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

# SPEI Transfers

> Accept bank transfers in Mexico with instant settlement

## What is SPEI?

SPEI (Sistema de Pagos Electrónicos Interbancarios) is Mexico's instant payment system. Offer your customers a bank-to-bank payment option with lower fees than cards.

SPEI enables instant bank transfers 24/7 between any Mexican bank accounts using CLABE numbers.

## When to Use SPEI

<CardGroup cols={2}>
  <Card title="Large Transactions" icon="money-bill-wave">
    Lower processing fees make SPEI ideal for high-value orders
  </Card>

  <Card title="Customer Preference" icon="user-check">
    Some customers prefer bank transfers over cards
  </Card>

  <Card title="B2B Payments" icon="building">
    Business customers often prefer bank transfers
  </Card>

  <Card title="Alternative Payment" icon="arrows-left-right">
    Offer as an alternative when cards decline
  </Card>
</CardGroup>

## How SPEI Works

<Steps>
  <Step title="Create Payment Request">
    You create a payment request with SPEI as the payment method.
  </Step>

  <Step title="CLABE Assigned">
    Cheqpay assigns a unique CLABE account number for this payment.
  </Step>

  <Step title="Customer Transfers">
    Display the CLABE to your customer who transfers funds from their bank.
  </Step>

  <Step title="Instant Confirmation">
    Payment is confirmed automatically (usually within minutes).
  </Step>

  <Step title="Webhook Notification">
    You receive a webhook notification when funds are received.
  </Step>
</Steps>

<Tip>
  SPEI transfers typically complete within minutes but can take up to 24 hours.
</Tip>

## Create a SPEI Payment

```http theme={null}
POST /v2/payment-orders
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json
```

### Request Example

```json theme={null}
{
  "externalId": "order-124",
  "customer": {
    "firstName": "Carlos",
    "lastName": "Hernández",
    "email": "carlos@example.com",
    "phoneNumber": "+521555987654"
  },
  "amount": 50000,
  "currency": "MXN",
  "description": "Large order payment",
  "paymentMethod": {
    "type": "spei"
  }
}
```

### Response with CLABE

```json theme={null}
{
  "paymentOrder": {
    "id": "ord_def456",
    "externalId": "order-124",
    "status": "PENDING",
    "amount": 50000,
    "currency": "MXN",
    "description": "Large order payment"
  },
  "paymentMethod": {
    "type": "spei",
    "options": {
      "spei": {
        "clabe": "646180111234567890",
        "bankName": "STP"
      }
    }
  },
  "customer": {
    "id": "cus_abc789",
    "firstName": "Carlos",
    "lastName": "Hernández",
    "email": "carlos@example.com"
  }
}
```

## Display Payment Instructions

Show the CLABE number prominently so customers can complete the transfer:

### Required Information

<CardGroup cols={2}>
  <Card title="CLABE Number" icon="hashtag">
    18-digit unique account identifier
  </Card>

  <Card title="Bank Name" icon="building-columns">
    Receiving bank (usually STP)
  </Card>

  <Card title="Amount" icon="dollar-sign">
    Exact amount to transfer
  </Card>

  <Card title="Reference" icon="receipt">
    Order number or payment reference
  </Card>
</CardGroup>

### Example Display

```html theme={null}
<div class="payment-instructions">
  <h2>Complete Your Payment</h2>
  <p>Transfer the exact amount to the following CLABE:</p>

  <div class="clabe-display">
    <strong>CLABE:</strong> 646180111234567890
    <button onclick="copyToClipboard()">Copy</button>
  </div>

  <div class="payment-details">
    <p><strong>Bank:</strong> STP</p>
    <p><strong>Amount:</strong> $500.00 MXN</p>
    <p><strong>Reference:</strong> Order #124</p>
  </div>

  <p class="note">
    Payment will be confirmed automatically within minutes.
  </p>
</div>
```

<Warning>
  Customer must transfer the **exact amount**. Incorrect amounts may delay payment confirmation.
</Warning>

## Monitor Payment Status

SPEI payments start with status `PENDING` and update to `COMPLETED` when funds are received.

### Polling (Not Recommended)

```bash theme={null}
curl -X GET https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/ord_def456 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID"
```

### Webhooks (Recommended)

Use webhooks to receive instant notifications:

```json theme={null}
{
  "eventType": "spei.deposit_received",
  "data": {
    "paymentOrderId": "ord_def456",
    "status": "COMPLETED",
    "amount": 50000
  }
}
```

<Card title="Set Up Webhooks" icon="webhook" href="/features/webhooks">
  Learn how to receive real-time SPEI notifications
</Card>

## SPEI Best Practices

<AccordionGroup>
  <Accordion title="Unique CLABE Per Payment" icon="fingerprint">
    Each CLABE is unique per payment order. Never reuse CLABEs across different orders.
  </Accordion>

  <Accordion title="Display Instructions Clearly" icon="eye">
    Make the CLABE number easy to copy. Provide clear instructions on how to complete the transfer.
  </Accordion>

  <Accordion title="Send Email Instructions" icon="envelope">
    Email the CLABE to customers so they can complete the transfer later from their bank.
  </Accordion>

  <Accordion title="Set Expiration Time" icon="clock">
    Consider setting a payment expiration (e.g., 24 hours) to avoid indefinite pending orders.
  </Accordion>

  <Accordion title="Use Webhooks" icon="bell">
    Don't poll for updates. Use webhooks to get instant notifications when payments complete.
  </Accordion>
</AccordionGroup>

## SPEI Payment Timeline

| Time      | Event                                       |
| --------- | ------------------------------------------- |
| 0 min     | Payment created, CLABE assigned             |
| 0-10 min  | Customer initiates transfer from their bank |
| 2-30 min  | Transfer completes (most common)            |
| Up to 24h | Maximum time for transfer to complete       |

<Note>
  Most SPEI transfers complete within 5-10 minutes during business hours.
</Note>

## Testing SPEI in Sandbox

SPEI payments in sandbox automatically complete after 30 seconds:

<Steps>
  <Step title="Create SPEI Payment">
    Make a payment request with `type: "spei"` in sandbox.
  </Step>

  <Step title="Wait 30 Seconds">
    Sandbox simulates the bank transfer delay.
  </Step>

  <Step title="Auto-Complete">
    Payment status automatically updates to `COMPLETED`.
  </Step>
</Steps>

<Tip>
  No need to actually transfer funds in sandbox - payments auto-complete for testing.
</Tip>

## Handling Payment Failures

SPEI payments rarely fail, but here are potential issues:

| Issue                    | Solution                                 |
| ------------------------ | ---------------------------------------- |
| Wrong amount transferred | Contact support to reconcile             |
| Transfer not received    | Check customer's bank confirmation       |
| CLABE expired            | Create new payment with fresh CLABE      |
| Bank system down         | Wait and retry, banks have 99.9%+ uptime |

## Fees and Limits

### Processing Fees

SPEI typically has lower fees than card payments:

* Card payments: \~3.5% + fees
* SPEI transfers: Flat fee per transaction

<Note>
  Contact [sales@cheqpay.com](mailto:sales@cheqpay.com) for current SPEI pricing.
</Note>

### Transaction Limits

* **Minimum:** \$1.00 MXN
* **Maximum:** \$8,000,000.00 MXN per transaction
* **Daily limit:** Contact support for high-volume needs

## Next Steps

<CardGroup cols={2}>
  <Card title="Accept Card Payments" icon="credit-card" href="/features/card-payments">
    Offer cards as primary payment method
  </Card>

  <Card title="Set Up Webhooks" icon="webhook" href="/features/webhooks">
    Get notified when SPEI transfers complete
  </Card>

  <Card title="Handle Refunds" icon="rotate-left" href="/features/refunds">
    Learn about SPEI refund processing
  </Card>

  <Card title="Test Integration" icon="flask" href="/guides/testing">
    Test SPEI payments in sandbox
  </Card>
</CardGroup>