The Payout Preview returns the final amount the payee would receive (in local currency) and the expected payment date, without creating a payout.

⚠️
Important: The preview is informational only. It does not freeze the FX rate. The rate is fixed only when you submit the payout.

Choose your environment

Bamboo provides two environments for payout preview requests:

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

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

Build the Request

Request Parameters

The following table shows the mandatory and optional parameters for the Payout preview.

Field	Type	Mandatory?	Description
`amount`	`number`	Yes	Amount of the Payout, the format has two digits for decimals. Example 100 → $ 1,00.
`destinationCountryIsoCode`	`string(2)`	Yes	ISO code of the country in the format `ISO 3166-2`. List of countries available for Payouts.
`destinationCurrencyIsoCode`	`string(3)`	Yes ^*	ISO code of the destination currency. Find the currencies list here
`originalCurrencyIsoCode`	`string(3)`	Yes	ISO code of the origin currency. Find the currencies list here

^*If the parameter is not provided, the system will default to the currency of the destination country (parameter destinationCountryIsoCode).

Request Example

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

{
  "amount": 1000,
  "destinationCountryIsoCode": "CO",
  "destinationCurrencyIsoCode": "COP",
  "originalCurrencyIsoCode": "USD"
}

Response

Parameter	Format	Description
`amountInOrignalCurrency`	`number`	Value requested in the Payout preview.
`fee`	`number`	Amount charged by Bamboo to process the Payout. You or the payee can assume the fee according to your contract.
`amountToBeSentInOrignalCurrency`	`number`	The amount to be sent to the Payee, which is calculated as the difference between `amountInOrignalCurrency` and `fee`.
`exchangeRate`	`number`	Conversion value between the origin and target currencies. This parameter includes up to `5` decimal places.
`amountToBeSentInLocalCurrency`	`number`	The amount received by the payee, calculated by multiplying `amountToBeSentInOriginalCurrency` by `exchangeRate`.
`expectedPaymentDate`	`datetime`	Indicates the estimated date of payment.
`validUntil`	`datetime`	Indicates the time until the exchange rate will be fixed; after this time the exchange rate can change. The time shown is UTC-0.
`errors`	`object`	Errors that may appear. The error codes for this method start with `6`. Review the Error Codes for Payouts.
`errors` → `ErrorCode`	`string`	Internal code of the error.
`errors` → `PropertyName`	`string`	Property that triggered the error.
`errors` → `Message`	`string`	Error description.

Response Example

{
  "amountInOrignalCurrency": 5.09,
  "fee": 0,
  "amountToBeSentInOrignalCurrency": 5.09,
  "exchangeRate": 39.3664547250,
  "amountToBeSentInLocalCurrency": 200.37,
  "expectedPaymentDate": "2024-09-12T00:00:00Z",
  "validUntil": "2024-09-10T15:19:17Z",
  "error": null
}

Test the API

Once you’re familiar with how to request a preview, test your integration in the API Reference

Country Requirements

Check what each country requires (documents, bank formats, supported currencies).

API Reference

Explore full request and response examples

Create a Payout

Send the request to create the payout after previewing the amount and fees.