PayCash
Con Checkout API de Mercado Pago, también puedes ofrecer pagos con PayCash.
Con este medio de pago, el comprador recibe un comprobante con un código de referencia y realiza el pago en efectivo en uno de los establecimientos autorizados de la red PayCash, dentro del plazo de vencimiento del comprobante. La compra se considera completada solo tras la confirmación del pago.
Si ya configuraste tu entorno y quieres ofrecer pagos con PayCash, sigue los pasos a continuación. Por el momento, no es posible probar pagos con PayCash en Perú.
processing_mode. Para más información, accede a la sección Modelo de integración.Para recibir pagos con PayCash, es necesario agregar al frontend un formulario que capture los datos del pagador de forma segura.
Si ya tienes un desarrollo que incluye un formulario de pago propio, asegúrate de incluir PayCash entre las opciones disponibles, como se indica a continuación, y continúa con el paso Enviar pago.
| Medio de pago | payment_method.id |
| PayCash | paycash |
html<form id="form-checkout" action="/process_payment" method="post"> <div> <label for="form-checkout__payerFirstName">Nombre</label> <input id="form-checkout__payerFirstName" name="payerFirstName" type="text"> </div> <div> <label for="form-checkout__payerLastName">Apellido</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">Pagar</button> </div> </form>
El envío del pago se realiza creando una order que contenga la transacción de pago asociada.
Para eso, envía una solicitud con tu Access TokenClave privada utilizada en el backend para autenticar las solicitudes a las APIs de Mercado Pago. Nunca debe compartirse ni exponerse en el frontend. y los parámetros indicados a continuación al endpoint /v1/ordersPOST y ejecuta la solicitud.
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, espera el tiempo indicado en el header Retry-After de la respuesta antes de intentar nuevamente. Consulta Posibles errores para más detalles.| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Hace referencia a tu clave privada, el Access TokenClave privada utilizada en el backend para autenticar las solicitudes a las APIs de Mercado Pago. Nunca debe compartirse ni exponerse en el frontend.. | Obligatorio |
X-Idempotency-Key | Header | Clave de idempotencia. Garantiza que cada solicitud sea procesada solo una vez. Usa un valor exclusivo en el header de la solicitud, como un UUID V4 o una string aleatoria. | Obligatorio |
processing_mode | Body. String | Modo de procesamiento de la order: automatic para crear y procesar automáticamente, o manual para procesar en una etapa separada. Para más información, accede a Modelo de integración. | Obligatorio |
expiration_time | Body. String | Solo en modo manual (processing_mode=manual): plazo de validez de la order, en formato de duración ISO 8601, contado desde created_date. El límite máximo es de 2920 horas y, si no se envía, el valor predeterminado es P1D (un día). Cuando el plazo vence sin que la order haya alcanzado un estado final, la order se cierra automáticamente y se cancelan los pagos pendientes asociados. No envíes este parámetro al crear una order en modo automático (processing_mode=automatic). | Opcional |
total_amount | Body. String | Monto total de la transacción. | Obligatorio |
payer.email | Body. String | E-mail del comprador. | Obligatorio |
payer.first_name | Body. String | Nombre del comprador. | Opcional |
payer.last_name | Body. String | Apellido del comprador. | Opcional |
transactions.payments.payment_method.id | Body. String | Identificador del medio de pago. En este caso, el valor debe ser paycash. | Obligatorio |
transactions.payments.payment_method.type | Body. String | Tipo del medio de pago. En este caso, el valor debe ser ticket. | Obligatorio |
transactions.payments.expiration_time | Body. String | Plazo de vencimiento del comprobante de PayCash, en formato de duración ISO 8601 (por ejemplo, P1D para un día). Si no envías este campo, se aplicará el plazo predeterminado del procesador del pago. En el modo automático, el procesador valida el plazo informado. En el modo manual, la API devuelve un error 400 si el plazo supera las 2920 horas o no está en un formato ISO 8601 válido. Además, define el expiration_time de la order igual o mayor que el del comprobante para evitar que la order venza y cancele el pago mientras el comprobante aún esté vigente. | Opcional |
Una vez finalizado el procesamiento, y al tratarse de un medio de pago offline, la order pasa al estado action_required con el detalle waiting_payment, indicando que el comprador aún debe realizar el pago en un establecimiento autorizado, tal como se muestra en el siguiente ejemplo de respuesta.
Te recomendamos configurar las notificaciones del tópico Order para recibir actualizaciones sobre el cambio de estado, incluyendo los datos actualizados de la order. Otra opción es enviar una solicitud al endpoint /v1/orders/{id}GET para consultar el estado actualizado.
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" } } ] } }
| Parámetro | Tipo | Descripción |
transactions.payments.status | String | Estado de la transacción. En este caso, devuelve action_required para indicar la necesidad de una acción para completar el procesamiento, es decir, hasta que se realice el pago. |
transactions.payments.status_detail | String | Detalle del estado de la transacción. En este caso, el valor obtenido indica que se está a la espera (waiting_payment) de que el comprador finalice el pago. |
transactions.payments.date_of_expiration | String | Fecha de vencimiento del comprobante, calculada a partir del expiration_time enviado o del plazo predeterminado del procesador. |
transactions.payments.payment_method | Object | Datos del comprobante de PayCash que debes presentar al comprador. Para más información, consulta la etapa Presentar instrucciones de pago al comprador. |
Tras crear la order, muestra al comprador la información necesaria para completar el pago en un establecimiento de la red PayCash. Estos datos están disponibles en el objeto transactions.payments.payment_method de la respuesta.
| Campo | Descripción |
ticket_url | URL con las instrucciones completas de pago. Redirige al comprador a este enlace o muéstraselo. |
reference | Código de referencia que el comprador debe presentar en el establecimiento para realizar el pago. |
barcode_content | Contenido del código de barras del comprobante que el establecimiento puede leer como alternativa al código de referencia. |
verification_code | Código de verificación del comprobante. |
El comprador debe completar el pago antes de la fecha indicada en date_of_expiration. Para verificar los establecimientos disponibles para pagos con PayCash en Perú, visita el sitio web oficial.
Una vez que el comprador realice el pago, la order pasa al estado processed con el detalle accredited. Si configuraste tus notificaciones, recibirás una notificación vía webhook. Si el plazo de vencimiento termina sin que se haya realizado el pago, cancela el pago como se indica en el paso Cancelar pago.
Si lo deseas, puedes cancelar un pago creado, siempre y cuando se encuentre pendiente o en proceso; es decir, con status=action_required.
Adicionalmente, recomendamos cancelar los pagos que no fueron realizados dentro de la fecha de vencimiento establecida, para evitar problemas de facturación y conciliación.
Para obtener más información, consulta la sección Reembolsos y cancelaciones.
Una vez acreditado, un pago con PayCash puede ser reembolsado de forma total o parcial a través de una solicitud al endpoint /v1/orders/{id}/refundPOST. Tras un reembolso parcial, la order permanece en el estado processed con el detalle partially_refunded. Al reembolsar el monto total, la order pasa al estado refunded con el detalle refunded.
Para obtener más información, consulta la sección Reembolsos y cancelaciones.