Whenever a collection currency differs from your settlement currency, a rate is applied. This page covers where that rate comes from, when it is locked, and how to read it back.

When Conversion Happens

Conversion applies in two places:

At collection, when you price in settlement currency. If you send amountCurrency: "settlement", Kyshi converts your amount into the customer's local currency so the customer can be charged. See Countries And Currencies.

At settlement, when local proceeds are converted for payout. Collected local funds are converted into your settlement currency as part of the settlement batch. See Settlements.

These are separate conversions and may use different rates, because they happen at different times.

How The Rate Is Composed

Kyshi sources a market rate for each supported currency pair and applies a spread. The spread is configured per collection currency, so NGN and KES are not necessarily marked up identically.

The rate you receive is the spread-adjusted rate, not the raw market rate. You do not need to apply anything further to it.

Reading The Applied Rate

Every converted transaction reports the rate it used.

Field	Meaning
`meta.fxRate`	The rate applied to this transaction.
`meta.localCurrency`	Currency the customer was charged in.
`meta.localAmount`	Amount in the local currency.
`meta.settlementCurrency`	Currency you will be settled in.
`meta.settlementAmount`	Equivalent amount in your settlement currency.

Store meta.fxRate alongside your own record of the sale. When finance asks why a $10 sale settled at $9.87 six weeks later, the rate on the transaction is the answer.

Fetching Current Rates

To quote a price before creating a transaction:

-H "x-api-key: your_secret_key"

GET {{host}}/v1/config/rates

This returns the rate and fee that currently apply to your business, together with the relevant settings.

If your business has negotiated custom rates, read them from:

GET {{host}}/v1/config/custom/rates

See Rates and Custom Rates for the request and response detail.

Rates Move

A rate fetched from /v1/config/rates is indicative. It tells you what the rate is now, not what it will be when the customer eventually pays.

This matters most for flows with a gap between quoting and paying:

Flow	Gap between quote and payment
Hosted checkout	Minutes
Payment link	Hours or days
Virtual account	Until the customer gets round to transferring
Subscription renewal	A full billing period

For anything longer than a checkout session, do not treat a quoted rate as a promise to the customer. Either price in local currency so there is no conversion to drift, or make clear that the final amount is determined when payment is made.

If you must show a settlement-currency price on a long-lived link, re-quote before displaying it rather than caching the rate from when the link was created.

Subscriptions And FX

A subscription priced in settlement currency is converted at each billing cycle, so the local amount your customer sees can change from one renewal to the next. A customer in a volatile currency may see a noticeably different figure month to month.

If a stable local price matters more to you than a stable settlement price, create the plan with amountCurrency: "local". You then absorb the FX movement instead of the customer. See Plans.

Fees And Who Pays Them — what is deducted on top of conversion
Settlements — the second conversion point

FX And Rates