Skip to main content

Bank Transfer (SPEI)

  POST https://api-sandbox.letpay.io/spei/simple

Overview​

SPEI (Sistema de Pagos Electrónicos Interbancarios) is a real-time bank transfer system created by the Bank of Mexico that allows customers to pay for online purchases directly from their own banking portal. When a customer chooses SPEI at checkout, they receive a unique CLABE number and a payment reference. The customer then uses these details to initiate the transfer through their personal online banking or mobile app, completing the payment in seconds, 24/7. For merchants, SPEI is an essential payment method for engaging any customer with a bank account in Mexico. Transactions are highly secure and, once confirmed, are final and cannot be reversed, which eliminates the risk of chargebacks.

Reference Checkout UI SPEI

Reference UI - SPEI - Part 1Reference UI - SPEI - Part 1

SPEI Generated​

Reference UI - SPEI - Part 2Reference UI - SPEI - Part 2

Reference Checkout UI SPEI Email​

Upon successful creation of a payment order via the API, an automated confirmation email is sent to the address provided in the person.email field of your request. This email contains a copy of the payment instructions for the user's convenience.

Reference UI - SPEI - Part 3 - EmailReference UI - SPEI - Part 3 - Email

SPEI Flow​

Request Body​

  • contract_id (required/string): Merchant's contract id.
  • payment (required/object): The payment data:
    • amount (float/required): Total amount of the payment. Value must have a maximum of two decimal places.
    • asset (optional/string): Reference code for asset for the sale's amount. Default: MXN.
    • currency (required/string): Currency code in ISO-4217.
    • country (required/string): Country code in ISO 3166-2.
    • spei (optional/object): The SPEI payment data:
      • description (optional/string): This is a message that goes attached to the transaction and will show at the recipient's bank statement.
      • logo (optional/string): The HTTP/Data URL of your logo (must be JPG or PNG format and it is recommended to be proportional to 200 x 45 pixels). If omitted, no logo will be displayed.
  • person (required/object): The person data:
    • full_name (required/string): Person’s full name.
    • email (required/string): Person’s email provided to the merchant.
  • notification_url (required/required): URL to post callbacks to this payment.
  • reference_id (required/required/max 45 chars): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
  • extra_data (optional/JSON): Any data pertinent to the merchant.
  • ip_address (optional/string): Remote IP Address(IPv4/IPv6).

Response Body​

  • transaction_status (string): Current status of the payment.
  • payment_token (string): Unique payment identification for this payment.
  • reference_id (string): External code created by the merchant to reference this payment (e.g. order number).
  • pdf_gzip_base_64 (string): Payment confirmation in Base64 zipped PDF format.
  • clabe (string): Unique interbank CLABE.
  • amount (string): Amount of this payment.
  • refresh_token (string): Updated access token for future calls.
  • totals (object): The payment totals:
    • amount (float): Amount in default region asset.
    • asset (string): Asset used in this amount.
    • original_amount (float): Amount as informed by merchant.
    • original_asset (string): Asset used in this originalAmount.
    • customer_fees (float): Total calculated fee assigned to customer.
    • customer_amount (float): Total amount for customer (amount + customer_fees).
  • customer_fees (object): List of incident customer fees and respective values.

Authorization​

AUTHORIZATIONAPI Key
KeyX-Auth-Token
ValueMY_ACCESS_TOKEN

Body Raw(json)​

json
{
    "contract_id": "MY_CONTRACT_ID",
    "reference_id": "MY_REFERENCE_ID",
    "notification_url": "https://my.notification.url/callback/",
    "ip_address": "0.0.0.0",
    "payment": {
        "amount": 123.45,
        "asset": "MXN",
        "currency": "MXN",
        "country": "MX",
        "spei": {
            "description": "Payment via SPEI",
            "logo": "data:image/png;base64,BASE64_ENCODED_IMAGE"
        }
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]"
    },
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

Example Request​

Example Request​

200 - Success
    curl --location 'https://api-sandbox.letpay.io/spei/simple' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data-raw '{
        "contract_id": "MY_CONTRACT_ID",
        "reference_id": "MY_REFERENCE_ID",
        "notification_url": "https://my.notification.url/callback/",
        "ip_address": "0.0.0.0",
        "payment": {
            "amount": 123.45,
            "asset": "MXN",
            "currency": "MXN",
            "country": "MX",
            "spei": {
                "description": "Payment via SPEI",
                "logo": "data:image/png;base64,BASE64_ENCODED_IMAGE"
            }
        },
        "person": {
            "full_name": "Alice Sonnentag",
            "email": "[email protected]"
        },
        "extra_data": {
            "my-conciliation-number": "xxxxxx"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "transaction_status": "PROCESSING",
      "payment_token": "0196e128-c6c7-4249-9f20-21a4c2eb1506",
      "reference_id": "MY_REFERENCE_ID",
      "pdf_gzip_base_64": "BASE64_ZIPPED_PDF",
      "clabe": "646180179900004256",
      "amount": "123.45",
      "refresh_token": "MY_ACCESS_TOKEN",
      "totals": {
        "amount": 123.45,
        "original_amount": 123.45,
        "original_asset": "MXN",
        "customer_fees": 0,
        "customer_amount": 123.45,
        "asset": "MXN"
      },
      "customer_fees": {}
    }