How to Handle Currency Conversion in Your Payment API

Identify whether the API prices, books or delivers#

A currency conversion payment API may return a display amount, offer an executable FX quote, book a conversion or initiate a recipient payment. Those operations have different consequences. Choose the operation you need and record its actual result; a successful rate response does not prove any money moved.

Begin with the obligation and supported accounts: whose funds are being converted, which currency amount is fixed, which account receives the converted funds and whether a separate beneficiary payment is required. A Merchant of Record arrangement, bank receiving details and a payout product describe different parts of a money path. None defines a universal FX request contract.

Four results with different evidence#

The ECB reference-rate page says its rates are for information and strongly discourages transaction use. Such a feed can support a clearly labeled reference display. It should not be presented as a provider’s guaranteed execution quote.

Current examples show why API names are insufficient#

As checked on October 3, 2026, Amazon Payment Services’ currency-conversion guide describes conversion for shopping-phase price display. Checkout’s final amount is in the merchant-account currency; the eventual card-currency conversion can differ from the estimate. A CURRENCY_CONVERSION response is therefore not evidence of a booked treasury trade or contractor payout.

Currencycloud’s conversion guide distinguishes an indicative detailed-rate quote from booking a conversion. Its example booking returns a conversion record that can be awaiting_funds. Do not turn booking acceptance into target-balance availability or recipient delivery. Track the relevant funding and settlement states separately.

For a supported held-rate product, Currencycloud’s Held FX Rates guide describes creating a quote and then booking with its quote_id. Hold periods must be enabled for the account. Quotes are currently single-use and amount-specific, and supported currency pairs are limited. The response carries expires_at; the booking must match its currencies, fixed side and amount. These are product rules, not general promises for every FX API.

Decide separately whether you need a beneficiary payment after conversion. Confirm the provider supports the source owner, account structure, purpose, currencies and recipient destination. Preserve the conversion and payment references as separate records, even if a provider offers an orchestration endpoint for both.

Specify the fixed side and rate direction#

Record both source and target currency and amounts. Do not infer rate direction from a currency-pair label alone: an API may normalize pair notation using market conventions. Write the mathematical direction explicitly, such as EUR per USD, and use the returned confirmed buy/sell amounts when reconciling.

A fixed source amount answers how much target currency it buys. A fixed recipient amount answers how much source currency is needed after the relevant target-side deductions. Neither guarantees the other amount remains unchanged if an indicative price moves. Keep the agreed fee treatment and permitted tolerance with the obligation.

A worked example with source and recipient amounts#

Assume an invented rate of EUR 0.80 per USD and a EUR 5 deduction from the converted amount. Fixing USD 1,000 buys EUR 800 and delivers EUR 795 after that deduction. If the obligation is a net EUR 1,000, sending USD 1,000 would leave it EUR 205 short. These are hypothetical values, not current prices or provider fees.

To deliver net EUR 1,000 under those same assumptions, buy EUR 1,005. Required source amount is EUR 1,005 ÷ 0.80 = USD 1,256.25. If a separate source fee is USD 10, total source debit is USD 1,266.25. Show the EUR 5 deduction and USD 10 fee separately; do not subtract either twice or confuse the bought amount with the net recipient amount.

If the illustrative rate changes to EUR 0.79 per USD before an unbooked conversion, buying EUR 1,005 requires about USD 1,272.151899 before the source fee. A two-decimal source amount needs the provider’s specified rounding and final quote; ordinary display rounding is not enough to promise exactly EUR 1,000 net. Reapprove a changed price where the agreement requires it.

Serialize amounts for the selected endpoint#

Keep exact decimal arithmetic or integer units internally, and define each currency/endpoint’s scale and rounding rules. Convert to the provider’s required representation once at the boundary. Do not multiply a value already expressed in minor units, or send a currency symbol, thousands separator or locale-formatted display string.

The APS API reference also specifies service_command, currency, converted_currency and a SHA-256 signature. Those names, limits and signature rules belong to that API. Currencycloud’s documented request instead uses buy_currency, sell_currency, fixed_side and its own authentication. Implement the selected contract; do not copy one provider’s payload into another.

Check zero- and three-decimal currency handling and any documented product exceptions. Currency metadata and the payment endpoint can impose different operational precision. Record the amount intended, the serialized value and the confirmed result so a rounding difference can be investigated without recomputing historical money.

Separate quote identity from request identity#

A quote ID identifies price terms; a request key identifies a supported execution retry; a conversion ID identifies the resulting trade. Keep all three distinct. Reusable quotes and single-use quotes have different rules. A single-use quote must not become a new booking simply because a local worker did not receive the first response.

Currencycloud’s held-rate guide includes unique_request_id for booking idempotency. Confirm the actual endpoint, payload equality, key retention and recovery rules for the enabled product. Do not assume duplicate protection lasts forever or crosses account, environment or provider boundaries. Retain a durable internal execution intent and all provider references beyond any key window.

Resolve unknown execution before replacing an expired quote#

Before an unsent request, check the provider’s quote expiry and booking conditions. If it is no longer executable, request an approved fresh quote and disclose changed source/target amounts as required. That is different from recovery after an execution request has already been sent.

After a timeout, connection loss or ambiguous response, look up the original conversion using retained references and supported recovery mechanisms. Check funding and transaction records if needed. An expired quote, missing local response or unchanged display balance does not prove that no trade was booked. Hold automatic replacement while the original could have executed.

For a permitted retry of the same unchanged instruction, use the original request identity under the provider’s rules. Do not rotate a key, book from a fresh quote or change providers to push an unknown operation through. If lookup confirms a booked conversion awaiting funds, resolve its funding obligation; another conversion can create additional exposure rather than completing the first.

Once the original outcome is confirmed, proceed according to that result. An unexecuted instruction can receive a new approved quote. A booked trade may require a supported cancellation or amendment, potentially with a cost. A funded conversion followed by a failed recipient payment needs payment recovery using the available target funds, not an automatic second FX trade.

Record the business event at each stage#

Recognize each event under your accounting policy rather than waiting for the last recipient status before recording every earlier trade or cash movement. A pending payment is not permission to omit a confirmed conversion. Preserve actual debits, credits and fees even when later eligibility or validation raises an exception; route the discrepancy for resolution.

Verify callback authenticity using the selected provider’s rules, persist authenticated events durably and apply local financial effects once. Where practical, commit the processed marker with the ledger and state update atomically. Handle duplicate and out-of-order delivery using object history and reconciliation, not arrival order alone. Retain failed processing for recovery.

Give operators a useful reconciliation export#

• Internal obligation and execution-intent IDs, environment and account owner.
• Quote ID, request identity, conversion ID and separate payment ID where applicable.
• Source/target currencies, intended fixed amount, confirmed amounts, rate direction and fees.
• Funding, conversion and payment event times plus provider and bank references.
• Confirmed returns/adjustments, unresolved status, next investigation action and owner.

Use separate demo and live credentials, endpoints and records. Restrict keys and signing material to their intended server-side use. Keep safe diagnostic references and payload hashes rather than exporting secrets. Follow the provider’s signature construction and verification rules; the word SHA-256 alone does not define a complete authentication scheme.

Have engineering own serialization and durable processing, payments operations own unknown-outcome investigation, finance own reconciliation and the relevant control owner approve actual onboarding/payment requirements. The diagram shows those responsibilities; it does not establish a mandatory company structure or universal release gate.

Implement the contract and preserve the outcome#

Classify the API operation, fix the intended amount side and serialize for its documented contract. Preserve each quote, booking, funding and payment result. When execution is unknown, investigate the original before replacing it; reconcile actual movements and linked corrections so operators and finance can explain the same transaction.

For broader fee modeling, see calculating the all-in cost of an international payment.