Payout
Payout API Documentation
Overview
This document provides step-by-step instructions on how users can make payouts through our platform. All requests must be authenticated, and POST requests require a unique Idempotency-Key for each unique request. CHL (Chile), COL (Colombia), PER (Peru), ARG (Argentina), MEX(Mexico).
Step 1: Retrieve Payout Gateway ID
To make a payout, first, retrieve the available payout methods for a specific country by making a GET request to:
GET {{host}}/payment-methods/payout?country={{country_iso3_code}}
Request Example:
GET {{host}}/payment-methods/payout?country=CHL
GET {{host}}/payment-methods/payout?country=COL
GET {{host}}/payment-methods/payout?country=PER
GET {{host}}/payment-methods/payout?country=ARG
GET {{host}}/payment-methods/payout?country=MEX
Response Example:
Extract the *id* of the desired payment method to proceed.
Step 2: Retrieve Beneficiary Form
Use the retrieved gateway_id to get the form fields required for beneficiary payment details:
GET {{host}}/beneficiary/form/show/{{gateway_id}}
Request Example:
Argentina
GET {{host}}/beneficiary/form/show/492
Chile
GET {{host}}/beneficiary/form/show/505
Colombia
GET {{host}}/beneficiary/form/show/2
Mexico
GET {{host}}/beneficiary/form/show/1
Peru
GET {{host}}/beneficiary/form/show/501
Response Example:
Step 3: Add Beneficiary Payment Details
Submit a POST request to add the beneficiary payment details using the obtained form structure:
POST {{host}}/beneficiaries/payment-methods/
Payload Example
Argentina
{ "gateway_id": 492, "nickname": "Arg acct", "currency": "ARS", "payment_data": { "beneficiary_type": "Individual", "beneficiary_first_name": "Lamine", "beneficiary_last_name": "Mandela", "company_name": null, "beneficiary_email": "[email protected]", // Not provided in data "beneficiary_address": "Address not provided", // Placeholder "beneficiary_document_type": "CUIL", "beneficiary_document_number": "20xxxxxxxxx5", // CUIL/T 20-6xxxxxxx6-5 (formatted without hyphens) "bank_code": "92", // Banco Ciudad's code "account_type_bank": "C", // Default to "Cuenta corriente" "account_bank": "02xxxxxxxxxxxxxx7", // CBU formatted without hyphens "fc_customer_type": "natural", "fc_legal_name": "Lamine Mandela", "fc_document_type": "dni", "fc_document_number": "6xxxxxxx6", // Last 8 digits of CUIL "fc_legal_address": "Address not provided", // Placeholder "fc_birthdate": "1888-01-01", // Placeholder (required field) "purpose": "EPFAMT", // "Mantenimiento familiar" "purpose_comentary": "Mantenimiento familiar" } }Chile
{ "gateway_id": 505, "nickname": "CHL acct", "currency": "CLP", "payment_data": { "beneficiary_id" : "7xxxxxxx1", "beneficiary_name" : "Zebra Aerospace", "beneficiary_account" : "8xxxxxx7", "beneficiary_account_type": "2", "beneficiary_bank_code": "016", "beneficiary_email": "[email protected]", "description": "transfer" } //"customer_id": "dxxxxxxx-exxx-4xxx-8xxxx-7xxxxxxx" }Colombia
{ "gateway_id": 2, "nickname": "COL acct", "currency": "COL", "payment_data": { "bankAccount" : "0xx-0xxxxx-5x", "AccountType" : "2", "bankCode" : "007" } //"customer_id": "dxxxxxxx-exxx-4xxx-8xxxx-7xxxxxxx" }Mexico
{ "gateway_id": 1, "nickname": "MXN acct", "currency": "MXN", "payment_data": { "clabe" : "6xxxxxxxxxxxxxxxxx", "beneficiary": "Hugo Marine" } //"customer_id": "dxxxxxxx-exxx-4xxx-8xxxx-7xxxxxxx" }Peru
{ "gateway_id": 501, "nickname": "Sample Account", "currency": "PEN", "payment_data": { "beneficiary_first_name": "John", "beneficiary_last_name": "Doe", "beneficiary_email": "[email protected]", "beneficiary_address": "123 Example Street", "city": "Lima", "phone": "0000000000", "beneficiary_document_type": "DNI", "beneficiary_document_number": 12345678, "bank_code": 111, "account_type_bank": "c", "account_bank": "002XXXXXXXXXXX", "fc_customer_type": "natural", "fc_legal_name": "Jane Smith", "fc_document_type": "DNI", "fc_document_number": 87654321, "fc_legal_address": "456 Another Ave", "fc_birthdate": "1990-01-01", "purpose": "ISSCVE", "purpose_comentary": "Test Payment" } // "customer_id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx" }
Response Example:
Argentina
{ "status": "success", "status_code": 200, "message": "Request successful", "data": { "message": "Payment data processed successfully", "data": { "user_id": 4, "currency": "ARS", "gateway_id": 492, "nickname": "Sample Account", "address": null, "payment_data": { "beneficiary_type": "Individual", "beneficiary_first_name": "John", "beneficiary_last_name": "Doe", "company_name": null, "beneficiary_email": "[email protected]", "beneficiary_address": "123 Placeholder Street", "beneficiary_document_type": "CUIL", "beneficiary_document_number": "20000000000", "bank_code": "99", "account_type_bank": "C", "account_bank": "0290XXXXXXXXXXXXXXX", "fc_customer_type": "natural", "fc_legal_name": "Jane Smith", "fc_document_type": "dni", "fc_document_number": "60000000", "fc_legal_address": "456 Sample Avenue", "fc_birthdate": "1990-01-01", "purpose": "EPFAMT", "purpose_comentary": "Mantenimiento familiar" }, "beneficiary_id": null, "created_at": "2025-02-17T11:38:04.000000Z", "id": 7 } } }Chile
{ "status": "success", "status_code": 200, "message": "Request successful", "data": { "message": "Payment data processed successfully", "data": { "user_id": 4, "currency": "CLP", "gateway_id": 505, "nickname": "Sample Account", "address": null, "payment_data": { "beneficiary_id": "000000000", "beneficiary_name": "Sample Company Ltd", "beneficiary_account": "00000000", "beneficiary_account_type": "2", "beneficiary_bank_code": "999", "beneficiary_email": "[email protected]", "description": "transfer" }, "beneficiary_id": null, "created_at": "2025-02-17T13:35:19.000000Z", "id": 12 } } }Colombia
{ "status": "success", "status_code": 200, "message": "Request successful", "data": { "message": "Payment data processed successfully", "data": { "user_id": 4, "currency": "COP", "gateway_id": 2, "nickname": "Sample Account", "address": null, "payment_data": { "bankAccount": "000-000000-00", "AccountType": "2", "bankCode": "999" }, "beneficiary_id": null, "created_at": "2025-02-17T13:22:48.000000Z", "id": 11 } } }Mexico
{ "status": "success", "status_code": 200, "message": "Request successful", "data": { "message": "Payment data processed successfully", "data": { "user_id": 4, "currency": "MXN", "gateway_id": 1, "nickname": "Sample Account", "address": null, "payment_data": { "clabe": "000000000000000000", "beneficiary": "Jane Doe" }, "beneficiary_id": null, "created_at": "2025-02-17T12:41:32.000000Z", "id": 9 } } }Peru
{ "status": "success", "status_code": 200, "message": "Request successful", "data": { "message": "Payment data processed successfully", "data": { "user_id": 4, "currency": "PEN", "gateway_id": 501, "nickname": "Sample Account", "address": null, "payment_data": { "beneficiary_first_name": "John", "beneficiary_last_name": "Doe", "beneficiary_email": "[email protected]", "beneficiary_address": "123 Main Street, Lima", "city": "Lima", "phone": "000000", "beneficiary_document_type": "DNI", "beneficiary_document_number": 12345678, "bank_code": 999, "account_type_bank": "c", "account_bank": "00000000000000000000", "fc_customer_type": "natural", "fc_legal_name": "John Doe", "fc_document_type": "DNI", "fc_document_number": 12345678, "fc_legal_address": "123 Main Street, Lima", "fc_birthdate": "1990-01-01", "purpose": "ISSCVE", "purpose_comentary": "Payment" }, "beneficiary_id": null, "created_at": "2025-02-17T13:06:48.000000Z", "id": 10 } } }
Step 4: Retrieve Beneficiary Payment Details
To retrieve all added beneficiary payment details, make a GET request to:
GET {{host}}/beneficiaries/payment-methods/all
Response Example:
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": [
{
"id": 12,
"gateway_id": 505,
"beneficiary_id": null,
"nickname": "CHL acct",
"currency": "CLP",
"address": null,
"payment_data": {
"beneficiary_id": "000000000",
"beneficiary_name": "Sample Beneficiary",
"beneficiary_account": "12345678",
"beneficiary_account_type": "2",
"beneficiary_bank_code": "001",
"beneficiary_email": "[email protected]",
"description": "transfer"
},
"created_at": "2025-02-17T13:35:19.000000Z",
"user_id": 4,
"gateway": {
"id": 505,
"method_name": "Bank Transfer",
"country": "CHL",
"currency": "CLP",
"base_currency": "CLP"
}
},
{
"id": 11,
"gateway_id": 2,
"nickname": "COL acct",
"currency": "COP",
"payment_data": {
"bankAccount": "000-000000-00",
"AccountType": "2",
"bankCode": "000"
},
"created_at": "2025-02-17T13:22:48.000000Z",
"user_id": 4,
"gateway": {
"id": 2,
"method_name": "Bank Transfer",
"country": "COL",
"currency": "COP",
"base_currency": "USD"
}
},
{
"id": 10,
"gateway_id": 501,
"nickname": "Peru acct",
"currency": "PEN",
"payment_data": {
"beneficiary_first_name": "John",
"beneficiary_last_name": "Doe",
"beneficiary_email": "[email protected]",
"beneficiary_address": "123 Example Street",
"city": "Lima",
"phone": "000000",
"beneficiary_document_type": "DNI",
"beneficiary_document_number": 12345678,
"bank_code": 123,
"account_type_bank": "c",
"account_bank": "00000000000000000000",
"fc_customer_type": "natural",
"fc_legal_name": "John Doe",
"fc_document_type": "DNI",
"fc_document_number": 12345678,
"fc_legal_address": "123 Example Street",
"fc_birthdate": "1990-01-01",
"purpose": "TEST",
"purpose_comentary": "Payment"
},
"created_at": "2025-02-17T13:06:48.000000Z",
"user_id": 4,
"gateway": {
"id": 501,
"method_name": "Bank Transfer",
"country": "PER",
"currency": "PEN",
"base_currency": "USD"
}
},
{
"id": 9,
"gateway_id": 1,
"nickname": "MXN acct",
"currency": "MXN",
"payment_data": {
"clabe": "000000000000000000",
"beneficiary": "Jane Doe"
},
"created_at": "2025-02-17T12:41:32.000000Z",
"user_id": 4,
"gateway": {
"id": 1,
"method_name": "SPEI",
"country": "MEX",
"currency": "MXN",
"base_currency": "USD"
}
},
{
"id": 8,
"gateway_id": 494,
"nickname": "BRA acct",
"currency": "BRL",
"payment_data": {
"taxId": "00000000000",
"pixKey": "00000000000"
},
"created_at": "2025-02-17T12:15:52.000000Z",
"user_id": 4,
"gateway": {
"id": 494,
"method_name": "Pix",
"country": "BRA",
"currency": "BRL",
"base_currency": "USD,BRL"
}
},
{
"id": 7,
"gateway_id": 492,
"nickname": "Arg acct",
"currency": "ARS",
"payment_data": {
"beneficiary_type": "Individual",
"beneficiary_first_name": "Alex",
"beneficiary_last_name": "Smith",
"beneficiary_email": "[email protected]",
"beneficiary_address": "Unknown",
"beneficiary_document_type": "CUIL",
"beneficiary_document_number": "00000000000",
"bank_code": "00",
Step 5: Initiate Payout
Use the id from the previous response as the payment_method_id to make a payout request:
POST {{host}}/wallet/payout
Payload Example:
Argentina
{ "debit_wallet": "USD", "amount": 17, "payment_method_id": 5 }Chile
{ "debit_wallet": "CLP", "amount": 1000, "payment_method_id": 12 }Colombia
{ "debit_wallet": "USD", "amount": 10000, "payment_method_id": 11 }Mexico
{ "debit_wallet": "USD", "amount": 1, "payment_method_id": 9 }Peru
{ "debit_wallet": "USD", "amount": 75, "payment_method_id": 10 }
Response Example:
Argentina
{ "status": "success", "status_code": 201, "message": "Withdrawal request received and will be processed shortly.", "data": { "amount": 17, "debit_wallet": "USD", "user_id": 4, "raw_data": { "debit_wallet": "USD", "amount": 17, "payment_method_id": 5 }, "currency": "ARS", "beneficiary_id": 5, "payout_id": "bf3b5096-f24d-419c-967f-dd8c75512ec4", "updated_at": "2025-02-17T11:34:38.000000Z", "created_at": "2025-02-17T11:34:38.000000Z" } }Chile
{ "status": "success", "status_code": 201, "message": "Withdrawal request received and will be processed shortly.", "data": { "amount": 10000, "debit_wallet": "CLP", "user_id": 4, "raw_data": { "debit_wallet": "CLP, "amount": 1000, "payment_method_id": 12 }, "currency": "CLP", "beneficiary_id": 12, "payout_id": "4a269cd6-f7a3-47e3-9946-d954a21c57da", "updated_at": "2025-02-17T13:23:57.000000Z", "created_at": "2025-02-17T13:23:57.000000Z" } }Colombia
{ "status": "success", "status_code": 201, "message": "Withdrawal request received and will be processed shortly.", "data": { "amount": 10000, "debit_wallet": "USD", "user_id": 4, "raw_data": { "debit_wallet": "USD", "amount": 10000, "payment_method_id": 11 }, "currency": "COP", "beneficiary_id": 11, "payout_id": "4a269cd6-f7a3-47e3-9946-d954a21c57da", "updated_at": "2025-02-17T13:23:57.000000Z", "created_at": "2025-02-17T13:23:57.000000Z" } }Mexico
{ "status": "success", "status_code": 201, "message": "Withdrawal request received and will be processed shortly.", "data": { "amount": 1, "debit_wallet": "USD", "user_id": 4, "raw_data": { "debit_wallet": "USD", "amount": 1, "payment_method_id": 9 }, "currency": "MXN", "beneficiary_id": 9, "payout_id": "767b0063-2427-421e-a56c-b3253a1d0bde", "updated_at": "2025-02-17T12:42:17.000000Z", "created_at": "2025-02-17T12:42:17.000000Z" } }Peru
{ "status": "success", "status_code": 201, "message": "Withdrawal request received and will be processed shortly.", "data": { "amount": 75, "debit_wallet": "USD", "user_id": 4, "raw_data": { "debit_wallet": "USD", "amount": 75, "payment_method_id": 10 }, "currency": "PEN", "beneficiary_id": 10, "payout_id": "ca59fba7-dad6-4d2a-bb04-deb4500b68d3", "updated_at": "2025-02-17T13:07:55.000000Z", "created_at": "2025-02-17T13:07:55.000000Z" } }
Authentication & Idempotency
Authentication: All requests must be authenticated using an API key.
Idempotency: POST requests require a unique Idempotency-Key header to ensure duplicate requests are not processed multiple times.
{
"gateway_id": 184,
"nickname": "EUR acct",
"currency": "EUR",
"payment_data": {
"account_number": "1234567890",
"account_name": "John Doe",
"routing_number": "111000025",
"account_type": "iban",
"beneficiary_bank_code": "001",
"beneficiary_email": "[email protected]",
"description": "transfer"
}
// "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
For further support, please contact Us.
Last updated