Overview
The PayOut API for Mexico enables secure disbursements to bank accounts via SPEI, Mexico’s interbank electronic payments system operated by Banco de México. Transactions are processed asynchronously with webhook notifications for status updates.
Key Features
- Payment Method:
SPEI — Sistema de Pagos Electrónicos Interbancarios
- Currency: Mexican Peso (
MXN)
- Asynchronous Processing: Background processing with webhook notifications
- CLABE Support: 18-digit standardized banking code required for all SPEI transfers
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 |
Request Parameters
Required Fields
| Field | Type | Description | Example |
|---|
payment_method | string | Disbursement method | "SPEI" |
reference | string | Unique transaction identifier from your system | "TXN-MX-OUT-001" |
amount | float | Transaction amount in MXN | 500.00 (= MX$ 500.00) |
currency | string | Three-letter currency code (ISO 4217) | "MXN" |
country | string | Two-letter country code (ISO 3166-1 alpha-2) | "MX" |
ipn_url | string | Webhook URL for transaction status updates | "https://your-domain.com/webhook" |
customer_data | object | Customer and account information (see below) | — |
Customer Data Object
| Field | Type | Required | Description | Example |
|---|
legal_doc | string | ✅ | Customer’s legal document number | "CURP12345678901234" |
legal_doc_type | string | ✅ | Document type: CURP, RFC, INE, PPN, PP | "RFC" |
phone_code | string | ✅ | Country calling code | "52" |
phone_number | string | ✅ | 10-digit phone number without country code | "5512345678" |
email | string | ✅ | Customer email address | "johndoe@email.com" |
full_name | string | ✅ | Customer full name | "John Doe" |
account_number | string | ✅ | Destination account number | "123456789012345678" |
account_type | string | ✅ | Account type: SPEI, CLABE | "CLABE" |
The account_number must be a valid 18-digit CLABE when account_type is CLABE. CLABE (Clave Bancaria Estandarizada) is required for all SPEI transfers in Mexico and uniquely identifies the destination bank and account.
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 |
Examples
Request Example
curl --request POST 'https://api-empresas.staging.tumipay.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": "TXN-MX-OUT-001",
"amount": 500.00,
"currency": "MXN",
"country": "MX",
"ipn_url": "https://your-domain.com/webhook",
"customer_data": {
"legal_doc": "CURP12345678901234",
"legal_doc_type": "RFC",
"phone_code": "52",
"phone_number": "5512345678",
"email": "johndoe@email.com",
"full_name": "John Doe",
"account_number": "123456789012345678",
"account_type": "CLABE"
}
}'
Response Example
{
"code": "01",
"status": "SUCCESS",
"message": "Operacion exitosa",
"data": {
"ticket": "7MXpKRwc3NLQst8",
"date": "2025-10-15 18:24:11",
"transaction": {
"reference": "TXN-MX-OUT-001",
"amount": 500.00,
"currency": "MXN",
"payment_method": "SPEI"
}
}
}
