Which amount fields does an order carry?
All amounts are strings, not numbers — the published reason is float precision:
0.1 + 0.2
is not 0.3, which is unacceptable for money. Parse them as decimals.
How should I verify that an order is the one I created?
CompareorderAmount + orderCurrency against the values you sent, keyed by your own
paymentRequestId or merchantOrderId. Those two fields are your own input echoed back, so
they are the only pair that is guaranteed to equal what you asked for.
Do not verify by comparing finalDealAmount to your expected amount. It is a different
quantity by design, and two entirely normal situations make it differ — which is the next
question.
Why is finalDealAmount different from orderAmount?
The API contract names two reasons, and both are normal:
- Your order currency is not the user’s payment currency. A cross-currency order is priced by you in one currency and paid by the user in another, so the two numbers are in different units and will not match.
- The user paid an additional service fee. Where the payment method charges the payer a
fee, that fee is included in
finalDealAmount, so it is larger than your amount.
finalDealAmount answers “what did this cost the user”, and orderAmount answers
“what did I charge”. Ship goods and run business validation against orderAmount; use
finalDealAmount only when you want to show the user what they paid.
Can orderCurrency and userCurrency really be different?
Yes — that is exactly what a cross-currency order is: you price in your own currency and the
user pays in theirs. It is not an error state and it is not limited to any one payment-method
category. The published definition and the parameters that go with it are in
Amounts and currencies; the practical rule for
order creation is that a cross-currency order needs payMethodCountry when you have not
pinned payMethodType or payMethodName, while userCurrency itself stays optional.
If your reconciliation assumes one currency per order, build for three fields from the start:
orderCurrency (yours), userCurrency / userPaymentCurrency (the user’s), and your
settlement currency (see Settlement calculation explained).
They are three separate things and only the first is under your control at order time.
What exactly did the user pay, in their own currency?
paymentInfo.payMethodResponse.userPaymentAmount with
paymentInfo.payMethodResponse.userPaymentCurrency. That block is the payment method’s own
view of the transaction and also carries:
It is a JSON string, and which keys are present depends on the payment method — read it
defensively rather than assuming a fixed shape.
Can I compute the user’s net payment as finalDealAmount minus the user fee?
No — not from the inquiry response. userFeeAmount and userFeeCurrency are returned in
orderAction.actionData on the order-create response, not as top-level fields on Order
Inquiry or in the payment notification. So at the moment you are reconciling, you generally
do not have the fee as a separate number to subtract, and a subtraction across two currencies
would be wrong anyway.
Use instead:
- Did I get charged the right amount? →
orderAmount+orderCurrency. - What did the user pay in total? →
finalDealAmount, oruserPaymentAmountfor the payment-method-side figure. - What was the fee? → capture
actionData.userFeeAmountat create time and store it, if you need it later.
Is a user fee only charged on over-the-counter payments?
The API does not scope it that way.userFeeAmount / userFeeCurrency live in
orderAction.actionData, which is the block for merchants building their own checkout, and
nothing in the contract restricts them to one payMethodType. Treat a payer fee as possible
on any method and read the field, rather than deciding by method category — the same advice as
for finalDealAmount: read it, do not infer it.
If you use the Waffo checkout page, the user sees the fee on the checkout itself; you do not
have to render it.
What is originalAmount, and which amount do I validate a discount against?
originalAmount is the order amount before a discount was applied. When a promotion code
or coupon has been used, orderAmount is the discounted, payable amount and originalAmount
is the pre-discount figure you priced.
So for business checks — entitlement, fulfilment, “did they pay enough for this SKU” — use
orderAmount, because that is what was actually charged. Use originalAmount only for
display or for measuring discount impact. Coupon and promotion-code mechanics, including what
happens to a discount on refund, are in
Coupons & Promotion Codes.
Which amount should I reconcile my finances against?
NeitherorderAmount nor finalDealAmount on its own — those are order-level fields, before
fees and before settlement conversion. For money reconciliation use the settlement reports,
which carry the amount, the fees and the settlement currency together:
Settlement reports and
Settlement calculation explained.
The order-level fields are for order reconciliation — proving that the order you created is
the order that was paid. Keep the two exercises separate; that is the single most common cause
of “your numbers do not match mine”.
Do I have to create the order in the local currency?
No.orderCurrency is your pricing currency, and a cross-currency order — you price in
one currency, the user pays in another — is a supported, first-class flow. Whether a
particular payment method can serve a particular order currency depends on the contracts on
your account, which is a lookup, not a guess:
Because that response is keyed on contracts, one payment method can appear several times —
once per currency.
payMethodName is not a unique key. Details in
Payment Method Config & Limits.
A payment method is listed in one currency. Can I still price in another?
Read the two currencies separately:- Payment currency — what the user is charged in. For a local payment method this is effectively fixed by the method itself.
- Order currency — what you priced in, and what you are billed and settled on.
A0018, the contract-mismatch code, not as
a currency-specific error; see
Limits, Currency & Configuration Errors.
Where do I see the exchange rate for a cross-currency order?
Two different rates, two different fields:
They answer different questions and can differ. When the rate is fixed, for how long, and
which rate a refund uses are all in
Exchange Rates in Payments & Settlement.
How many decimals may I send, and does it depend on the currency?
Yes, it depends on the currency, and the rule differs between same-currency and cross-currency orders. The published rule: most currencies take two decimals per ISO 4217, a set of currencies must carry no decimals at all in a same-currency order, and in a cross-currency order every currency must follow its ISO 4217 precision with no exceptions. The full list and the rejection behaviour are in Amounts and currencies and Order Amounts, Limits & Declines. Per-payment-method amount ranges are a separate check from precision: they come fromorderAmountMin / orderAmountMax on the contract, so validate against those before you
create the order rather than discovering the limit from an error code.
Which amount fields does a refund carry?
remainingRefundAmount is the field to drive your own “can I still refund” logic from, rather
than recomputing it from your records — it already accounts for every refund on the order,
including ones you did not initiate yourself. Refund rules themselves are in
Refund FAQ and
Refund Limits by Payment Method.
Still not sure which field to compare? Contact support with your
paymentRequestId and the two numbers that disagree.