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

<RequestExample>
  ```bash Curl 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": "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"
      }
  }'
  ```
</RequestExample>

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

## Required Headers

<ParamField header="Token-Top" type="string" required>
  Your merchant authentication token
</ParamField>

<ParamField header="Authorization" type="string" required>
  Basic authentication key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be "application/json"
</ParamField>

## Request Body Parameters

<ParamField body="payment_method" type="string" required>
  Payment method. Supported methods: <code>BANK\_TRANSFER</code>, <code>BREB</code>. Refer to [Country-Specific Information](/docs/introduction#country-specific-information) for the list of available methods per country.

  For Bre-B integration details, see [Bre-B Integration](/docs/co/breb). Availability varies by country.
</ParamField>

<ParamField body="reference" type="string" required>
  Your unique transaction reference
</ParamField>

<ParamField body="amount" type="number" required>
  Transaction amount in the specified currency code.
</ParamField>

<ParamField body="currency" type="string" required>
  Three-letter currency code following the ISO 4217 standard (e.g., <code>COP</code>, <code>PEN</code>).
</ParamField>

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

<ParamField body="ipn_url" type="string" required>
  URL for receiving webhook notifications
</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 Information](/docs/introduction#country-specific-information) for available 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. See [Country-Specific Information](/docs/introduction#country-specific-information) for available banks.
    </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 Information](/docs/introduction#country-specific-information) for available account types.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom data for the transaction
</ParamField>

## Response

<ResponseField name="ticket" type="string">
  Unique transaction identifier (UUID v4 format)
</ResponseField>

<ResponseField name="reference" type="string">
  Your provided transaction reference (must be unique)
</ResponseField>

<ResponseField name="status" type="string">
  Initial transaction status (will be PENDING)
</ResponseField>

<ResponseField name="estimated_time" type="string">
  Estimated completion time in UTC (typically within 24 hours)
</ResponseField>


## 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.staging.topup.com.co/production/api/v1
    description: Staging 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: Transaction amount (in cents/minor currency unit)
                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

````