Payout Request
To learn more about Payouts, refer to this article.
Payout request
This method allows you to request one or more Payouts using the funds settled in your account.
Request URL
You must invoke a POST request to the following URLs according to your needs.
- Production:
https://payout-api.bamboopayment.com/api/payout
- stage:
https://payout-api.stage.bamboopayment.com/api/payout
Request parameters
The following table shows the mandatory and optional parameters to create a Payout for all the countries.
Field | Type | Mandatory? | Description | |
---|---|---|---|---|
country | string(2) | Yes | ISO code of the country in the format ISO 3166-2 .List of countries available for Payouts. | |
amount | integer | Yes | Amount of the Payout, the format has two digits for decimals. Example 100 => $ 1.00. | |
currency | string(3) | Yes | ISO code of the origin currency. This currency must match the one configured in your account. Find the currencies list here. | |
reason | string | No | Description of the Payout. | |
destinationCurrency | string(3) | Yes | ISO code of the currency in which the beneficiary will receive the payout. This parameter is not required for the USD2L model, and the system will default to the currency of the destination country. This currency must comply with your account’s payout model. For example:
Find the currencies list here. | |
reference | string | Yes | Unique identifier of the Payout defined by you. Ensure it is unique. | |
type | integer | Yes | Payout type. Assign any of these values:
| |
InstantPaymentData → PixDocument | string | Yes1 | Payee’s CPF/CNPJ number registered as a PIX key. Must be 11 digits for CPF or 14 for CNPJ. | |
InstantPaymentData → PixEmail | string | Yes1 | Payee’s email address registered as a PIX key. Must be a valid email. | |
InstantPaymentData → PixPhone | string | Yes1 | Payee’s phone number registered as a PIX key. Must start with +55 . | |
InstantPaymentData → PixRandom | string | Yes1 | Randomly generated PIX key assigned to the Payee. | |
notification_Url | string | No | Webhook to notify the Payout result. Learn more here. | |
payee → FirstName | string | Yes3 | Payee’s first name. | |
payee → lastName | string | Yes3 | Payee’s last name. | |
payee → companyName | string | Yes3 | Payee’s company name (if applicable). | |
payee → email | string | No | Payee’s email address. | |
payee → phone | string | No | Payee’s phone number. | |
payee → nationalityCode | string | No | Payee’s nationality (2-digit ISO country code). | |
payee → BirthDay | DateTime | No | Payee’s date of birth (format: YYYY-MM-DD ). | |
payee → address | string | No | Payee’s physical address. | |
Location → City | string | Yes5 | Payee’s city of residence. | |
Location → address | string | Yes5 | Payee’s full residential address. | |
Location → zipCode | string | No | Payee’s postal/ZIP code. | |
payee → document → type | string | Yes | Payee’s document type. See document types. | |
payee → document → number | string | Yes | Payee’s document number. | |
payee → bankaccount → number | string | Yes2 | Payee’s account number. Notes:
| |
payee → bankaccount → type | integer | Yes2 | Account type: 1 (Checking) or 2 (Savings). | |
payee → bankaccount → codebank | string | Yes2 | Payee’s bank code. Get bank list or view codes. | |
payee → bankaccount → Swift | string | Yes4 | International routing code (SWIFT/BIC). | |
payee → bankaccount → Branch | string | No | Bank branch code (if applicable). | |
Remitter → firstName | string | Yes4 | Remitter’s first name. | |
Remitter → lastName | string | Yes4 | Remitter’s last name. | |
Remitter → companyName | string | Yes4 | 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 | Yes4 | Remitter’s physical address. | |
Remitter → location → ZipCode | string | No | Remitter’s postal/ZIP code. |
1 Applies only to Brazil using Instant Bank Transfer. Otherwise, the object payee.InstantPaymentData
and its parameters must not be present in the request.
2 When using Bank transfer, these parameters are mandatory for ALL countries. For Instant Bank Transfer in Brazil, the object payee.bankaccount
and its parameters must not be present in the request.
3 The fields firstName
and lastName
for an individual and companyName
for a company are mandatory. If a payout is sent to a company, only the companyName
field has to be completed, and if a payout is sent to an individual, only the firstName
and lastName
fields have to be completed.
Important: The firstName
and lastName
fields do not support numbers or special characters, only letters. The companyName
field does accept all types of alphanumeric characters.
4 These fields are mandatory for bank transfers ONLY to the following countries:
Bosnia and Herzegovina, Bulgaria, Costa Rica, Dominican Republic, Egypt, Guatemala, Israel, Nicaragua, Norway, Paraguay, and Turkey.
5 These fields are mandatory only for bank transfers to Egypt.
Request example
Refer to the corresponding tab according to the payee’s country.
Argentina: From USD to ARS:
{
"country": "AR",
"amount": 1000,
"currency": "USD",
"destinationCurrency":"ARS",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Sara",
"lastName": "Jáquez",
"email": "sarasouez@mail.com",
"phone": "099999999",
"address": "Francisco 51 Gral. Ximena, AR-H 0376",
"document": {
"type": "CUIL",
"number": "12345678901"
},
"bankAccount": {
"number": "0000053600000000000566",
"type": 1,
"codeBank": "7"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Argentina: From ARS to ARS:
{
"country": "AR",
"amount": 1000,
"currency": "ARS",
"reason": "string",
"destinationCurrency":"ARS",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Sara",
"lastName": "Jáquez",
"email": "sarasouez@mail.com",
"phone": "099999999",
"address": "Francisco 51 Gral. Ximena, AR-H 0376",
"document": {
"type": "CUIL",
"number": "12345678901"
},
"bankAccount": {
"number": "0000053600000000000566",
"type": 1,
"codeBank": "7"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
As mentioned before, the payee.bankaccount
object should not be present in the request. Therefore, when using Instant Bank Transfers it must be sent as follows:
Brazil: From USD to BRL:
{
"country": "BR",
"amount": 100,
"currency": "USD",
"destinationCurrency":"BRL",
"reason": "string",
"reference": "PayOut34",
"type": 4,
"InstantPaymentData": {
"PixEmail":"tcosta@mail.com" // Can also be PixDocument, PixPhone, or PixRandom
},
"payee": {
"firstName": "Tiago",
"lastName": "Costa",
"email": "tcosta@mail.com",
"phone": "92799322",
"address": "55489-272, Travessa Eduardo, 90 Esteves do Norte - CE",
"document": {
"type": "CPF",
"number": "54562271779"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Brazil: From BRL to BRL
{
"country": "BR",
"amount": 100,
"currency": "BRL",
"destinationCurrency":"BRL",
"reason": "string",
"reference": "PayOut34",
"type": 4,
"InstantPaymentData": {
"PixEmail":"tcosta@mail.com" // Can also be PixDocument, PixPhone, or PixRandom
},
"payee": {
"firstName": "Tiago",
"lastName": "Costa",
"email": "tcosta@mail.com",
"phone": "92799322",
"address": "55489-272, Travessa Eduardo, 90 Esteves do Norte - CE",
"document": {
"type": "CPF",
"number": "54562271779"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Chile: From USD to CLP
{
"country": "CL",
"amount": 1000,
"currency": "USD",
"destinationCurrency":"CLP",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Mercedes",
"lastName": "Garrido",
"email": "merceddo@mail.com",
"phone": "099999999",
"address": "Camino Franco, 13, Atico 4, 93631, L Garay",
"document": {
"type": "CI",
"number": "26068762K"
},
"bankAccount": {
"number": "1234567890123450",
"type": 1,
"codeBank": "1"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Chile: From CLP to CLP
{
"country": "CL",
"amount": 1000,
"currency": "CLP",
"destinationCurrency":"CLP",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Mercedes",
"lastName": "Garrido",
"email": "merceddo@mail.com",
"phone": "099999999",
"address": "Camino Franco, 13, Atico 4, 93631, L Garay",
"document": {
"type": "CI",
"number": "26068762K"
},
"bankAccount": {
"number": "1234567890123450",
"type": 1,
"codeBank": "1"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Colombia: From USD to COP
{
"country": "CO",
"amount": 100,
"currency": "USD",
"destinationCurrency":"COP",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Diego",
"lastName": "Silva",
"email": "dsilva@mail.com",
"phone": "099999999",
"address": "Cra 23 # 123-45 Apto 601",
"document": {
"type": "CC",
"number": "11111111"
},
"bankAccount": {
"number": "2288",
"type": 1,
"codeBank": "1007"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Colombia: From COP to COP
{
"country": "CO",
"amount": 100,
"currency": "COP",
"reason": "string",
"destinationCurrency":"COP",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Diego",
"lastName": "Silva",
"email": "dsilva@mail.com",
"phone": "099999999",
"address": "Cra 23 # 123-45 Apto 601",
"document": {
"type": "CC",
"number": "11111111"
},
"bankAccount": {
"number": "2288",
"type": 1,
"codeBank": "1007"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Mexico: From USD to MXN
{
"country": "MX",
"amount": 1000,
"currency": "USD",
"destinationCurrency":"MXN",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Rubén",
"lastName": "Torres",
"email": "rubentres@mail.com",
"phone": "01 55 5601 7965",
"address": "Coyoacan 2000",
"document": {
"type": "CURP",
"number": "OEAF771012HMCRGR09"
},
"bankAccount": {
"number": "123456789012345678",
"type": 1,
"codeBank": "2"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Mexico: From MXN to MXN
{
"country": "MX",
"amount": 1000,
"currency": "MXN",
"reason": "string",
"destinationCurrency":"MXN",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Rubén",
"lastName": "Torres",
"email": "rubentres@mail.com",
"phone": "01 55 5601 7965",
"address": "Coyoacan 2000",
"document": {
"type": "CURP",
"number": "OEAF771012HMCRGR09"
},
"bankAccount": {
"number": "123456789012345678",
"type": 1,
"codeBank": "2"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Peru: From USD to PEN
{
"country": "PE",
"amount": 1000,
"currency": "USD",
"destinationCurrency":"PEN",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Ornela",
"lastName": "Olivera",
"email": "ornelera@mail.com",
"phone": "099999999",
"address": "Cl. Jesús Bueno # 64 Dpto. 229",
"document": {
"type": "DNI",
"number": "12345678"
},
"bankAccount": {
"number": "12345678901234567890",
"type": 1,
"codeBank": "2"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Peru: From PEN to PEN
{
"country": "PE",
"amount": 1000,
"currency": "PEN",
"reason": "string",
"destinationCurrency":"PEN",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Ornela",
"lastName": "Olivera",
"email": "ornelera@mail.com",
"phone": "099999999",
"address": "Cl. Jesús Bueno # 64 Dpto. 229",
"document": {
"type": "DNI",
"number": "12345678"
},
"bankAccount": {
"number": "12345678901234567890",
"type": 1,
"codeBank": "2"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Peru: From USD to USD
{
"country": "PE",
"amount": 1000,
"currency": "USD",
"reason": "string",
"destinationCurrency":"USD",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Ornela",
"lastName": "Olivera",
"email": "ornelera@mail.com",
"phone": "099999999",
"address": "Cl. Jesús Bueno # 64 Dpto. 229",
"document": {
"type": "DNI",
"number": "12345678"
},
"bankAccount": {
"number": "12345678901234567890",
"type": 1,
"codeBank": "2"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Uruguay: From USD to UYU
{
"country": "UY",
"amount": 1000,
"currency": "USD",
"destinationCurrency":"UYU",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Daniel",
"lastName": "Lorenzo",
"email": "danielzo@mail.com",
"phone": "999999999",
"address": "12900 Montevideo",
"document": {
"type": "CI",
"number": "38067788"
},
"bankAccount": {
"number": "1234567",
"type": 2,
"codeBank": "113"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Uruguay: From UYU to UYU
{
"country": "UY",
"amount": 1000,
"currency": "UYU",
"reason": "string",
"destinationCurrency":"UYU",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Daniel",
"lastName": "Lorenzo",
"email": "danielzo@mail.com",
"phone": "999999999",
"address": "12900 Montevideo",
"document": {
"type": "CI",
"number": "38067788"
},
"bankAccount": {
"number": "1234567",
"type": 2,
"codeBank": "113"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Uruguay: From USD to USD
{
"country": "UY",
"amount": 1000,
"currency": "USD",
"destinationCurrency": "USD",
"reason": "string",
"reference": "PayOut34",
"type": 2,
"payee": {
"firstName": "Daniel",
"lastName": "Lorenzo",
"email": "danielzo@mail.com",
"phone": "999999999",
"address": "12900 Montevideo",
"document": {
"type": "CI",
"number": "38067788"
},
"bankAccount": {
"number": "1234567",
"type": 2,
"codeBank": "113"
}
},
"notification_Url": "https://webhook.site/ebc46ace-94a1-4265-9d7f-d457d437a1b4"
}
Bosnia and Herzegovina: From USD to BAM
{
"country": "BA",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "DNI",
"number": "12345678901"
},
"bankAccount": {
"number": "BA393384002241452786",
"swift": "UNCRBA22XXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Bulgaria: From USD to BGN
{
"country": "BG",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "BULSTAT",
"number": "ABC123456789"
},
"bankAccount": {
"number": "BG80BNBG96611020345678",
"swift": "BNBGBGSFXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Costa Rica: From USD to CRC
{
"country": "CR",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "CI",
"number": "951951258"
},
"bankAccount": {
"number": "CR23015108410026012345",
"swift": "BNCRCRSJXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Dominican Republic: From USD to DOP
{
"country": "DO",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "CI",
"number": "12345678901"
},
"bankAccount": {
"number": "DO88BRRD00000000001630622734",
"swift": "BRRDDOSDXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Egypt: From USD to EGP
{
"country": "EG",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "DNI",
"number": "ABC123456789"
},
"bankAccount": {
"number": "EG380019000500000000263180002",
"swift": "NBADEGCAXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Guatemala: From USD to GTQ
{
"country": "GT",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "DNI",
"number": "ABC123456789"
},
"bankAccount": {
"number": "GT82TRAJ01020000001210029690",
"swift": "TRAJGTGCXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Israel: From USD to ILS
{
"country": "IL",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "PASSPORT",
"number": "ABC123456789"
},
"bankAccount": {
"number": "IL620108000000099999999",
"swift": "LUMIILITTLV",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Nicaragua: From USD to NIO
{
"country": "NI",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "RUC",
"number": "DEF987654321"
},
"bankAccount": {
"number": "12345678901234567890123456789012345",
"swift": "UNCRBA22XXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Norway: From USD to NOK
{
"country": "NO",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "PASSPORT",
"number": "ABC123456789"
},
"bankAccount": {
"number": "NO9386011117947",
"swift": "DABANO22XXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Paraguay: From USD to PYG
{
"country": "PY",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "RUC",
"number": "GHI555666777"
},
"bankAccount": {
"number": "1459842747",
"swift": "BGNBPYPXXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Turkey: From USD to TRY
{
"country": "TR",
"amount": 508,
"currency": "USD",
"reason": "string",
"reference": "reference",
"type": 2,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"email": null,
"phone": "099999999",
"nationalityCode": "AR",
"birthDay": "1996-11-04",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"type": "TCKN",
"number": "ABC123456789"
},
"bankAccount": {
"number": "TR220001234567890000000001",
"swift": "TRHBTR2AXXX",
"type": 0,
"codeBank": null,
"branch": null
}
},
"remitter": {
"firstName": "Ari",
"lastName": "Carba",
"birthDay": "1996-11-04",
"companyName": "michifusis",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"countryIsoCode": "AR"
},
"notification_Url": "null"
}
Info
To send a payout to a legal entity, replace the firstName
and lastName
fields with companyName
.
Example: "companyName":"Google LLC"
Info
For corporate payouts, use companyName
instead of firstName
and lastName
.
Example "companyName":"Google LLC"
Responses
Ok
: HttpCode200
.
Message received correctly, at this point the Payout starts to be processed.
Response body
{
"payoutId": 145,
"status": 5,
"statusDescription": "Received",
"reference": "PayOut34",
"errors": []
}
Where:
Field | Description |
---|---|
payoutId | Internal identifier of the Payout. |
status | Internal code of the current status of the Payout. |
statusDescription | Current status of the Payout. Refer to this article to learn more about Payout status. |
reference | Unique identifier of the Payout you defined when you requested the Payout. |
errors | Errors that may appear. Find the possible errors here. |
BadRequest
: HttpCodeHttpCode 400
.
The validation of the message failed (data validation error), and the Payout is not created.
Response body
{
"errors": [
{
"ErrorCode": "ExactLengthValidator",
"PropertyName": "Country",
"Message": "'Country' must be 2 characters in length. You entered 1 characters."
}
],
"statusCode": 400
}
It also applies when a required API field is not entered.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Payee.Document": [
"The Document field is required."
]
},
"traceId": "00-0f34c73a204d3fece346911769356011-8e4519aef77c0652-00"
}
Unauthorized
: HttpCode401
.
Authorization error.Conflict
-Declined
: HttpCodeHttpCode 409
.
The validation of the message was successful, but the Payout is Declined due to business rules.
Response body
{
"payoutId": 493945,
"status": 8,
"statusDescription": "Declined",
"reference": "QA-538",
"error": {
"errorCode": 812,
"message": "Declined by validation for document"
}
}
Obtaining a Payout
This method allows you to retrieve the information of a Payout. You can retrieve the Payouts using the generated identifier (ID) or the reference you provided when requesting the Payout.
Request URL
You must invoke a GET request to the following URLs according to your needs.
- Production:
https://payout-api.bamboopayment.com/api/payout
- Stage:
https://payout-api.stage.bamboopayment.com/api/payout
To get the payout, include the following endpoints according to your needs.
- Using Payout ID:
{{URL}}/api/payout/{{PayoutID}}
- Using Payout Reference:
{{URL}}/api/payout/reference/{{PayoutReference}}
Response parameters
Parameter | Format | Description |
---|---|---|
payoutId | long | Internal identification of the Payout. (Max. 19 characters) |
reference | string | Unique identifier of the Payout you defined when you requested the Payout. |
isoCountry | string | ISO code of the country in format ISO 3166-2 . |
created | date | Date and time when the Payout was requested. |
lastUpdate | date | Date and time of the last update of the Payout. |
status | integer | Internal code of the current status of the Payout. |
statusDescription | string | Current status of the Payout. Refer to this article to learn more about Payout status. |
errorCode | string | Internal code of the error for the declined Payout. Find the possible errors here. |
errorDescription | string | Error description for declined Payouts. |
amount | object | Value and currency requested in the Payout. |
localAmount | object | Value and currency requested in the Payout in local currency. |
exchangeRate | numeric | Conversion value used in the Payout. |
payee | object | Information of the recipient or beneficiary of the Payout. |
description | string | The description/reason entered in the request. |
Response example
{
"payoutId": 183967619655665472,
"reference": "ARI-763",
"isoCountry": "BA",
"created": "2025-05-22T15:41:39.0401892Z",
"lastUpdate": "2025-05-22T15:41:40.2559466Z",
"status": 8,
"statusDescription": "Declined",
"errorCode": "705",
"errorDescription": "Invalid origin currency ISO code",
"amount": {
"value": 5.08,
"isoCurrency": "EUR"
},
"localAmount": null,
"exchangeRate": null,
"payee": {
"firstName": "Ari",
"lastName": "Carba",
"companyName": "",
"email": "",
"phone": "099999999",
"location": {
"city": "city",
"address": "address",
"zipCode": "zip"
},
"document": {
"number": "2606876221",
"type": "PASSPORT"
}
},
"description": "string"
}
Info
In payout for company, you will receive the field companyName
instead of firstName
and lastName
.
