Amounts and Currencies
All monetary values in the Orchestration API use the same representation, whichever processor handles the payment.
Amounts Are in Minor Units
Every amount is a positive integer in the currency's minor unit, the smallest unit of that currency. For example, 1099 in USD means $10.99. Don't send decimal values or strings.
The number of decimal places depends on the currency:
Decimal places | Example currencies | Example |
|---|---|---|
2 (most currencies) | USD, EUR, GBP, AUD | 1099 USD = $10.99 |
0 | JPY, KRW, CLP, VND, XAF, XOF | 1099 JPY = ¥1,099 |
3 | BHD, JOD, KWD, OMR, TND | 1099 KWD = 1.099 KWD |
Forter converts amounts to each processor's expected format, so you always send the same representation.
Amounts inside order details, such as cartItems[].price, shipping.deliveryPrice, tax.amount and discounts[].amount, use the same minor-unit representation.
Currency Codes
currency is a three-letter ISO 4217 code in uppercase, for example USD. Lowercase codes are rejected. Responses and webhooks always return uppercase codes.
Which currencies you can process depends on the processors configured for your site. If no configured processor supports the payment's currency, the create request fails with error code PAYMENT_UNSUPPORTED_CURRENCY.
Amounts in Operations
Request | What amount means |
|---|---|
POST /api/payments | The payment total (required). |
POST /api/payments/{id}/capture | The amount to capture. Omit it to capture everything that is still authorized. |
POST /api/payments/{id}/cancel | The part of the hold to release (partial cancel). Omit it to release the whole authorization. |
POST /api/payments/{id}/adjust-authorization | The new total the authorization should hold (required). |
POST /api/payments/{id}/reauthorize | The amount the new or adjusted authorization should hold. Omit it to renew the current amount. |
POST /api/payments/{id}/refunds | The amount to refund. Omit it to refund everything remaining on the capture. |
Every amount must be at least 1. Requests that exceed what is available, such as capturing more than is authorized or refunding more than was captured, are rejected and leave the payment unchanged.
On the payment itself, amount, authorizedAmount, capturedAmount and refundedAmount show where the money stands. See Payment Lifecycle.