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
Mexico: SPEI
Guatemala: BANK_TRANSFER
Honduras: BANK_TRANSFER

For country-specific details (banks, account types, document types, limits), see the Colombia, Peru, Mexico, Guatemala, and Honduras 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

string

required

Secret token for authorization

string

required

Authorization key for access

Request Body

string

required

Specifies the payment method. See country-specific options:

string

required

Unique reference for the transaction

integer

required

Amount to be transferred

string

required

Currency for the transaction. Use COP for Colombia, PEN for Peru, MXN for Mexico

string

required

Two-letter country code. Possible values: “CO”, “PE”, “MX”

string

required

Webhook URL to receive transaction status updates

object

required

Show Customer data object

string

required

Customer ID number

string

required

Type of document. See country-specific types:

string

required

Country code for the customer’s phone number

string

required

Customer’s phone number without country code

string

required

Customer email address

string

required

Full name of the customer

string

required

Destination bank

string

required

Account number of the customer

string

required

Type of destination account. See country-specific types:

Response

string

required

Response code (see Error Codes)

string

required

Status of the transaction (e.g., “SUCCESS”)

string

Transaction result message

object

required

Show Transaction data object

string

Unique identifier for the payout

string

Timestamp of the transaction

object

Show Transaction details

string

Client reference identifier

integer

Transaction amount

string

Currency code

string

Selected payment method

cURL

curl --request POST 'https://api-empresas.staging.topup.com.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": "johndoe@email.com",
        "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.topup.com.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: 'johndoe@email.com',
      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.topup.com.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": "johndoe@email.com",
        "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.topup.com.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" => "johndoe@email.com",
        "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);
?>

Examples for Mexico

SPEI

Disbursement via SPEI to a CLABE account. The 18-digit CLABE uniquely identifies the destination bank and account.

curl --request POST 'https://api-empresas.staging.topup.com.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": "SPEI",
    "reference": "mx-payout-ref-001",
    "amount": 500.00,
    "currency": "MXN",
    "country": "MX",
    "ipn_url": "https://your-server.com/webhook",
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "RFC",
        "phone_code": "52",
        "phone_number": "5512345678",
        "email": "customer@example.com",
        "full_name": "Juan Pérez",
        "account_number": "123456789012345678",
        "account_type": "CLABE"
    }
}'

Error Codes

Code	Meaning
01	Operation successful
00	Validation error or processing failed

Supported Banks

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

Colombia - Supported Banks
Peru - Supported Banks
Mexico - SPEI transfers route via the national CLABE system; no specific bank selection is required

Valid Account Types

The following account types are valid for processing transactions through this API.

Account Type	Country	Description
AHORRO	Colombia, Peru	Savings account
CORRIENTE	Colombia, Peru	Current or checking account
WALLET	Colombia, Peru	Digital wallet
CLABE	Mexico	18-digit standardized banking code (SPEI transfers)
SPEI	Mexico	SPEI transfer account

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"
}

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

PayOut API

PayOut API

Transaction Flow

Preauthorization Rules

Endpoints

POST Initiate a PayOut Transaction

/api/v1/payout

Request Headers

Request Body

Response

Examples for Mexico

SPEI

Error Codes

Supported Banks

Valid Account Types

Common Bank Response Messages for “REJECTED” Status

Response Examples

​PayOut API

​Transaction Flow

​Preauthorization Rules

​Endpoints

​POST Initiate a PayOut Transaction

/api/v1/payout

​Request Headers

​Request Body

​Response

​Examples for Mexico

​SPEI

​Error Codes

​Supported Banks

​Valid Account Types

​Common Bank Response Messages for “REJECTED” Status

​Response Examples

PayOut API

Transaction Flow

Preauthorization Rules

Endpoints

POST Initiate a PayOut Transaction

Request Headers

Request Body

Response

Examples for Mexico

SPEI

Error Codes

Supported Banks

Valid Account Types

Common Bank Response Messages for “REJECTED” Status

Response Examples