PayOut - Tumipay API

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

​Overview

​Quick Reference

​Common Request Fields

​Top-level Fields

​Base Customer Data Fields

​SPEI via CLABE

​Additional Fields

​Request Example

​SPEI via Tarjeta Débito

​Additional Fields

​Request Example

​Response Structure

​Success Response

​Data Object

​Transaction Status Flow

​Response Example

Overview

Quick Reference

Common Request Fields

Top-level Fields

Base Customer Data Fields

SPEI via CLABE

Additional Fields

Request Example

SPEI via Tarjeta Débito

Additional Fields

Request Example

Response Structure

Success Response

Data Object

Transaction Status Flow

Response Example