PayCash
With Mercado Pago's Checkout API, you can also offer payments with PayCash.
With this payment method, the buyer receives a voucher with a reference code and pays in cash at one of the authorized stores of the PayCash network, within the voucher's expiration period. The purchase is considered complete only after the payment is confirmed.
If you have already set up your environment and want to offer payments with PayCash, follow the steps below. Currently, it is not possible to test PayCash payments in Peru.
processing_mode parameter. For more information, visit the section Integration Model.To receive payments with PayCash, you need to add a form to the frontend that securely captures the payer's data.
If you already have a development that includes your own payment form, make sure to include PayCash among the available options, as shown below, and continue to the Submit payment step.
| Payment method | payment_method.id |
| PayCash | paycash |
html<form id="form-checkout" action="/process_payment" method="post"> <div> <label for="form-checkout__payerFirstName">First name</label> <input id="form-checkout__payerFirstName" name="payerFirstName" type="text"> </div> <div> <label for="form-checkout__payerLastName">Last name</label> <input id="form-checkout__payerLastName" name="payerLastName" type="text"> </div> <div> <label for="form-checkout__email">E-mail</label> <input id="form-checkout__email" name="email" type="email"> </div> <div> <input type="hidden" name="transactionAmount" id="transactionAmount" value="200"> <button type="submit">Pay</button> </div> </form>
The payment is submitted by creating an order that contains the associated payment transaction.
To do so, send a request with your Access TokenPrivate key used in the backend to authenticate requests to Mercado Pago APIs. It must never be shared or exposed in the frontend. and the parameters listed below to the endpoint /v1/ordersPOST and execute the request.
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": "200.00", "payer": { "email": "test_payer@example.com", "first_name": "Juan", "last_name": "Pérez" }, "transactions": { "payments": [ { "amount": "200.00", "expiration_time": "P1D", "payment_method": { "id": "paycash", "type": "ticket" } } ] } }'
429 Too Many Requests error, wait for the time indicated in the Retry-After header of the response before trying again. See Possible errors for more details.| Parameter | Type | Description | Requirement |
Authorization | Header | Refers to your private key, the Access TokenPrivate key used in the backend to authenticate requests to Mercado Pago APIs. It must never be shared or exposed in the frontend.. | Required |
X-Idempotency-Key | Header | Idempotency key. Ensures that each request is processed only once. Use a unique value in the request header, such as a UUID V4 or a random string. | Required |
processing_mode | Body. String | Order processing mode: automatic to create and process automatically, or manual to process in a separate step. For more information, see Integration model. | Required |
expiration_time | Body. String | Only in manual mode (processing_mode=manual): validity period of the order, in ISO 8601 duration format, counted from created_date. The maximum limit is 2920 hours and, if not sent, the default value is P1D (one day). When the period expires before the order reaches a final status, the order is automatically closed and the associated pending payments are canceled. Do not send this parameter when creating an order in automatic mode (processing_mode=automatic). | Optional |
total_amount | Body. String | Total amount of the transaction. | Required |
payer.email | Body. String | Buyer's e-mail. | Required |
payer.first_name | Body. String | Buyer's first name. | Optional |
payer.last_name | Body. String | Buyer's last name. | Optional |
transactions.payments.payment_method.id | Body. String | Payment method identifier. In this case, the value must be paycash. | Required |
transactions.payments.payment_method.type | Body. String | Payment method type. In this case, the value must be ticket. | Required |
transactions.payments.expiration_time | Body. String | Expiration period of the PayCash voucher, in ISO 8601 duration format (for example, P1D for one day). If you do not send this field, the payment processor's default period applies. In automatic mode, the processor validates the period provided. In manual mode, the API returns a 400 error if the period exceeds 2920 hours or is not in a valid ISO 8601 format. Also, set the order's expiration_time equal to or greater than the voucher's to prevent the order from expiring and canceling the payment while the voucher is still valid. | Optional |
Once processing is complete, and since this is an offline payment method, the order moves to the action_required status with the waiting_payment detail, indicating that the buyer still needs to pay at an authorized store, as shown in the following response example.
We recommend setting up notifications for the Order topic to receive updates on the status change, including the updated order data. Another option is to send a request to the endpoint /v1/orders/{id}GET to check the updated status.
json{ "id": "ORDPE01EXAMPLEPE1234NCAKKBF68N64S", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "200.00", "total_paid_amount": "0.00", "country_code": "PER", "user_id": "1245621468", "status": "action_required", "status_detail": "waiting_payment", "capture_mode": "automatic_async", "currency": "PEN", "created_date": "2026-10-15T18:02:11.104Z", "last_updated_date": "2026-10-15T18:02:12.873Z", "integration_data": { "application_id": "1234567890123456" }, "transactions": { "payments": [ { "id": "PAYPE01EXAMPLEPE1234BSAR5ZWXX5YZG", "amount": "200.00", "expiration_time": "P1D", "date_of_expiration": "2026-10-16T18:02:11.104+00:00", "reference_id": "1ioxvbg0wls", "status": "action_required", "status_detail": "waiting_payment", "payment_method": { "id": "paycash", "type": "ticket", "ticket_url": "https://www.mercadopago.com.pe/payments/5551234567/ticket?caller_id=1245621468&hash=00000000-0000-0000-0000-000000000000", "barcode_content": "3335008800000000006004835002100020000242462010", "reference": "6005407530", "verification_code": "9876543210" } } ] } }
| Parameter | Type | Description |
transactions.payments.status | String | Transaction status. In this case, it returns action_required to indicate that an action is needed 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 indicates that it is waiting (waiting_payment) for the buyer to complete the payment. |
transactions.payments.date_of_expiration | String | Voucher expiration date, calculated from the expiration_time sent or from the processor's default period. |
transactions.payments.payment_method | Object | PayCash voucher data that you must present to the buyer. For more information, see the Display payment instructions to the buyer step. |
After creating the order, show the buyer the information needed to complete the payment at a store of the PayCash network. This data is available in the transactions.payments.payment_method object of the response.
| Field | Description |
ticket_url | URL with the complete payment instructions. Redirect the buyer to this link or display it. |
reference | Reference code that the buyer must present at the store to make the payment. |
barcode_content | Voucher barcode content that the store can scan as an alternative to the reference code. |
verification_code | Voucher verification code. |
The buyer must complete the payment before the date indicated in date_of_expiration. To check the stores available for PayCash payments in Peru, visit the official website.
Once the buyer makes the payment, the order moves to the processed status with the accredited detail. If you set up your notifications, you will receive a notification via webhook. If the expiration period ends without the payment being made, cancel the payment as described in the Cancel payment step.
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.
Once accredited, a PayCash payment can be fully or partially refunded through a request to the endpoint /v1/orders/{id}/refundPOST. After a partial refund, the order remains in the processed status with the partially_refunded detail. When the total amount is refunded, the order moves to the refunded status with the refunded detail.
For more information, see the Refunds and cancellations section.