This guide shows you how to accept SPEI (Sistema de Pagos Electrónicos Interbancarios) bank transfers in Mexico. SPEI enables real-time bank-to-bank transfers and is perfect for higher-value transactions where customers prefer bank payments.
For detailed operational information about SPEI including operating hours, processing times, and holiday calendar, see the Payment Methods Reference page.

​
When to Use SPEI

SPEI (Sistema de Pagos Electrónicos Interbancarios) is Mexico’s real-time bank transfer system, perfect for:
  • Higher-value transactions (B2B payments).
  • Customers who prefer bank transfers over cards.
  • Transactions requiring immediate processing during business hours.
  • Reducing card processing fees for large amounts.

​
Step 1: Create a SPEI Payment Request

Creating a SPEI payment request is straightforward since SPEI doesn’t require additional customer data beyond basic information. The API will generate payment instructions for your customer. 
{
  "operation_type": "payment",
  "amount": 500.00,
  "currency": "MXN",
  "customer": {
    "name": "Carlos Eduardo López",
    "email": "carlos.lopez@empresa.mx"
  },
  "payment_method": {
    "type": "SPEI"
  },
  "client_reference": "invoice-456"
}

​
Step 2: Send the Payment Request

Send your payment request to the Process Transaction endpoint to initiate the SPEI transfer: 
curl -X POST https://stage.tonder.io/api/v1/process/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "payment",
    "amount": 500.00,
    "currency": "MXN",
    "customer": {
      "name": "Carlos Eduardo López",
      "email": "carlos.lopez@empresa.mx"
    },
    "payment_method": {
      "type": "SPEI"
    },
    "client_reference": "invoice-456"
  }'

​
Step 3: Handle the Response

The API response will include payment instructions and status information. SPEI payments always start with a pending status since they require the customer to complete the bank transfer. 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "pending",
  "amount": 500.00,
  "currency": "MXN",
  "payment_instructions": {
    "bank_account": "123456789012345678",
    "bank_name": "Banco Receptor",
    "reference": "SPEI789456123",
    "instructions": [
      "Realiza una transferencia SPEI a la cuenta indicada",
      "Usa la referencia proporcionada",
      "El pago será procesado inmediatamente"
    ]
  },
  "created_at": "2024-07-26T10:30:00Z"
}

​
Step 4: Provide Instructions to Your Customer

Present the payment instructions clearly to help customers complete their bank transfer successfully:
1

Share the bank account details

Provide the bank_account number and bank_name from the response.
2

Provide the payment reference

Give the customer the reference number - this is crucial for payment identification.
3

Set expectations

Explain that SPEI transfers are processed in real-time during operating hours.
4

Monitor payment status

Use webhooks or polling to track when the payment is completed.

​
Step 5: Track Payment Status

Monitor the payment status to know when the transfer is completed. SPEI payments follow this status flow:
  1. pending - Waiting for customer to make transfer
  2. processing - Bank transfer in progress
  3. success - Payment completed successfully
Webhooks provide real-time notifications when payment status changes. Set up webhooks to receive status updates automatically: 
{
  "event": "payment.status_changed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "amount": 500.00,
    "completed_at": "2024-07-26T10:45:00Z"
  }
}
Alternatively, poll the transaction status using the Get Transaction Status endpoint: 
curl -X GET https://stage.tonder.io/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Token YOUR_API_KEY"

​
Step 6: Handle SPEI-Specific Scenarios

Understanding SPEI’s unique characteristics will help you provide a better customer experience:
SPEI operates 24/7, but some banks may have their own restrictions that affect processing times:
  • Most transfers process immediately.
  • Some banks may batch transfers during off-hours.
  • Transfers between participating banks are typically instant.
SPEI has flexible limits that make it suitable for various transaction sizes:
  • Minimum: Usually $1 MXN.
  • Maximum: Varies by bank (commonly $8,000,000 MXN per day).
  • No Tonder-imposed limits on SPEI amounts.
Understanding common SPEI errors will help you handle issues effectively:
ErrorCauseSolution
invalid_amountAmount exceeds bank limitsUse smaller amount or split transaction
spei_unavailableTemporary service issueRetry later or offer alternative payment

​
Next Steps

  • Set up webhooks to receive real-time notifications when SPEI status changes.
  • Learn about HTTP response codes to handle different API responses.
  • Explore other payment methods for customers without bank accounts.