Create Payout

Payouts allow transferring funds from a Bamboo account to a recipient’s bank account, wallet, or instant payment system. This guide explains how to configure the environment, build the request, and test the API for payouts to individuals or companies.

Use the Staging or Production endpoints to initiate payouts, with properly formatted recipient, bank, and remitter data. For the full parameter list and error codes, see the API Reference →Create Payout.

📘
Some countries require extra fields (document type, bank format, purpose codes).
Check the Country Guides before sending payouts.

Choose your environment

Bamboo provides two environments:

Staging for simulations and homologation (recommended first).
Production for live payouts.

Staging https://payout-api.stage.bamboopayment.com/api/payout

Production https://payout-api.bamboopayment.com/api/payout

🔐
Authentication
All payout creation requests must include the authentication headers described in the reference guide. Make sure to generate the DigitalSignature using the HMAC SHA-256 algorithm and include it in the request headers.

Build the request

Send a POST with your credentials and the payout details.

Request Parameters

Parameter	Type	Required	Description
`country`	`string(2)`	Yes	ISO code of the country (ISO 3166-2).
`amount`	`integer`	Yes	Payout amount, with two implied decimals (e.g. `100` = $1.00).
`currency`	`string(3)`	Yes	Origin currency configured in your account.
`destinationCurrency`	`string(3)`	Yes	Currency received by the payee. Optional in USD2L and L2L models.
`reason`	`string`	No	Description of the payout.
`reference`	`string`	Yes	Unique identifier for the payout, defined by you.
`type`	`integer`	Yes	Payout type: `1` Cash `2` Bank Transfer `3` Wallet `4` Instant Payment (Pix o Bre-B)
`paymentCode`	`string`	Yes⁶	Payment purpose code in China.
`notification_Url`	`string`	No	Webhook endpoint to receive payout result notifications.

⁶ This field is required ONLY for China.

Payee Object

Parameter	Type	Required	Description
`payee` → `FirstName`	`string`	Yes¹	First name of the payee.
`payee` → `LastName`	`string`	Yes¹	Last name of the payee.
`payee` → `CompanyName`	`string`	Yes¹	Company name.
`payee` → `Email`	`string`	No	Payee’s email address.
`payee` → `Phone`	`string`	No	Payee’s phone number.
`payee` → `Birthday`	`date time`	No	Date of birth (YYYY-MM-DD).
`payee` → `Nationality`	`string`	No	Nationality (2-digit ISO code).
`payee` → `document` → `type`	`string`	Yes	Type of document (e.g., DNI, Passport).
`payee` → `document` → `number`	`string`	Yes	Document number of the payee.

¹ The fields firstName and lastName are mandatory for natural persons, and companyName is mandatory for legal entities (companies). If a payout is sent to a company, only the companyName field must be completed, and if a payout is sent to an individual, only the firstName and lastName fields must be completed..

⚠️
Important:

The fields firstName and lastName do not support numbers or special characters, only letters. The companyName field does accept all types of alphanumeric characters.

The length of the combined firstName and lastName fields or the companyName field cannot exceed 35 characters.

Payee → Location

Parameter	Type	Required	Description
`payee` → `location` → `city`	`string`	Yes²	City.
`payee` → `location` → `address`	`string`	Yes²	Street address.
`payee` → `location` → `zipCode`	`string`	No	Postal/ZIP code.

² These fields are mandatory only for bank transfers to Egypt.

⚠️
Important:

The field Location → City cannot exceed 20 characters.

The field Location → Address cannot exceed 35 characters.

Bank Account Object

Parameter	Type	Required	Description
`payee` → `bankaccount` → `number`	`string`	Yes³	Beneficiary’s account number (CBU, CLABE, CCI, etc.).
`payee` → `bankaccount` → `type`	`int`	Yes³	1 = Checking, 2 = Savings.
`payee` → `bankaccount` → `codebank`	`string`	Yes³	Bank code of the payee. Review the Bank List per country
`payee` → `bankaccount` → `swift`	`string`	Yes⁵	SWIFT/BIC code when required by the destination bank.

³ When using Bank Transfers for Argentina, Chile, Colombia, Mexico, Peru, and Uruguay, these parameters are mandatory. For Instant Bank Transfers in Brazil, the payee.bankaccount object and its parameters must not be included in the request. For Bank Transfers to countries that require the bankaccount.Swift field, only bankaccount.number should be completed, while bankaccount.type and bankaccount.codebank must be left empty..

⁵ These fields are required for bank transfers ONLY to the following countries:
Bolivia, Bosnia and Herzegovina, Bulgaria, China, Costa Rica, Ecuador, Egypt, El Salvador, Guatemala, Honduras, Israel, Nicaragua, Norway, Panama, Paraguay, the Dominican Republic, and Turkey.

⚠️
Important:

The combined length of the fields Remitter -> firstName and Remitter -> lastName or Remitter -> companyName cannot exceed 35 characters.

The field Remitter → location → Address cannot exceed 35 characters.

PIX Key (for Brazil) or Bre-B (for Colombia)

Parameter	Type	Required	Description
`InstantPaymentData → Document`	`string`	Yes⁴	PIX: The beneficiary’s CPF/CNPJ number configured as the PIX key. The number of digits for CPF must be 11 and for CNPJ must be 14. Bre-B: The beneficiary’s document number configured as the Bre-B key.
`InstantPaymentData → Email`	`string`	Yes⁴	PIX and Bre-B: The beneficiary’s email address configured as the PIX or Bre-B key. This parameter must be a valid email address.
`InstantPaymentData → Phone`	`string`	Yes⁴	PIX: The beneficiary’s phone number configured as the PIX key. The number must start with `+55`. Bre-B: The beneficiary’s phone number configured as the Bre-B key. The number MUST NOT include `+57`.
`InstantPaymentData → Random`	`string`	Yes⁴	PIX and Bre-B: The random key the beneficiary has generated as a Pix or Bre-B key.
`InstantPaymentData → Commerce`	`string`	Yes⁴	Identifier key for businesses.

⁴ Applies only to Brazil (PIX) or Colombia (Bre-B) when using type InstantPayment. Otherwise, the payee.InstantPaymentData object and its parameters must not be included in the request..

Remitter Object

Parameter	Type	Required	Description
`remitter` → `firstName`	`string`	Yes⁵	Remitter’s first name.
`remitter` → `lastName`	`string`	Yes⁵	Remitter’s last name.
`remitter` → `companyName`	`string`	Yes⁵	Remitter’s company name (if applicable).
`remitter` → `birthday`	`DateTime`	No	Remitter’s date of birth (`YYYY-MM-DD`).
`remitter` → `CountryIsoCode`	`string`	No	Remitter’s country of residence (2-digit ISO).
`remitter` → `location` → `City`	`string`	No	Remitter’s city.
`remitter` → `location` → `Address`	`string`	Yes⁵	Remitter’s physical address.
`remitter` → `location` → `ZipCode`	`string`	No	Remitter’s postal/ZIP code.

⁵ These fields are required for bank transfers ONLY to the following countries:
Bolivia, Bosnia and Herzegovina, Bulgaria, China, Costa Rica, Ecuador, Egypt, El Salvador, Guatemala, Honduras, Israel, Nicaragua, Norway, Panama, Paraguay, the Dominican Republic, and Turkey.

Test the API

Now that you know how to create a payout, you can explore the API Reference for more details:

Country Requirements

Specific rules per country (documents, bank formats, currencies).

API Reference

Complete documentation with request/response examples.

Webhooks

Learn how to receive payout status updates and automate notifications.

Error Codes

Understand possible error responses and how to resolve them.