SPEI Transfers
With Mercado Pago's Checkout API, it is also possible to offer payments via SPEI Transfers, a service that allows payments to be made from any bank or financial institution using the CLABE (Clave Bancaria Estandarizada).
If you already set up your environment and want to offer payments with SPEI Transfer, follow the steps below.
processing_mode parameter. For more information, visit the section Integration model.To be able to receive payments, you need to add a form in the frontend that securely captures the payer's information.
If you already have a development that includes your own payment form, make sure to include SPEI Transfer among the payment options you want to offer, as indicated below, and continue to the Submit payment step.
If you do not have a payment form, add the one below to your project, including the identifier for SPEI Transfer among the payment methods to be offered.
| Payment method | payment_method_id |
| SPEI Transfer | clabe |
html<form id="form-checkout" action="/process_payment" method="post"> <div> <div> <label for="payerFirstName">Nombre</label> <input id="form-checkout__payerFirstName" name="payerFirstName" type="text"> </div> <div> <label for="payerLastName">Appelido</label> <input id="form-checkout__payerLastName" name="payerLastName" type="text"> </div> <div> <label for="email">E-mail</label> <input id="form-checkout__email" name="email" type="text"> </div> <div> <label for="identificationType">Tipo de documento</label> <select id="form-checkout__identificationType" name="identificationType" type="text"></select> </div> <div> <label for="identificationNumber">Número del documento</label> <input id="form-checkout__identificationNumber" name="identificationNumber" type="text"> </div> </div> <div> <div> <input type="hidden" name="transactionAmount" id="transactionAmount" value="100"> <input type="hidden" name="description" id="description" value="Nome do Produto"> <br> <button type="submit">Pagar</button> </div> </div> </form>
The payment submission must be made by creating an order that contains associated payment transactions.
To do this, send a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix. and the required parameters listed below to the endpoint /v1/ordersPOST.
curlcurl --location 'https://api.mercadopago.com/v1/orders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ --data '{ "type": "online", "external_reference": "ext_ref_1234", "processing_mode": "automatic", "total_amount": "50.00", "payer": { "email": "test_payer@example.com" }, "config": { "location": { "state_id": "MX-DIF" } }, "transactions": { "payments": [ { "amount": "50.00", "expiration_time": "P3D", "payment_method": { "id": "clabe", "type": "bank_transfer" } } ] } }'
429 Too Many Requests error, wait the time indicated in the Retry-After response header before retrying. See Possible errors for more details.See the table below for descriptions of the parameters that are mandatory in the request and those that, although optional, have some important particularity that should be highlighted.
| Parameter | Type | Description | Requirement |
Authorization | Header | Refers to your private key, the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix.. | Required |
X-Idempotency-Key | Header | Idempotency key. It is used to ensure that each request is processed only once, avoiding duplications. Use a unique value in the header of your request, such as a UUID V4 or random strings. | Required |
processing_mode | Body. String | Processing mode of the order. The possible values are: - automatic: to create and process the order in automatic mode. - manual: to create the order and process it later. For more information, visit the section Integration model. | Required |
expiration_time | Body. String | When an order is created in manual mode (processing_mode=manual), this parameter lets you define its expiration time using the ISO 8601 duration format. The period starts at created_date and the maximum limit is 2920 hours. If not sent, the default value will be P1D (one day). This parameter must not be sent when creating an order in automatic mode (processing_mode=automatic). | Optional |
config.location | Body. Object | Information about the payer's location. | Optional |
config.location.state_id | Body. String | Code of the payer's state, province, or administrative region, formed by the two-letter country code, followed by a hyphen and the location code. See the accepted values.Aguascalientes (MX-AGU); Baja California (MX-BCN); Baja California Sur (MX-BCS); Campeche (MX-CAM); Chiapas (MX-CHP); Chihuahua (MX-CHH); Coahuila (MX-COA); Colima (MX-COL); Distrito Federal (MX-DIF); Durango (MX-DUR); Estado De México (MX-MEX); Guanajuato (MX-GUA); Guerrero (MX-GRO); Hidalgo (MX-HID); Jalisco (MX-JAL); Michoacán (MX-MIC); Morelos (MX-MOR); Nayarit (MX-NAY); Nuevo León (MX-NLE); Oaxaca (MX-OAX); Puebla (MX-PUE); Querétaro (MX-QUE); Quintana Roo (MX-ROO); San Luis Potosí (MX-SLP); Sinaloa (MX-SIN); Sonora (MX-SON); Tabasco (MX-TAB); Tamaulipas (MX-TAM); Tlaxcala (MX-TLA); Veracruz (MX-VER); Yucatán (MX-YUC); Zacatecas (MX-ZAC). | Optional |
total_amount | Body. String | Total amount for the transaction. | Required |
transactions.payments.expiration_time | Body. String | Allows you to set the due date using the ISO 8601 duration format. While you can configure it to be between 1 and 30 days after the payment is issued, we recommend setting a duration of 3 days ("P3D" in the example) to avoid conflicts between the expiration date and the payment crediting, which can take up to 2 business hours from its completion. In case the payment is made after the established expiration date, the amount will be refunded to the payer's Mercado Pago account. | Optional |
payer.email | Body. String | Buyer’s e-mail. | Required |
transaction.payments.payment_method.id | Body. String | Identifier of the payment method. In this case, the value should be clabe. | Required |
transaction.payments.payment_method.type | Body. String | Type of the payment method. In the case of payments with a slip, the value should be bank_transfer. | Required |
The response will return the parameter ticket_url, which contains the URL with instructions for the buyer to make the payment. You should redirect them to it following the instructions in the Make the payment available step. Additionally, it will show the status action_required with status_detail=waiting_transfer until the payment is completed.
json{ "id": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "marketplace": "NONE", "total_amount": "50.00", "country_code": "MEX", "user_id": "1245621468", "status": "action_required", "status_detail": "waiting_payment", "capture_mode": "automatic", "created_date": "2024-09-02T22:04:01.880469Z", "last_updated_date": "2024-09-02T22:04:04.429289Z", "integration_data": { "application_id": "4599991948843755" }, "transactions": { "payments": [ { "id": "PAY01J6TC8BYRR0T4ZKY0QRTZ0E24", "amount": "50.00", "reference_id": "22dvqmsbq8c", "status": "action_required", "status_detail": "waiting_payment", "payment_method": { "id": "clabe", "type": "bank_transfer", "ticket_url": "https://www.mercadopago.com.mx/sandbox/payments/00000000000/ticket?caller_id=77777777777&hash=34cb0d7c-81d9-478c-92a5-767d0kakjja", "reference": "1234567890" } } ] } }
Among the returned parameters, the ones indicated in the table below stand out.
| Parameter | Type | Description |
transactions.payments.status | String | Returns the status of the transaction. In this case, it will return action_required to indicate that an action is required to complete the processing, that is, until the payment is made. |
transactions.payments.status_detail | String | In cases of bank transfer, as is the case with SPEI Transfers, the status_detail obtained is pending (waiting_payment) for the user to complete the payment process at their bank. |
transactions.payments.payment_method.ticket_url | String | URL to the page with payment instructions via SPEI Transfer. See more information in Make the payment available. |
transactions.payments.payment_method.reference | String | CLABE reference number for the buyer to make the bank transfer. |
expiration_time | String | Expiration period (in ISO 8601 format) returned for an order created in manual mode (processing_mode=manual), counted from created_date. When omitted from the request, the returned default will be P1D (one day). This parameter will not be returned for an order created in automatic mode (processing_mode=automatic). |
After the payment is created, and for the client to be able to make the transfer, it is necessary to redirect them to the URL returned in the response to the order creation under the parameter ticket_url.
json{ [...] "transactions": { "payments": [ { [...] "payment_method": { "id": "clabe", "type": "bank_transfer", "ticket_url": "https://www.mercadopago.com.mx/payments/113775986440/ticket?caller_id=1872745950&hash=9545e05b-a530-4c82-9441-a666d0c73f70", "reference": "646010349353743569" } } ] } }
To do this, you have two options:
- You can automatically redirect the user.
- You can provide that URL to the user through a clickable button, following the example below.
html<a href="https://www.mercadopago.com.mx/payments/51096146182/ticket?caller_id=34728475&hash=f3a8630a-f06a-48e4-b2a6-f95750af7346" target="_blank">Pagar com Transferências SPEI</a>
If you wish, you can cancel a payment created, as long as it is pending or in process; that is, with status=action_required.
Additionally, we recommend canceling payments that were not made by the established due date to avoid billing and reconciliation issues.
For more information, please consult the Refunds and cancellations section.