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

# POST Initiate PayOut Transaction

> Initialize a new PayOut transaction for disbursement

Initialize a new PayOut transaction for disbursement to bank accounts.

This endpoint allows you to send money to your customers' bank accounts using bank transfers.

```bash Curl theme={null}
curl --request POST 'https://api-empresas.uat.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"
    }
}'
```

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

## Required Headers

**Token-Top** `string` *required*

Your merchant authentication token

**Authorization** `string` *required*

Basic authentication key

**Content-Type** `string` *required*

Must be "application/json"

## Request Body Parameters

**payment\_method** `string` *required*

Payment method. Supported methods: `BANK_TRANSFER`, `BREB`. Refer to [Country-Specific Information](https://docs.v2.topup.com.co/docs/introduction.md#country-specific-information) for the list of available methods per country.

For Bre-B integration details, see [Bre-B Integration](https://docs.v2.topup.com.co/docs/co/breb.md). Availability varies by country.

**reference** `string` *required*

Your unique transaction reference

**amount** `number` *required*

Transaction amount in the specified currency code.

**currency** `string` *required*

Three-letter currency code following the ISO 4217 standard (e.g., `COP`, `PEN`).

**country** `string` *required*

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

**ipn\_url** `string` *required*

URL for receiving webhook notifications

**customer\_data** `object` *required*

**Customer data object**

**legal\_doc** `string` *required*

Customer ID number

**legal\_doc\_type** `string` *required*

Type of document. See [Country-Specific Information](https://docs.v2.topup.com.co/docs/introduction.md#country-specific-information) for available document types.

**phone\_code** `string` *required*

Country code for the customer's phone number

**phone\_number** `string` *required*

Customer's phone number without country code

**email** `string` *required*

Customer email address

**full\_name** `string` *required*

Full name of the customer

**bank** `string` *required*

Destination bank. See [Country-Specific Information](https://docs.v2.topup.com.co/docs/introduction.md#country-specific-information) for available banks.

**account\_number** `string` *required*

Account number of the customer

**account\_type** `string` *required*

Type of destination account. See [Country-Specific Information](https://docs.v2.topup.com.co/docs/introduction.md#country-specific-information) for available account types.

**metadata** `object`

Additional custom data for the transaction

## Response

**ticket** `string`

Unique transaction identifier (UUID v4 format)

**reference** `string`

Your provided transaction reference (must be unique)

**status** `string`

Initial transaction status (will be PENDING)

**estimated\_time** `string`

Estimated completion time in UTC (typically within 24 hours)


## OpenAPI

````yaml post /payout
openapi: 3.0.0
info:
  title: PayOut API
  version: 1.0.0
  description: API for disbursement operations
servers:
  - url: https://api-empresas.uat.topup.com.co/production/api/v1
    description: UAT server
security: []
paths:
  /payout:
    post:
      summary: Initiate PayOut Transaction
      description: Initialize a new PayOut transaction for disbursement
      operationId: initiatePayOut
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payment_method
                - reference
                - amount
                - currency
                - ipn_url
                - customer_data
                - country
              properties:
                payment_method:
                  type: string
                  enum:
                    - BANK_TRANSFER
                  description: Payment method
                reference:
                  type: string
                  description: Your unique transaction reference
                amount:
                  type: number
                  description: Amount in COP
                currency:
                  type: string
                  description: Three-letter currency code (ISO 4217)
                  example: COP
                ipn_url:
                  type: string
                  format: uri
                  description: URL for receiving webhook notifications
                customer_data:
                  type: object
                  required:
                    - legal_doc
                    - legal_doc_type
                    - phone_code
                    - phone_number
                    - email
                    - full_name
                    - bank
                    - account_number
                  properties:
                    legal_doc:
                      type: string
                      description: Customer ID number.
                    legal_doc_type:
                      type: string
                      enum:
                        - CC
                        - CE
                        - PPN
                        - NIT
                        - DNI
                        - RUC
                      description: Type of document.
                    phone_code:
                      type: string
                      description: Country code for the customer's phone number.
                    phone_number:
                      type: string
                      description: Customer's phone number without country code.
                    email:
                      type: string
                      format: email
                      description: Customer email address.
                    full_name:
                      type: string
                      description: Full name of the customer.
                    bank:
                      type: string
                      description: Destination bank.
                    account_number:
                      type: string
                      description: Account number of the customer.
                    account_type:
                      type: string
                      description: Type of destination account.
                      enum:
                        - AHORRO
                        - CORRIENTE
                        - WALLET
                metadata:
                  type: object
                  description: Additional custom data for the transaction
                  additionalProperties: true
                country:
                  type: string
                  description: >-
                    Two-letter country code (ISO 3166-1 alpha-2). Possible
                    values: CO, PE, MX
                  example: CO
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    type: string
                    description: Unique transaction identifier
                  reference:
                    type: string
                    description: Your provided transaction reference
                  status:
                    type: string
                    enum:
                      - PENDING
                    description: Initial transaction status
                  estimated_time:
                    type: string
                    format: date-time
                    description: Estimated completion time (UTC)
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '422':
          description: Validation error
      security:
        - Token-Top: []
          BasicAuth: []
components:
  securitySchemes:
    Token-Top:
      type: apiKey
      name: Token-Top
      in: header
      description: Merchant authentication token
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication with username and password

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.