Exchange Rate

Lock the FX rate before sending payouts. Get a reusable exchangeRateId that guarantees the same exchange rate across multiple payout requests, regardless of the amount.

📘
This feature requires activation.
FX rate lock must be enabled for your account and destination country. Contact your Bamboo account manager to request access.

How it works

When you request a rate lock, Bamboo freezes the exchange rate at that moment and returns an exchangeRateId. You can then reference that id in any Create Payout request to apply the locked rate — for any amount — until it expires.

Call POST /api/payout/exchangerate with exchangeRateLock: true.
Receive an exchangeRateId and a validUntil timestamp.
Include exchangeRateId in your POST /api/payout requests.
The locked rate is applied to every payout that uses that id until it expires.

⚠️
The lock applies to the exchange rate only.
Fees are always calculated at the time each payout is created, using the rules in effect at that moment.

Choose your environment

Environment	Endpoint
Staging	`https://payout-api.stage.bamboopayment.com/api/payout/exchangerate`
Production	`https://payout-api.bamboopayment.com/api/payout/exchangerate`

🧪
To test this endpoint, use the API Reference or the Postman Collection.

Request

Send a POST with your credentials and the currency pair you want to quote.

Request Parameters

Field	Type	Required	Description
`originalCurrencyIsoCode`	`string(3)`	Yes	ISO code of the origin currency.
`destinationCountryIsoCode`	`string(2)`	Yes	ISO 3166-2 code of the destination country.
`destinationCurrencyIsoCode`	`string(3)`	Yes	ISO code of the destination currency.
`amount`	`number`	No	Reference amount in the origin currency, used only for informational fields in the response. Defaults to `1` if not sent. Does not affect the locked rate.
`exchangeRateLock`	`boolean`	No	Send `true` to request a locked rate. Defaults to `false`. If the feature is not enabled for your account and country, the call still succeeds and returns the rate unlocked.

Request Examples

With amount and lock

{
  "amount": 300,
  "originalCurrencyIsoCode": "USD",
  "destinationCountryIsoCode": "UY",
  "destinationCurrencyIsoCode": "UYU",
  "exchangeRateLock": true
}

Rate check only (no lock)

{
  "originalCurrencyIsoCode": "USD",
  "destinationCurrencyIsoCode": "UYU",
  "destinationCountryIsoCode": "UY"
}

Response

Parameter	Format	Description
`exchangeRate`	`number`	Exchange rate between the origin and destination currencies (up to 5 decimal places). This is the value locked when `exchangeRateId` is returned.
`exchangeRateId`	`string`	Id that locks the rate. Only returned when `exchangeRateLock` is `true` and the feature is enabled for your account and country. Reusable with no usage limit until it expires.
`amountInOriginalCurrency`	`number`	Amount used for the informational calculation — the value sent, or `1` by default.
`amountInLocalCurrency`	`number`	Result of `amountInOriginalCurrency × exchangeRate`. Informational only — has no effect on the locked rate or on future payout amounts.
`originalCurrencyIsoCode`	`string(3)`	Origin currency this exchange rate applies to.
`destinationCurrencyIsoCode`	`string(3)`	Destination currency this exchange rate applies to.
`destinationCountryIsoCode`	`string(2)`	Destination country this exchange rate applies to.
`validUntil`	`datetime`	UTC-0 timestamp until which `exchangeRateId` remains valid. `null` when no lock was granted.
`errors`	`object`	Errors that may appear, in the same format used across the Payouts API. Review the Error Codes.
`errors` → `ErrorCode`	`string`	Internal code of the error.
`errors` → `PropertyName`	`string`	Property that triggered the error.
`errors` → `Message`	`string`	Error description.

Response Examples

Lock granted

{
  "exchangeRate": 40.00000,
  "exchangeRateId": "fx_8f3a1c9e2b4d4f7c9a0e1d2c3b4a5f60",
  "amountInOriginalCurrency": 300,
  "amountInLocalCurrency": 12000,
  "originalCurrencyIsoCode": "USD",
  "destinationCurrencyIsoCode": "UYU",
  "destinationCountryIsoCode": "UY",
  "validUntil": "2026-06-17T18:30:00Z",
  "errors": null
}

No lock (feature not enabled or exchangeRateLock not sent)

{
  "exchangeRate": 40.00000,
  "exchangeRateId": "",
  "amountInOriginalCurrency": 1,
  "amountInLocalCurrency": 40,
  "originalCurrencyIsoCode": "USD",
  "destinationCurrencyIsoCode": "UYU",
  "destinationCountryIsoCode": "UY",
  "validUntil": null,
  "errors": null
}

Use the locked rate in a payout

Once you have an exchangeRateId, include it in your Create Payout request. The payout amount can be anything — the locked rate is applied regardless.

{
  "exchangeRateId": "fx_8f3a1c9e2b4d4f7c9a0e1d2c3b4a5f60",
  "country": "UY",
  "amount": 5000,
  "currency": "USD",
  "destinationCurrency": "UYU",
  "type": 2,
  "reference": "PAY-2026-00099",
  "reason": "Supplier payment",
  "notification_Url": "https://yoursite.com/webhook/payouts",
  "payee": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "[email protected]",
    "phone": "094123456",
    "document": {
      "type": "CI",
      "number": "12345678"
    },
    "bankaccount": {
      "number": "001234567890",
      "type": 1,
      "codebank": "999"
    }
  }
}

⚠️
Important

The exchangeRateId is valid only for the exact currency pair and destination country it was issued for. Using it with a different country or currency returns error 821.

Once validUntil has passed, the id returns error 822. Request a new quote to continue.

A single exchangeRateId can be reused across an unlimited number of payouts while it has not expired.