# Amounts, currency and FX

Keep requested, provider-reported, credited and settlement values separate.

Canonical: https://docs-firehorsepay.powerwebhub.com/guides/amounts-fx
Updated: 2026-11-22; API v1

## Use major currency units

The merchant API uses major units: 10.00 EUR is ten euros. Prefer decimal strings and decimal arithmetic on your server. Currency exponents differ, for example JPY has zero decimal places and KWD has three.

Provider adapters convert to minor units only when their amount format requires it. Do not multiply merchant API amounts by 100.




## Read the amount breakdown



1. requestAmount/requestCurrency preserve the original merchant request.
2. convertedAmount/convertedCurrency and conversionRate/source/at describe the FX snapshot when conversion applies.
3. providerAmount/providerCurrency describe what was requested from the provider.
4. actualAmount/actualCurrency describe what the provider reported paid.
5. creditedAmount/creditedCurrency describe what the merchant was credited under its configured policy.
6. settlementAmount/settlementCurrency are separate recorded values. They are not proof of a bank payout or bank statement reconciliation.


## Handle differences explicitly

amountUpdateType can be EXACT, WITHIN_TOLERANCE, OVERPAYMENT, UNDERPAYMENT, AMOUNT_REVIEW or INVALID. Review status requires operator handling; do not treat it as SUCCESS. The merchant policy decides credit/reject/review behavior.

FX uses the create-time snapshot, not a fresh callback-time rate. A missing or expired required rate returns 422 FX_RATE_UNAVAILABLE without creating a transaction. Refund amount is validated against creditedAmount when available.


- [Transaction response](https://docs-firehorsepay.powerwebhub.com/api/get-transaction)
- [Full refund action](https://docs-firehorsepay.powerwebhub.com/api/refund)