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.
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 | "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" |
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.
Request Example
{
"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" |
Only debit cards (Visa or Mastercard) are supported for this transfer type. Credit cards will be rejected.
Request Example
{
"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
{
"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"
}
}
}
