Overview

The PayOut API for Colombia enables secure disbursements to bank accounts and digital wallets through multiple payment methods including standard bank transfers, TumiPay wallet, and Bre-B instant payments. Transactions are processed asynchronously with webhook notifications.

Key Features

Multiple Disbursement Methods: BANK_TRANSFER,TUMIPAY, BREB
Currency: Colombian Peso (COP)
Asynchronous Processing: Background processing with webhook notifications
Instant Payments: Bre-B support for real-time transfers (24/7/365)
Wide Bank Coverage: Support for major Colombian banks and digital wallets

Quick Reference

Parameter	Value	Description
Endpoint	`POST /api/v1/payout`	Initiate PayOut transaction
Currency	`COP`	Colombian Peso
Country Code	`CO`	Colombia
Auth Required	Yes	Token-Top + Basic Auth
Processing	Async	Status updates via webhook

Request Parameters

Required Fields

Field	Type	Description	Example
`payment_method`	string	Disbursement method	`"BANK_TRANSFER"`, `"BREB"`, `"TUMIPAY"`
`reference`	string	Unique transaction identifier from your system	`"3cNPNGbX7meiMppXzVz7g781ysektqq5X"`
`amount`	integer	Transaction amount in cents (minor currency unit)	`1000` (= $10.00 COP)
`currency`	string	Three-letter currency code (ISO 4217)	`"COP"`
`country`	string	Two-letter country code (ISO 3166-1 alpha-2)	`"CO"`
`ipn_url`	string	Webhook URL for transaction status updates	`"http://example.com/tu-webhook"`
`customer_data`	object	Customer and account information (see below)	-

Customer Data Object

Field	Type	Required	Description	Example
`legal_doc`	string	✅	Customer’s legal document number	`"1002184990"`
`legal_doc_type`	string	✅	Document type: `CC`, `CE`, `PPN`, `NIT`	`"CC"`
`phone_code`	string	✅	Country calling code	`"57"`
`phone_number`	string	✅	Phone number without country code	`"3003540831"`
`email`	string	✅	Customer email address	`"johndoe@email.com"`
`full_name`	string	✅	Customer full name	`"John Doe"`
`bank`	string	✅	Destination bank code	`"BANCOLOMBIA"`, `"NEQUI"`, etc.
`account_number`	string	✅	Bank account number or wallet ID	`"3990000011"`
`account_type`	string	✅	Account type: `AHORRO`, `CORRIENTE`	`"AHORRO"`

Response Structure

Success Response

Field	Type	Description
`code`	string	Response code (`"01"` = success)
`status`	string	Transaction status (`"SUCCESS"`)
`message`	string	Description of the response
`data`	object	Transaction data object

Data Object

Field	Type	Description
`ticket`	string	Unique transaction identifier (TumiPay ID)
`date`	string	Transaction timestamp (YYYY-MM-DD HH:MM:SS)
`transaction`	object	Transaction details echo

Transaction Status Flow

Status	Description
`PENDING`	Transaction created, processing initiated
`APPROVED`	Funds successfully transferred to recipient
`REJECTED`	Transaction rejected by bank or validation failure

Request Example

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

use reqwest::Client;
use serde_json::json;

async fn make_payout_request() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let response = client.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")
        .json(&json!({
            "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"
            }
        }))
        .send()
        .await?;

    let response_json: serde_json::Value = response.json().await?;
    println!("{:#?}", response_json);

    Ok(())
}

import axios from 'axios';

const makePayoutRequest = async () => {
  try {
    const response = await axios.post('https://api-empresas.staging.topup.com.co/production/api/v1/payout', {
      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'
      }
    }, {
      headers: {
        'Token-Top': 'your_auth_token',
        'Authorization': 'Basic your_auth_key',
        'Content-Type': 'application/json'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

makePayoutRequest();

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-empresas.staging.topup.com.co/production/api/v1/payout',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "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"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Token-Top: your_auth_token',
    'Authorization: Basic your_auth_key',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.io.IOException;

public class PayoutRequest {
    public static void main(String[] args) throws IOException, InterruptedException {
        HttpClient client = HttpClient.newHttpClient();
        String json = "{ \\"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\\" } }";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("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")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
    "strings"
)

func main() {
    url := "https://api-empresas.staging.topup.com.co/production/api/v1/payout"
    method := "POST"

    payload := strings.NewReader(`{
        "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"
        }
    }`)

    client := &http.Client {}
    req, err := http.NewRequest(method, url, payload)

    if err != nil {
        fmt.Println(err)
        return
    }
    req.Header.Add("Token-Top", "your_auth_token")
    req.Header.Add("Authorization", "Basic your_auth_key")
    req.Header.Add("Content-Type", "application/json")

    res, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer res.Body.Close()

    body, err := ioutil.ReadAll(res.Body)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(string(body))
}

Response Example

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

Advanced Integration

For Bre-B integration to send money to digital wallets and bank accounts using unique identifiers, see Bre-B Integration.

​Overview

​Key Features

​Quick Reference

​Request Parameters

​Required Fields

​Customer Data Object

​Response Structure

​Success Response

​Data Object

​Transaction Status Flow

​Request Example

​Response Example

​Advanced Integration