Currency Quotes

Some companies present prices in one currency and settle in another. When the company is configured to pass the currency spread on to the buyer, the buyer is charged more than the commercial price — and that final amount must be shown to them and confirmed before authorization. The hosted Checkout does this on its own. Everywhere else — the Payment Element, a direct API integration, your own payment page — the screen belongs to you, so the guarantee is contractual: you create a quote, display it, and pass its id when creating the transaction.

This page only applies to companies configured for buyer-paid currency spread. If your company absorbs the spread, nothing changes: keep creating transactions exactly as you do today.

The flow

Create the quote

Call POST /v2/fx/quotes with the commercial amount, the currency you present to the buyer, and the payment method you will charge.

curl -X POST https://api.pagou.ai/v2/fx/quotes \
  -H "Authorization: Bearer $PAGOU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1029" \
  -d '{ "amount": 1000, "currency": "BRL", "payment_method": "pix" }'

{
  "data": {
    "id": "0198f3a0-1c2d-7e00-9a3b-6f8a2c4d1e5f",
    "presented_currency": "BRL",
    "wallet_currency": "USD",
    "payment_method": "pix",
    "base_rate": "0.2000000000",
    "spread_bps": 500,
    "presented_amount": 1000,
    "spread_amount": 50,
    "buyer_charged_amount": 1050,
    "expires_at": "2026-08-13T12:05:00.000Z"
  }
}

Amounts are integers in the currency’s smallest unit. Idempotency-Key is optional; repeating a call with the same key returns the same quote instead of freezing a second rate.

Show the buyer what they will pay

Before the buyer authorizes, your page must display:

the final amount (buyer_charged_amount), in the charged currency, as the prominent figure — it must equal what gets authorized;
the commercial amount (presented_amount) and its currency, when different;
the applied rate (base_rate) and the destination currency;
a neutral, consistent label.

Never:

call it a tax, IOF, MDR, card fee, or network fee — it is none of those;
present it as a choice the buyer makes;
change the amount between confirmation and authorization;
reveal the spread only after the buyer picks a payment method.

The last two are not stylistic. An amount that changes after confirmation, or a markup that appears only once a method is chosen, changes what the charge legally is.

Create the transaction with the quote

Pass fx_quote_id on POST /v2/transactions. The charge uses the rate frozen in the quote, not the current one, so the buyer is authorized for exactly the amount they confirmed.

{
  "amount": 1000,
  "currency": "BRL",
  "method": "pix",
  "fx_quote_id": "0198f3a0-1c2d-7e00-9a3b-6f8a2c4d1e5f",
  "buyer": { "name": "...", "email": "..." }
}

amount stays the commercial amount — the same one you quoted. The buyer-facing total is derived from the quote; sending it here would be quoting one figure and charging another.

With the Payment Element

The Element tokenizes the card and handles 3DS; it never renders an amount. So the quote lives in your own flow, around submit:

const quote = await fetch("/api/fx-quote", { method: "POST" }).then((r) => r.json());

renderTotal(quote); // your UI, following the display rules above

const result = await elements.submit({
  createTransaction: ({ token }) =>
    fetch("/api/pay", {
      method: "POST",
      body: JSON.stringify({ token, fx_quote_id: quote.id }),
    }).then((r) => r.json()),
});

Your backend forwards fx_quote_id to POST /v2/transactions.

Errors

code	what happened
`FX_QUOTE_REQUIRED`	The company passes the spread to the buyer and no `fx_quote_id` was sent. Create a quote, show it, and retry.
`FX_QUOTE_EXPIRED`	The quote lapsed. Create a new one and confirm the new total with the buyer — never reuse the old figure.
`FX_QUOTE_REUSED`	The quote already authorized another transaction. Quotes are single-use.
`FX_QUOTE_AMOUNT_MISMATCH`	The transaction amount differs from the quoted commercial amount.
`FX_PASSTHROUGH_NOT_ALLOWED`	This method and currency are not approved for passing the spread to the buyer.
`503`	No usable exchange rate. The charge is refused rather than converted at a made-up rate — retry shortly.

Notes

Quotes are single-use and expire with the rate that produced them; expect to create one per checkout attempt.
A quote belongs to one company. Quotes from another company return 404.
Same presented and wallet currency means there is no currency conversion, and POST /v2/fx/quotes returns 422.

Start with Payment Element

Build a Card Checkout

Launch and Migrate

The flow

With the Payment Element

Errors

Notes

​The flow

​With the Payment Element

​Errors

​Notes

The flow

With the Payment Element

Errors

Notes