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

> Country-specific information for PayOut transactions in Mexico.

## Overview

Mexico PayOut operates exclusively through **SPEI** (Sistema de Pagos Electrónicos Interbancarios), the interbank real-time settlement network operated by Banco de México. Disbursements are processed asynchronously — the API returns a `PENDING` status immediately, and the final result (`APPROVED` or `REJECTED`) is delivered via webhook.

SPEI supports two destination account types:

| Account Type     | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| `CLABE`          | 18-digit Clave Bancaria Estandarizada — routes to any Mexican bank account |
| `TARJETA_DEBITO` | Routes directly to a Visa or Mastercard debit card number                  |

### Quick Reference

| Parameter         | Value                 | Description                 |
| ----------------- | --------------------- | --------------------------- |
| **Endpoint**      | `POST /api/v1/payout` | Initiate PayOut transaction |
| **Currency**      | `MXN`                 | Mexican Peso                |
| **Country Code**  | `MX`                  | Mexico                      |
| **Auth Required** | Yes                   | Token-Top + Basic Auth      |
| **Processing**    | Async                 | Status updates via webhook  |

***

## Common Request Fields

Both transfer types share the same top-level fields and base `customer_data` fields. The only difference is in the **account-specific fields** documented in each section below.

### Top-level Fields

| Field            | Type   | Description                                    | Example                                     |
| ---------------- | ------ | ---------------------------------------------- | ------------------------------------------- |
| `reference`      | string | Unique transaction identifier from your system | `"PAYOUT-0001"`                             |
| `amount`         | float  | Transaction amount in MXN                      | `250.00`                                    |
| `currency`       | string | ISO 4217 currency code                         | `"MXN"`                                     |
| `payment_method` | string | Always `"SPEI"` for Mexico PayOut              | `"SPEI"`                                    |
| `description`    | string | Transaction description                        | `"Payout SPEI a CLABE"`                     |
| `ipn_url`        | string | Webhook URL for status notifications           | `"https://your-domain.com/webhooks/payout"` |
| `customer_data`  | object | Customer and account information (see below)   | —                                           |

### Base Customer Data Fields

These fields are required for **both** account types:

| Field            | Type   | Description                                                              | Example                    |
| ---------------- | ------ | ------------------------------------------------------------------------ | -------------------------- |
| `legal_doc_type` | string | Document type: `RFC`, `CURP`, `INE`, `PPN`                               | `"RFC"`                    |
| `legal_doc`      | string | Customer's legal document number                                         | `"XAXX010101000"`          |
| `full_name`      | string | Customer full name                                                       | `"Maria Lopez"`            |
| `email`          | string | Customer email address                                                   | `"maria.lopez@correo.com"` |
| `phone_code`     | string | Country calling code                                                     | `"52"`                     |
| `phone_number`   | string | 10-digit phone number                                                    | `"5512345678"`             |
| `bank`           | string | Bank code — see [Supported Banks](/docs/mx/introduction#supported-banks) | `"BBVA_MEXICO"`            |
| `account_type`   | string | `"CLABE"` or `"TARJETA_DEBITO"`                                          | `"CLABE"`                  |
| `account_number` | string | Bank account number                                                      | `"1234567890"`             |

***

## SPEI via CLABE

Use this flow to disburse funds to any Mexican bank account identified by its **18-digit CLABE number**.

### Additional Fields

| Field          | Type   | Required | Description                           | Example                |
| -------------- | ------ | -------- | ------------------------------------- | ---------------------- |
| `account_type` | string | ✅        | Must be `"CLABE"`                     | `"CLABE"`              |
| `clabe_number` | string | ✅        | 18-digit Clave Bancaria Estandarizada | `"032180000118359719"` |

<Note>
  The `clabe_number` must be exactly **18 digits**. CLABE uniquely identifies the destination bank branch and account within Mexico's SPEI network. Incorrect CLABEs will result in rejected transfers.
</Note>

### Request Example

```json theme={null}
{
  "reference": "PAYOUT-0002",
  "amount": 250,
  "currency": "MXN",
  "payment_method": "SPEI",
  "description": "Payout SPEI a CLABE",
  "ipn_url": "https://your-domain.com/webhooks/payout",
  "customer_data": {
    "legal_doc_type": "RFC",
    "legal_doc": "XAXX010101000",
    "full_name": "Maria Lopez",
    "email": "maria.lopez@correo.com",
    "phone_code": "52",
    "phone_number": "5512345678",
    "bank": "BBVA_MEXICO",
    "account_type": "CLABE",
    "account_number": "1234567890",
    "clabe_number": "032180000118359719"
  }
}
```

***

## SPEI via Tarjeta Débito

Use this flow to disburse funds directly to a Visa or Mastercard **debit card number**, without needing a CLABE.

### Additional Fields

| Field              | Type   | Required | Description                                | Example              |
| ------------------ | ------ | -------- | ------------------------------------------ | -------------------- |
| `account_type`     | string | ✅        | Must be `"TARJETA_DEBITO"`                 | `"TARJETA_DEBITO"`   |
| `card_number`      | string | ✅        | 16-digit debit card number                 | `"4111111111111111"` |
| `card_holder_name` | string | ✅        | Name as it appears on the card (uppercase) | `"JUAN PEREZ"`       |

<Note>
  Only **debit cards** (Visa or Mastercard) are supported for this transfer type. Credit cards will be rejected.
</Note>

### Request Example

```json theme={null}
{
  "reference": "PAYOUT-0001",
  "amount": 150.5,
  "currency": "MXN",
  "payment_method": "SPEI",
  "description": "Payout SPEI a tarjeta débito",
  "ipn_url": "https://your-domain.com/webhooks/payout",
  "customer_data": {
    "legal_doc_type": "RFC",
    "legal_doc": "XAXX010101000",
    "full_name": "Juan Perez",
    "email": "juan.perez@correo.com",
    "phone_code": "52",
    "phone_number": "5512345678",
    "bank": "BANAMEX",
    "account_type": "TARJETA_DEBITO",
    "account_number": "1234567890",
    "card_number": "4111111111111111",
    "card_holder_name": "JUAN PEREZ"
  }
}
```

***

## 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, SPEI transfer initiated       |
| `APPROVED` | Funds successfully transferred to recipient        |
| `REJECTED` | Transaction rejected by bank or validation failure |

### Response Example

```json theme={null}
{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "7MXpKRwc3NLQst8",
        "date": "2025-10-15 18:24:11",
        "transaction": {
            "reference": "PAYOUT-0002",
            "amount": 250.00,
            "currency": "MXN",
            "payment_method": "SPEI"
        }
    }
}
```