SPEI

SPEI (Sistema de Pagos Electrónicos Interbancarios) is an electronic payment system in Mexico, supported by EBANX, that allows customers to make real-time bank transfers. SPEI is widely used for online purchases, offering a fast, secure, and convenient way for customers to transfer funds directly from their bank accounts to merchants. It is popular in Mexico due to its accessibility, as it supports most local banks, and its ability to process transactions quickly and securely without the need for credit or debit cards. It’s ideal for customers who prefer to use bank transfers over card-based payments.

How it works

• Customer selects SPEI - At checkout, your customer chooses SPEI as the payment method.
• Generate payment voucher - EBANX generates a payment voucher with the transfer details, including a unique reference code and the total amount to be transferred.
• Customer completes bank transfer - Your customer logs in to their online banking platform and completes the transfer using the provided reference code.
• Real-time confirmation - Once the transfer is made, the transaction is processed in real-time, and EBANX receives confirmation.
• Merchant notified - EBANX notifies you of the completed payment, allowing you to proceed with order fulfillment.

This process ensures secure and real-time payments directly from the customer’s bank account using SPEI.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Define your parameters

   SPEI operates as a voucher-based payment method, so you will need to redirect your customer to a page displaying the voucher. To obtain this redirection link, call the ws/direct endpoint with the required parameters.

   
   

   Defining API parameters

   You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.
   
   

   Essential parameters

   • payment.payment_type_code - Specifies the payment method to be used for the transaction.
   • payment.currency_code - Three-letter code of the payment currency.
   • payment.amount_total - Total amount to be charged.

   
   

   Additional parameters

   • EBANX Integration Key - Used to authenticate and authorize API requests.
   • Customer Information
     • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
     • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
   • Additional Context - Extra data for specific methods or countries.

   
   

   To learn more about API parameters, please refer to the

   API Reference Guide chevron_right

   At the API Reference Guide, select Mexico and SPEI from the dropdown menues.

3. Sample request

   Use the following example to initiate a request.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{your_EBANX_integration_key}",
       "operation": "request",
       "payment": {
         "name": "Juan Garcia",
         "email": "juangarcia@example.com",
         "phone_number": "0405777687", // Optional
         "country": "mx",
         "payment_type_code": "spei", // Set to 'spei'
         "merchant_payment_code": "0x0W28D03-T05",
         "currency_code": "MXN",
         "amount_total": "6000"
       }
     }'

4. Sample response

   A successful request will return a JSON response like the example below.

   Notable Parameters

   • The voucher link will be located in the payment.spei_url parameter
   • The customer’s CLABE account will be in payment.clabe_account
   • The current payment will be in payment.clabe_reference.

   A CLABE account refers to a CLABE number (Clave Bancaria Estandarizada), which is a standardized 18-digit bank account number used in Mexico for electronic funds transfers.

   
   

   {
     "payment": {
       "hash": "5efcb917129a9a5a175e5c918fea0651ba6bf1e6fb6ae593",
       "country": "mx",
       "merchant_payment_code": "0x0W28D03-T05",
       "order_number": null,
       "status": "PE",
       "status_date": null,
       "open_date": "2020-07-01 16:25:58",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "6000.00",
       "amount_ext": "6000.00",
       "amount_iof": "0.00",
       "amount_ext_requested": "6000.00",
       "currency_rate": "1.0000",
       "currency_ext": "MXN",
       "due_date": "2020-07-04",
       "instalments": "1",
       "payment_type_code": "spei",
       "clabe_account": "000000000000000000",
       "clabe_reference": "0000000",
       "spei_url": "https://sandbox.ebanxpay.com/print/spei/execute?hash=5efcb917129a9a5a175e5c918fea0651ba6bf1e6fb6ae593",
       "pre_approved": false,
       "capture_available": null
     },
     "status": "SUCCESS"
   }
   At this stage, the payment will appear as pending (PE) in your

   EBANX Dashboardchevron_right

5. Redirect customer to the returned URL

   Redirect your customer to the URL provided in the spei_url parameter. Once redirected, they will see an voucher similar to the one below:

   

6. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification that status has changed, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

7. Congratulations!

   You have succesfully integrated SPEI.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.