Amounts and currency

Amount

All amounts are represented as an integer (maximum 12 digits) number in the minor unit of the currency, as defined by ISO 4217. For example, for Euro (EUR) the amount is expressed in cents, so an amount of 1.00 EUR is represented as 100. For Japanese Yen (JPY) the amount is expressed in yen, so an amount of 1.00 JPY is represented as 1. Floating point numbers are not used in the API, as they can lead to rounding errors. The amount is always a positive number, and the sign of the amount is determined by the context in which it is used.

Authorized amount

Amount that was authorized by the acquirer. This can be larger than the initially requested amount if surcharge or tip is added to the transaction. This can also be less than the initially requested amount, if partial authorization is requested and the customer has insufficient funds for the full amount.

Captured amount

Amount that was captured from customer account. This is the final amount that the merchant will receive from the transaction. It should be equal or less than the authorized amount, which can be more than the requested amount in case of surcharge or tip. The client can capture less than the authorized amount, for example in cases where the final amount is not known at the time of authorization, such as for vending machines or gas stations. The captured amount can also be zero, in which case the transaction is voided.

Cashback amount

Amount of cashback given to the customer. This is the portion of the purchase amount that is given to the customer in cash. The cashback amount must be included in the requested amount and therefore cannot exceed requested amount.

Cashback is only allowed in certain situations so usage of it needs to be specifically agreed upon and unless the terminal has been enabled for cashback, requesting a non-zero cashback amount will cause the transaction to be rejected.

Refundable amount

The total sum of refunds that can still be accepted for this transaction. This value can keep on changing after transaction completion if new refunds are performed that refer to this transaction.

Requested amount

Amount that was requested for the transaction. This is the amount that the customer was asked to pay initially. The final transaction amount may be higher in case of surcharges or tip, or lower in case of partial authentication or capture. The amount should include cashback amount if cashback was requested.

Surcharge amount

Amount of surcharge that was added to the transaction. There may be a surcharge configured separately for certain card types which will be added on top of the normal purchase amount depending on the card type. The customer will be asked to accept any surcharge on the terminal. The surcharge amount is added to the requested amount before the transaction is sent to the acquirer.

Tip amount

Amount of tip that was added to the transaction. Whether the customer is prompted to tip or not is selected in the terminal configuration. The customer will select the tip amount on the terminal. The tip amount is added to the requested amount before the transaction is sent to the acquirer.

Total amount

Current total amount for the transaction, which may change during the lifetime of the transaction. Initially this is the same as requested amount. It will change to be authorized amount on successful authorization. Finally it will change to be captured amount upon confirmation.

Currency

The currency code for all transaction amounts is the value of the transaction.currency field, unless DCC is used (see DCC).

DCC

If DCC is used, the transaction will have a transaction.dcc field with details about the currency conversion. Then transaction.dcc.customer_currency is the currency that the customer paid in, while transaction.currency is the currency that was credited to the merchant.

Examples of currency codes