PayCash
Com o Checkout API do Mercado Pago, também é possível oferecer pagamentos com PayCash.
Com esse meio de pagamento, o comprador recebe um comprovante com um código de referência e realiza o pagamento em dinheiro em um dos estabelecimentos autorizados da rede PayCash, dentro do prazo de vencimento do comprovante. A compra é considerada concluída somente após a confirmação do pagamento.
Se você já configurou seu ambiente e quer oferecer pagamentos com PayCash, siga os passos abaixo. No momento, não é possível testar pagamentos com PayCash no Peru.
processing_mode. Para mais informações, acesse a seção Modelo de integração.Para receber pagamentos com PayCash, é necessário adicionar ao frontend um formulário que capture os dados do pagador de forma segura.
Se você já tem um desenvolvimento que inclui um formulário de pagamento próprio, certifique-se de incluir PayCash entre as opções disponíveis, conforme indicado abaixo, e continue com o passo Enviar pagamento.
| Meio de pagamento | payment_method.id |
| PayCash | paycash |
html<form id="form-checkout" action="/process_payment" method="post"> <div> <label for="form-checkout__payerFirstName">Nome</label> <input id="form-checkout__payerFirstName" name="payerFirstName" type="text"> </div> <div> <label for="form-checkout__payerLastName">Sobrenome</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>
O envio do pagamento é feito por meio da criação de uma order que contenha a transação de pagamento associada.
Para isso, envie uma requisição com seu Access TokenChave privada utilizada no backend para autenticar as solicitações às APIs do Mercado Pago. Nunca deve ser compartilhada nem exposta no frontend. e os parâmetros indicados abaixo ao endpoint /v1/ordersPOST e execute a requisição.
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, aguarde o tempo indicado no header Retry-After da resposta antes de tentar novamente. Consulte Possíveis erros para mais detalhes.| Parâmetro | Tipo | Descrição | Obrigatoriedade |
Authorization | Header | Faz referência à sua chave privada, o Access TokenChave privada utilizada no backend para autenticar as solicitações às APIs do Mercado Pago. Nunca deve ser compartilhada nem exposta no frontend.. | Obrigatório |
X-Idempotency-Key | Header | Chave de idempotência. Garante que cada requisição seja processada apenas uma vez. Use um valor exclusivo no header da requisição, como um UUID V4 ou uma string aleatória. | Obrigatório |
processing_mode | Body. String | Modo de processamento da order: automatic para criar e processar automaticamente, ou manual para processar em uma etapa separada. Para mais informações, acesse Modelo de integração. | Obrigatório |
expiration_time | Body. String | Somente em modo manual (processing_mode=manual): prazo de validade da order, no formato de duração ISO 8601, contado a partir de created_date. O limite máximo é de 2920 horas e, se não for enviado, o valor padrão é P1D (um dia). Quando o prazo vence sem que a order tenha chegado a um status final, a order é encerrada automaticamente e os pagamentos pendentes associados são cancelados. Não envie este parâmetro ao criar uma order em modo automático (processing_mode=automatic). | Opcional |
total_amount | Body. String | Valor total da transação. | Obrigatório |
payer.email | Body. String | E-mail do comprador. | Obrigatório |
payer.first_name | Body. String | Nome do comprador. | Opcional |
payer.last_name | Body. String | Sobrenome do comprador. | Opcional |
transactions.payments.payment_method.id | Body. String | Identificador do meio de pagamento. Neste caso, o valor deve ser paycash. | Obrigatório |
transactions.payments.payment_method.type | Body. String | Tipo do meio de pagamento. Neste caso, o valor deve ser ticket. | Obrigatório |
transactions.payments.expiration_time | Body. String | Prazo de vencimento do comprovante PayCash, no formato de duração ISO 8601 (por exemplo, P1D para um dia). Se você não enviar este campo, será aplicado o prazo padrão do processador do pagamento. No modo automático, o processador valida o prazo informado. No modo manual, a API retorna um erro 400 se o prazo ultrapassar 2920 horas ou não estiver em formato ISO 8601 válido. Além disso, defina o expiration_time da order igual ou maior que o do comprovante para evitar que a order vença e cancele o pagamento enquanto o comprovante ainda estiver vigente. | Opcional |
Após a conclusão do processamento, e por se tratar de um meio de pagamento offline, a order passa para o status action_required com o detalhe waiting_payment, indicando que o comprador ainda deve realizar o pagamento em um estabelecimento autorizado, conforme o exemplo de resposta a seguir.
Recomendamos configurar as notificações do tópico Order para receber atualizações sobre a mudança de status, incluindo os dados atualizados da order. Outra opção é enviar uma requisição ao endpoint /v1/orders/{id}GET para consultar o status atualizado.
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 | Descrição |
transactions.payments.status | String | Status da transação. Neste caso, retorna action_required para indicar a necessidade de uma ação para concluir o processamento, ou seja, até que se realize o pagamento. |
transactions.payments.status_detail | String | Detalhe do status da transação. Neste caso, o valor obtido é aguardando (waiting_payment) que o comprador finalize o pagamento. |
transactions.payments.date_of_expiration | String | Data de vencimento do comprovante, calculada a partir do expiration_time enviado ou do prazo padrão do processador. |
transactions.payments.payment_method | Object | Dados do comprovante PayCash que você deve apresentar ao comprador. Para mais informações, consulte a etapa de Apresentar instruções de pagamento ao comprador. |
Após criar a order, mostre ao comprador as informações necessárias para concluir o pagamento em um estabelecimento da rede PayCash. Esses dados estão disponíveis no objeto transactions.payments.payment_method da resposta.
| Campo | Descrição |
ticket_url | URL com as instruções completas de pagamento. Redirecione o comprador para esse link ou exiba-o para ele. |
reference | Código de referência que o comprador deve apresentar no estabelecimento para realizar o pagamento. |
barcode_content | Conteúdo do código de barras do comprovante que o estabelecimento pode ler como alternativa ao código de referência. |
verification_code | Código de verificação do comprovante. |
O comprador deve concluir o pagamento antes da data indicada em date_of_expiration. Para verificar os estabelecimentos disponíveis para pagamentos com PayCash no Peru, acesse o site oficial.
Assim que o comprador realizar o pagamento, a order passa para o status processed com o detalhe accredited. Se você configurou suas notificações, receberá uma notificação via webhook. Se o prazo de vencimento terminar sem que o pagamento tenha sido realizado, cancele o pagamento conforme indicado no passo Cancelar pagamento.
Caso deseje, você pode cancelar um pagamento criado, desde que esteja pendente ou em processamento. Ou seja, com status=action_required.
Além disso, recomendamos cancelar os pagamentos que não foram realizados dentro da data de vencimento estabelecida, para evitar problemas de cobrança e conciliação.
Para obter mais informações, consulte a seção Reembolsos e cancelamentos.
Uma vez creditado, um pagamento com PayCash pode ser reembolsado de forma total ou parcial por meio de uma requisição ao endpoint /v1/orders/{id}/refundPOST. Após um reembolso parcial, a order permanece no status processed com o detalhe partially_refunded. Ao reembolsar o valor total, a order passa para o status refunded com o detalhe refunded.
Para mais informações, consulte a seção Reembolsos e cancelamentos.