Charges

Charges represent a payment by your users, and have a wealth of data associated with it. Each charge has an associated checkout, which is a hosted page where a user can perform the payment. You'll need to redirect your users there so they can pay the charge. Note that charges (and it's associated checkouts) expire after a determined amount of time. Any payment done after the expiry of the charge will be refused.

note

To understand the difference between PAID and CONFIRMED status later on, just bear in mind that a PAID orders mean that the payment was sent, while CONFIRMED means the payment is successful and the funds are in your account. If you are familiar with credit cards payment processing, they are the equivalent to AUTHORIZED and CAPTURED payments using credit cards.

Note that, contrary to usual fiat working, cryptocurrency payments can't be reversed. Once the funds hit your account, they are yours and can't be taken away.

tip

Payments done from Criptan by your client are instantaneous and automatically confirmed, and are even faster and more secure than a normal cryptocurrency or credit card payment.

Create charge

To request a cryptocurrency payment, you create a charge. Since cryptocurrency payments are push payments, a charge will expire after a waiting period (payment window) if no payment has been detected. Charges are identified by a unique code.

HTTP Request

POST https://api.criptan.es/business/charge

Request arguments

Parameter	Type	Required	Description
currency	string	Required	Fiat currency identifier (e.g: 'EUR')
amount	number	Required	Amount charged in fiat currency
description	string	Required	Description of the payment
products	array	Required	An array of JSON object that contains information about what you are charging the user
product.title	string	Required	Name of the product
product.description	string	Optional	Description of the product to be sold
product.image	string	Optional	URL to the image of the product. Will be replaced by a placeholder if ommited
product.quantity	number	Required	Number of items you are selling
product.price	number	Required	Individual price of each product
metadata	object	Optional	A JSON object that contains any metadata you want to include about your order
ttl	number	Optional	The number of minutes your user has to pay the charge. Minimum: 5 minutes, Maximum: 60 minutes

tip

Your metadata object has to be stringifable. If it is not, charge creation will fail.

Response

{

id: string; // uuid of the charge generated

checkout: string; // hosted page for the checkout associated with this charge

createdAt: string;

expiresAt: string;

paymentStatus:

/** Payment has been created, but a payment still haven't been made. */

'PENDING' |

/** Payment has been made and has been detected, but it hasn't been confirmed yet. */

'PAID' |

/** Payment has been confirmed. */

'CONFIRMED' |

/** Payment has expired without a payment being made. */

'EXPIRED' |

/** User has sent less than the specified amount. */

'UNDERPAID' |

/** The payment was made after the specified time. */

'DELAYED' |

/** A refund has been requested, but it hasn't been resolved yet. */

'REFUND_PENDING' |

/** Payment has been sucessfully refunded. */

'REFUNDED'

;

products: {

title: string;

price: number;

quantity: number;

image?: string;

description?: string;

}

pricing: {

fiat: {

amount: string;

currency: 'EUR';

}

BTC: {

amount: string;

currency: 'BTC';

address: string;

}

ETH: {

amount: string;

currency: 'ETH';

address: string;

}

LTC: {

amount: string;

currency: 'LTC';

address: string;

}

}

description: string;

processStatus:

/** Processing of the payment hasn't been initiated */

'UNPROCESSED' |

/** Process has been initiated (Cryptocurrency has been sold, but still awaiting confirmations to finish it) */

'INITIATED' |

/** Processing has finished and the fiat currency has been transferred to the user. */

'PROCESSED' |

/** There has been an error while processing the payment. */

'ERROR'

;

metadata?: Record<string, unknown>;

}

Generate QR code

If you don't want to use the provided payment page, you can use the data received from charge creation to generate a QR code and address for payment. The procedure depends on each coin, but for BTC (the only accepted coin at this time) you can use the following:

// Data is data received from creating a charge

const data = {

address: '3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5',

amount: '1'

}

const qrCode = bitcoin:${data.address}?amount=${data.amount}

warning

If you alter the amount field from the response, the system will either register the charge as underpaid (if lowering the amount) or the amount overpaid (if making the amount bigger) will be lost!

You don't need to include fees: they are automatically included when the user scans the wallet.

Get information about a charge

If you want to retrieve information about a charge, you can do so using using a GET and the UUID of the payment

HTTP Request

GET https://api.criptan.es/business/charge/{id}

Response

{

id: string, // uuid of the charge

createdAt: string, // ISO timestamp of the creation date

expiresAt: string, // ISO timestamp of the expiration date

paidAt?: string, // ISO timestamp of when the charge was paid

confirmedAt?: string, // ISO timestamp of when the charge was confirmed (has at least 1 confirmation in the blockchain)

refundRequestedAt?: string, // ISO timestamp of the refund petition from the user

resolvedAt?: string, // ISO timestamp of when the refund was resolved (either granted or denied)

refundPaidAt?: string, // ISO timestamp when the refund took place (payment was sent)

canceledAt?: string, // ISO timestamp of the cancellation

pricing: {

fiat: {

amount: number // amount asked in fiat currency

currency: string // currency code of the fiat currency

},

BTC: {

amount: string, // Crypto currency amount asked. Note that, due to the size of some numbers it is recommended to treat them as strings to prevent floating point errors.

currency: string // Crypto currency code code

address: string

}

...

// Other supported crypto currencies pricing options

},

redirect_url?: string, // url of the hosted payment page

status: string, // Status of the charge. Possible status include: PENDING, PAID, CONFIRMED, CANCELED, REFUND_REQUESTED, REFUND_PAID, REFUND_APPROVED

metadata?: {[key: string]: unknown}, // Any metadata passed as part of the request.

transaction: {

id?: string, // Transaction id in its respective blockchain

currency?: string, // Crypto currency code

amount?: string, // Crypto currency amount paid. Note that, due to the size of some numbers it is recommended to treat them as strings to prevent floating point errors.

confirmations?: number // Number of confirmations the transaction has received

}

}

tip

Payments done from Criptan by your client are instantaneous and automatically confirmed, and are even faster and more secure than a normal cryptocurrency or credit card payment.