> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.topup.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# PayOut API

> API for initiating PayOut transactions, including supported banks, account types, and preauthorization rules.

# 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](/docs/co/breb))
* **Peru**: `BANK_TRANSFER`
* **Mexico**: `SPEI`

For country-specific details (banks, account types, document types, limits), see the [Colombia](/docs/co/introduction), [Peru](/docs/pe/introduction), and [Mexico](/docs/mx/introduction) configuration pages.

## Transaction Flow

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

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant T as TumiPay API
    participant TF as Transfiya
    participant B as Customer Bank
    participant C as Customer

    M->>T: 1. Create PayOut transaction
    T->>T: 2. Validate request & generate ticket
    T->>M: 3. Return ticket & PENDING status
    T->>TF: 4. Initiate bank transfer
    TF->>TF: 5. Debit funds from merchant account
    TF->>B: 6. Credit funds to customer account
    B->>C: 7. Credit funds to customer's account
    TF->>T: 8. Notify transfer COMPLETED
    T->>T: 9. Update internal balances
    T->>M: 10. Send webhook with final status
```

## 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

<Card title="/api/v1/payout" icon="money-bill-transfer" iconType="solid">
  This endpoint allows you to perform dispersions using methods like TumiPay Wallet and Bank Transfer.
  Transactions are processed asynchronously, ensuring efficiency and reliability.
</Card>

#### Request Headers

<ParamField header="Token-Top" type="string" required>
  Secret token for authorization
</ParamField>

<ParamField header="Authorization" type="string" required>
  Authorization key for access
</ParamField>

#### Request Body

<ParamField body="payment_method" type="string" required>
  Specifies the payment method. See country-specific options:

  * [Colombia](/docs/co/introduction#payment-methods)
  * [Peru](/docs/pe/introduction#payment-methods)
  * [Mexico](/docs/mx/introduction#payment-methods)
</ParamField>

<ParamField body="reference" type="string" required>
  Unique reference for the transaction
</ParamField>

<ParamField body="amount" type="integer" required>
  Amount to be transferred
</ParamField>

<ParamField body="currency" type="string" required>
  Currency for the transaction. Use `COP` for Colombia, `PEN` for Peru, `MXN` for Mexico
</ParamField>

<ParamField body="country" type="string" required>
  Two-letter country code. Possible values: "CO", "PE", "MX"
</ParamField>

<ParamField body="ipn_url" type="string" required>
  Webhook URL to receive transaction status updates
</ParamField>

<ParamField body="customer_data" type="object" required>
  <Expandable title="Customer data object">
    <ParamField body="legal_doc" type="string" required>
      Customer ID number
    </ParamField>

    <ParamField body="legal_doc_type" type="string" required>
      Type of document. See country-specific types:

      * [Colombia](/docs/co/introduction#document-types)
      * [Peru](/docs/pe/introduction#document-types)
      * [Mexico](/docs/mx/introduction#document-types)
    </ParamField>

    <ParamField body="phone_code" type="string" required>
      Country code for the customer's phone number
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      Customer's phone number without country code
    </ParamField>

    <ParamField body="email" type="string" required>
      Customer email address
    </ParamField>

    <ParamField body="full_name" type="string" required>
      Full name of the customer
    </ParamField>

    <ParamField body="bank" type="string" required>
      Destination bank
    </ParamField>

    <ParamField body="account_number" type="string" required>
      Account number of the customer
    </ParamField>

    <ParamField body="account_type" type="string" required>
      Type of destination account. See country-specific types:

      * [Colombia](/docs/co/introduction#account-types)
      * [Peru](/docs/pe/introduction#account-types)
      * [Mexico](/docs/mx/introduction#account-types)
    </ParamField>
  </Expandable>
</ParamField>

#### Response

<ResponseField name="code" type="string" required>
  Response code (see [Error Codes](#error-codes))
</ResponseField>

<ResponseField name="status" type="string" required>
  Status of the transaction (e.g., "SUCCESS")
</ResponseField>

<ResponseField name="message" type="string">
  Transaction result message
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="Transaction data object">
    <ResponseField name="ticket" type="string">
      Unique identifier for the payout
    </ResponseField>

    <ResponseField name="date" type="string">
      Timestamp of the transaction
    </ResponseField>

    <ResponseField name="transaction" type="object">
      <Expandable title="Transaction details">
        <ResponseField name="reference" type="string">
          Client reference identifier
        </ResponseField>

        <ResponseField name="amount" type="integer">
          Transaction amount
        </ResponseField>

        <ResponseField name="currency" type="string">
          Currency code
        </ResponseField>

        <ResponseField name="payment_method" type="string">
          Selected payment method
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  <Tabs>
    <Tab title="cURL">
      ```bash theme={null}
      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"
          }
      }'
      ```
    </Tab>

    <Tab title="JavaScript">
      ```javascript theme={null}
      // 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();
      ```
    </Tab>

    <Tab title="Python">
      ```python theme={null}
      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()
      ```
    </Tab>

    <Tab title="PHP">
      ```php theme={null}
      <?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);
      ?>
      ```
    </Tab>
  </Tabs>
</RequestExample>

### Examples for Mexico

#### SPEI

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

<RequestExample>
  ```bash theme={null}
  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"
      }
  }'
  ```
</RequestExample>

### 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](/docs/co/introduction#banks)
* [Peru - Supported Banks](/docs/pe/introduction#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

```json theme={null}
{
    "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"
        }
    }
}
```

```json Error Response theme={null}
{
  "code": "00",
  "status": "ERROR",
  "error": "VALIDATION_ERROR",
  "message": "El banco especificado no existe"
}
```