> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Exchange Rates in Payments & Settlement

> Which rate a cross-currency order uses, when it is quoted and re-quoted, why the local amount changes at midday UTC+8, where the applied rate appears in the API and the Portal, and how settlement and refunds each pick their rate.

[Amounts and currencies](/docs/en/developer-docs/core-concepts/currency) says Waffo converts
cross-currency orders automatically. This page is the mechanics behind that sentence: which rate,
quoted when, visible where, and what happens at settlement and on a refund.

## Which exchange rate does a cross-currency order use?

An order is cross-currency when your `orderCurrency` differs from the currency the customer actually
pays in. Waffo quotes a rate for that currency pair — order currency as the base, payment currency
as the quote — for the payment method being priced, then applies the markup agreed in your contract:

```
payable amount = orderAmount × base rate × (1 + contracted markup)
```

The result is then rounded **up** to what the payment currency and the payment method accept — some
methods take only whole multiples or a fixed number of decimals — and the rounding difference is
carried as a separate adjustment component rather than folded into the rate.

## Why is the local amount different in the morning and the afternoon?

Because the standard daily rate is not a calendar-day rate. Each rate window runs for a day but
rolls over at a **fixed time of day (UTC+8) that is not midnight**, so an order priced before the
switch and an order priced after it use different rates for the same currency pair even though they
fall on the same calendar date.

Two qualifiers: every quoted rate carries its own validity and expiry, so the daily rollover is the
normal refresh point rather than a guarantee that a rate cannot be superseded inside the window; and
your contracted markup is effective-dated in its own right, independently of the rate window.

## Is the rate locked, and for how long?

There is no rate-lock product to buy or enable. What exists is a snapshot:

* The rate is quoted **when the payable amount is priced**, and stored on the order together with a
  rate reference and its expiry.
* If the payable amount is **recalculated at the cashier** — for example a promotion code changes the
  order amount, or the shopper switches payment method — the FX is re-quoted at that moment. The
  amount displayed when the shopper submits is the amount charged.
* A later **capture** on an authorised order reuses the order's stored rate. It is not re-quoted.

## Does Waffo have an exchange-rate query endpoint?

No. There is no rate-quote endpoint, no rate-lock endpoint, and no separate FX-locking service to
request access to. Do not build against one. Rates reach you as part of the order:

| You want | Use |
| - | - |
| The rate applied to one order | `orderAction.actionData.exchangeRate` on the create response, or `POST /api/v1/order/inquiry` |
| The amount the customer will pay | `paymentAmount` / `paymentCurrency` in the same `actionData`, or `finalDealAmount` on inquiry |
| Rates across many transactions | Portal settlement reports and exports, not an API call |

## There are two `exchangeRate` fields. Which is which?

| Field | Whose rate | Read it as |
| - | - | - |
| `orderAction.actionData.exchangeRate` | Waffo's applied rate for this order | Documented as `paymentAmount ÷ orderAmount` when order currency and payment currency differ |
| `payMethodInfo.exchangeRate` | The payment method's own rate during the customer's payment | Informational — what the wallet or bank used on its side, alongside `userPaymentAmount` / `userPaymentCurrency` |

Where a customer-paid service fee applies, it is returned separately as `userFeeAmount` /
`userFeeCurrency`. Account for it before treating any ratio of two amounts as a pure FX rate.

## Where do I see the rate in the Portal?

| Portal location | Field | Covers |
| - | - | - |
| Transaction detail | `Payment Amount` with its currency | The customer-facing amount; no rate field — the rate is implied against the order amount |
| Settlements → Estimation | `Forex Currency Pair`, `Est. Forex Rate` | The **estimated** conversion for orders not yet settled |
| Settlements → Settlement Batch | `Exchange rate`, shown as *original amount = target amount* | The conversion that actually executed, per order currency |
| Settlement reports | `Forex Currency Pair`, `Forex Rate` | Per transaction, in batch detail and customised exports |

Estimation is a menu-permission-driven page: if it appears in your Portal navigation, it is available
to your account. Its figures carry an `Est.` prefix for a reason — computed before settlement runs,
they can still move.

## Is my settlement converted at the order's rate?

No. Settlement conversion is a **separate event** with its own rate, applied when the settlement is
processed — not the rate stored on the order. That is why `Settlement Original Amount` (netted in the
order currency) and `Settlement Target Amount` (the same money after conversion) sit in different
currencies on the batch, and why the target amount is empty until conversion completes.

`Forex Currency Pair` also appears on settlement rows where your order currency already matches your
settlement currency, because fees and taxes can be billed in a third currency. The pair is resolved by
a fixed priority order, and `Forex Rate` is empty whenever the pair is empty — both are set out in
[Settlement Reports & Exports](/docs/en/support/settlement-reports-faq).

## Which rate does a refund use?

Always the **original order's stored rate**, never a fresh quote. A rate move between the payment and
the refund does not change the local amount the customer gets back.

| Refund | How the customer-facing amount is derived |
| - | - |
| Full refund | From the original payable amount, with the customer-paid fee and tax components removed |
| Partial refund | The refunded order amount converted proportionally at the order's FX-only rate |

Refund amounts are rounded **down** to the payment currency's precision — the opposite direction from
order pricing — so a refund can never exceed the original payable amount, and one whose converted
amount rounds to zero is rejected rather than sent. The rounding rules across several partial refunds
are in the [Refund FAQ](/docs/en/support/refund-faq).

***

Reconciling a specific figure? [Contact support](mailto:support@waffo.com) with the order id — the
applied rate, the payable amount and the rounding adjustment are all stored against it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.