Skip to main content

​
PayOut API

Use this API to initiate disbursements to bank accounts and supported wallets. Supported methods by country:
  • Colombia: BANK_TRANSFER, TRANSFIYA, TUMIPAY, BREB (see Bre-B integration)
  • Peru: BANK_TRANSFER
For country-specific details (banks, account types, document types, limits), see the Colombia and Peru configuration pages.

​
Transaction Flow

The PayOut process follows a clear sequence of interactions between different participants:

​
Preauthorization Rules

Preauthorization, limits and validations depend on each country and method. Refer to the country pages for current values and processes.

​
Endpoints

​
POST Initiate a PayOut Transaction

/api/v1/payout

This endpoint allows you to perform dispersions using methods like TumiPay Wallet and Bank Transfer. Transactions are processed asynchronously, ensuring efficiency and reliability.

​
Request Headers

​
Token-Top
string
required
Secret token for authorization
​
Authorization
string
required
Authorization key for access

​
Request Body

​
payment_method
string
required
Specifies the payment method. See country-specific options:
​
reference
string
required
Unique reference for the transaction
​
amount
integer
required
Amount to be transferred
​
currency
string
required
Currency for the transaction. Use COP for Colombia, PEN for Peru
​
country
string
required
Two-letter country code. Possible values: “CO”, “PE”, “MX”
​
ipn_url
string
required
Webhook URL to receive transaction status updates
​
customer_data
object
required

​
Response

​
code
string
required
Response code (see Error Codes)
​
status
string
required
Status of the transaction (e.g., “SUCCESS”)
​
message
string
Transaction result message
​
data
object
required
cURL
curl --request POST 'https://api-empresas.staging.tumipay.co/production/api/v1/payout' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payment_method": "BANK_TRANSFER",
    "reference": "tu-referencia",
    "amount": 1000,
    "currency": "COP",
    "country": "CO",
    "ipn_url": "http://example.com/tu-webhook",
    "customer_data": {
        "legal_doc": "1002184990",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3003540831",
        "email": "[email protected]",
        "full_name": "John Doe",
        "bank": "EXAMPLE_BANK",
        "account_number": "3990000011",
        "account_type": "AHORRO"
    }
}'
JavaScript
// Using fetch API
const response = await fetch('https://api-empresas.staging.tumipay.co/production/api/v1/payout', {
  method: 'POST',
  headers: {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_method: 'BANK_TRANSFER',
    reference: '3cNPNGbX7meiMppXzVz7g781ysektqq5X',
    amount: 1000,
    currency: 'COP',
    country: 'CO',
    ipn_url: 'http://example.com/tu-webhook',
    customer_data: {
      legal_doc: '1002184990',
      legal_doc_type: 'CC',
      phone_code: '57',
      phone_number: '3003540831',
      email: '[email protected]',
      full_name: 'John Doe',
      bank: 'EXAMPLE_BANK',
      account_number: '3990000011',
      account_type: 'AHORRO'
    }
  })
});
const data = await response.json();
Python
import requests
import json

url = "https://api-empresas.staging.tumipay.co/production/api/v1/payout"

headers = {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
}

payload = {
    "payment_method": "BANK_TRANSFER",
    "reference": "tu-referencia",
    "amount": 1000,
    "currency": "COP",
    "country": "CO",
    "ipn_url": "http://example.com/tu-webhook",
    "customer_data": {
        "legal_doc": "1002184990",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3003540831",
        "email": "[email protected]",
        "full_name": "John Doe",
        "bank": "EXAMPLE_BANK",
        "account_number": "3990000011",
        "account_type": "AHORRO"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
result = response.json()
PHP
<?php
$url = "https://api-empresas.staging.tumipay.co/production/api/v1/payout";

$headers = array(
    'Token-Top: your_auth_token',
    'Authorization: Basic your_auth_key',
    'Content-Type: application/json'
);

$payload = array(
    "payment_method" => "BANK_TRANSFER",
    "reference" => "tu-referencia",
    "amount" => 1000,
    "currency" => "COP",
    "country" => "CO",
    "ipn_url" => "http://example.com/tu-webhook",
    "customer_data" => array(
        "legal_doc" => "1002184990",
        "legal_doc_type" => "CC",
        "phone_code" => "57",
        "phone_number" => "3003540831",
        "email" => "[email protected]",
        "full_name" => "John Doe",
        "bank" => "DAVIPLATA",
        "account_number" => "3990000011",
        "account_type" => "AHORRO"
    )
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>

​
Error Codes

CodeMeaning
01Operation successful
00Validation error or processing failed

​
Supported Banks

For a complete list of supported banks for PayOut transactions, please refer to the country-specific documentation:

​
Valid Account Types

The following account types are valid for processing transactions through this API.
Account TypeDescription
AHORROSavings account
CORRIENTECurrent or checking account
WALLETDigital Wallet
Always use the corresponding account type in your API requests to ensure proper processing of the transaction.

​
Common Bank Response Messages for “REJECTED” Status

When a payout transaction is rejected, the top_response_message field in the webhook payload contains a message provided by the bank explaining the reason for the rejection.
Response Message
Transferencia exitosa
Esta cuenta está inactiva/bloqueada
La cuenta o Nit no corresponden
El número de cuenta no existe
El número de cuenta no es válido
Cuenta no autorizada
El Nit no es válido
El producto de destino no existe
Excede el tope saldo de la cuenta destino
These messages should be monitored and logged to understand the reason for the rejection and take any necessary corrective actions.

​
Response Examples

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "19kazMPNue2fOIp",
        "date": "2025-10-16 00:58:54",
        "transaction": {
            "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 1000,
            "currency": "COP",
            "payment_method": "BANK_TRANSFER"
        }
    }
}
Error Response
{
  "code": "00",
  "status": "ERROR",
  "error": "VALIDATION_ERROR",
  "message": "El banco especificado no existe"
}