Other payment methods
With Mercado Pago's Checkout API it is also possible to offer payments with OXXO, Paycash, Banamex and BBVA Bancomer.
With these payment methods, buyers will be able to make a deferred cash payment, always within the established deadline for its due date, and they will need to wait for it to be credited to consider the purchase completed.
If you wish to continue with your integration after setting up your environment and want to offer payments with OXXO, Paycash, Banamex e BBVA Bancomer, 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 these payment methods 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 of the payment methods to be offered.
| Payment method | payment_method_id |
| BBVA Bancomer | bancomer |
| Banamex | banamex |
| OXXO | oxxo |
| Paycash | paycash |
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.
processing_mode=manual) can have an expiration period defined in the expiration_time field. If the field is not sent, the default period is P1D (one day). When the period expires before the order reaches a final status, it is automatically closed, the associated pending payments are canceled, and the integrator is notified.curlcurl --location --request POST '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-raw '{ "type": "online", "external_reference": "ext_ref_1234", "processing_mode": "automatic", "total_amount": "50.00", "payer": { "email": "test_payer@example.com", "first_name": "John", "last_name": "Doe", "identification": { "type": "CURP", "number": "99999999999" } }, "config": { "location": { "state_id": "MX-DIF" } }, "transactions": { "payments": [ { "amount": "50.00", "expiration_time": "P3D", "payment_method": { "id": "oxxo", "type": "ticket" } } ] } }'
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. By default, the due date of the boleto is 3 business 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. The options for these payment methods are: bancomer: for payments with BBVA Bancomer. banamex: for payments with Banamex. oxxo: for payments with OXXO. paycash: for payments with Paycash. | Required |
transaction.payments.payment_method.type | Body. String | Type of the payment method. For payments with BBVA Bancomer and Banamex, the value must be atm. For payments with OXXO and Paycash, the value must be ticket. | Required |
The creation of the payment occurs asynchronously in the order. While it is being processed, the order is returned with a processing status and without information.
Once processing is complete, and since this is an offline payment method, the order transitions to action_required with the detail waiting_payment, indicating that the buyer still needs to complete the payment, as shown in the following response example. We recommend setting up Order topic notifications to receive updates on the status change, including the updated order data. Alternatively, you can choose to send a request to the /v1/orders/{id}GET endpoint to retrieve the updated status.
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": "oxxo", "type": "ticket", "ticket_url": "https://www.mercadopago.com.mx/sandbox/payments/00000000000/ticket?caller_id=77777777777&hash=34cb0d7c-81d9-478c-92a5-767d0kakjja", "barcode_content": "3335008800000000006004835002100020000242462010", "reference": "1234567890", "verification_code": "1234567890" } } ] } }
Among the returned parameters, the ones indicated in the table below stand out.
| Parameter | Type | Description |
transactions.payments.status | String | Returns the transaction status. 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 | Transaction status detail. In this case, the value obtained is pending (waiting_payment) for the buyer to complete the payment. |
transactions.payments.payment_method.ticket_url | String | URL with payment instructions to which you should redirect the buyer. |
transactions.payments.payment_method.barcode_content | String | Barcode in EAN-13 format for payment of the payment slip. |
transactions.payments.payment_method.reference | String | Payment reference code. |
transactions.payments.payment_method.verification_code | String | Payment verification code. |
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). |
It is important to share with buyers the information about the different places where they can make the payment. Please refer to the following table to learn the details of each location, and include them when providing the payment coupon.
| Payment method | Available locations |
| OXXO | OXXO |
| PayCash | 7-Eleven Circle K Soriana Extra Calimax Santander |
| BBVA Bancomer | BBVA Bancomer Farmacias del Ahorro Casa Ley |
| Banamex | Banamex Chedraui Telecomm |
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.