> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tonder.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Accept SPEI Bank Transfers

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.

<Info>
  For detailed operational information about SPEI including operating hours, processing times, and holiday calendar, see the [Payment Methods Reference](/direct-integration/payment-methods/payment-methods-reference#spei-operational-information) page.
</Info>

## 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](/reference/overview) will generate payment instructions for your customer.

```json theme={null}
{
  "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](/reference/process-transaction) endpoint to initiate the SPEI transfer:

```bash theme={null}
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](/reference/overview) 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.

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "pending",
  "amount": 500.00,
  "currency": "MXN",
  "next_action": {
    "redirect_to_url": {
      "url": "https://stage-payflow.tonder.io/spei?clabe=710969000000629935&transaction_reference=B030516028bb286&amount=100.0&return_url=https%3A%2F%2Ftonder.io%3Ftndr_payment_id%3D63772&debug=true&business_id=117&acquirer=SPEIV2",
      "return_url": "https://tonder.io?tndr_payment_id=63772",
      "verify_transaction_status_url": "/transactions/21cbe500-b320-4e0d-9186-9fb63c3d9617/"
    }
  },
  "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:

<Steps>
  <Step title="Share the bank account details">
    Provide the `bank_account` number and `bank_name` from the response.
  </Step>

  <Step title="Provide the payment reference">
    Give the customer the `reference` number - this is crucial for payment identification.
  </Step>

  <Step title="Set expectations">
    Explain that SPEI transfers are processed in real-time during operating hours.
  </Step>

  <Step title="Monitor payment status">
    Use [webhooks](/direct-integration/webhooks/how-webhooks-works) or polling to track when the payment is completed.
  </Step>
</Steps>

## 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](/direct-integration/webhooks/how-webhooks-works) provide real-time notifications when payment status changes. Set up webhooks to receive status updates automatically:

```json theme={null}
{
  "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](/reference/get-transaction-status) endpoint:

```bash theme={null}
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:

<AccordionGroup>
  <Accordion title="Operating Hours">
    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.
  </Accordion>

  <Accordion title="Amount Limits">
    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.
  </Accordion>

  <Accordion title="Common Errors">
    Understanding common SPEI errors will help you handle issues effectively:

    | Error              | Cause                      | Solution                                 |
    | ------------------ | -------------------------- | ---------------------------------------- |
    | `invalid_amount`   | Amount exceeds bank limits | Use smaller amount or split transaction  |
    | `spei_unavailable` | Temporary service issue    | Retry later or offer alternative payment |
  </Accordion>
</AccordionGroup>

## Next Steps

* Set up [webhooks](/direct-integration/webhooks/how-webhooks-works) to receive real-time notifications when SPEI status changes.
* Learn about [HTTP response codes](/direct-integration/http-response-codes) to handle different API responses.
* Explore other [payment methods](/direct-integration/payment-methods/payment-methods-overview) for customers without bank accounts.