Paycash
PayCash é uma plataforma de pagamento em dinheiro que permite aos compradores pagar contas e serviços em estabelecimentos físicos autorizados, como bancos, agentes e redes de cobrança. Com essa opção, o comprador gera um código de pagamento e pode pagá-lo presencialmente em qualquer ponto habilitado.
Com o Checkout Transparente do Mercado Pago, é possível oferecer pagamentos com Paycash, permitindo que seus compradores finalizem compras online com pagamento em dinheiro.
Nesta documentação, você encontra todas as etapas necessárias para realizar a integração com Paycash.
Obter meios de pagamento disponíveis
Para obter uma lista detalhada com todos os meios de pagamento disponíveis para integração, envie um GET com seu Access TokenChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Credenciais. ao endpoint /v1/payment_methodsAPI e execute a requisição ou, se preferir, faça a requisição utilizando os SDKs abaixo.
MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");
PaymentMethodClient client = new PaymentMethodClient();
client.list();curl -X GET \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/payment_methods' \MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");
PaymentMethodClient client = new PaymentMethodClient();
client.list();import { MercadoPagoConfig, PaymentMethods } from 'mercadopago';
const client = new MercadoPagoConfig({ accessToken: 'access_token' });
const paymentMethods = new PaymentMethods(client);
paymentMethods.get().then((result) => console.log(result))
.catch((error) => console.log(error));<?php
use MercadoPago\MercadoPagoConfig;
MercadoPagoConfig::setAccessToken("ENV_ACCESS_TOKEN");
$client = new PaymentMethodClient();
$payment_method = $client->get();
?>import mercadopago
sdk = mercadopago.SDK("ACCESS_TOKEN")
payment_methods_response = sdk.payment_methods().list_all()
payment_methods = payment_methods_response["response"]require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
payment_methods_response = sdk.payment_methods.get()
payment_methods = payment_methods_response[:response]Importar MercadoPago.js
Para realizar a integração do Checkout Transparente, é necessário capturar os dados necessários para processar o pagamento.
Esta captura é feita a partir da inclusão da biblioteca MercadoPago.js em seu projeto, seguida do formulário de pagamento. Utilize o código abaixo para importar a biblioteca MercadoPago.js antes de adicionar o formulário de pagamento.
npm install @mercadopago/sdk-js<body>
<script src="https://sdk.mercadopago.com/js/v2"></script>
</body>Configurar credenciais
As credenciais são chaves únicas com as quais identificamos uma integração na sua conta. São utilizadas para capturar pagamentos em lojas virtuais e outras aplicações de forma segura.
Esta é a primeira etapa de uma estrutura de código completa que deve ser seguida para integrar corretamente os pagamentos. Atente-se aos blocos abaixo para adicioná-los conforme indicado.
javascript
const mp = new MercadoPago("YOUR_PUBLIC_KEY");
Adicionar formulário de pagamento
Com a biblioteca MercadoPago.js incluída, adicione o formulário de pagamento abaixo ao seu projeto para garantir a captura segura dos dados dos compradores. Nesta etapa é importante utilizar a lista que você consultou para obter os meios de pagamento disponíveis para criar as opções de pagamento que deseja oferecer.
html
<form id="form-checkout" action="/process_payment" method="post"> <div> <div> <label for="payerFirstName">Nome</label> <input id="form-checkout__payerFirstName" name="payerFirstName" type="text"> </div> <div> <label for="payerLastName">Sobrenome</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 do 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>
Obter tipos de documento
Após configurar a credencial e adicionar o formulário de pagamento, é necessário obter os tipos de documento que serão utilizados para preencher o formulário de pagamento.
Ao incluir o elemento select com o id: form-checkout__identificationType que está no formulário, será possível preencher automaticamente as opções disponíveis ao chamar a seguinte função:
javascript
function createSelectOptions(elem, options, labelsAndKeys = { label : "name", value : "id"}){ const {label, value} = labelsAndKeys; elem.options.length = 0; const tempOptions = document.createDocumentFragment(); options.forEach( option => { const optValue = option[value]; const optLabel = option[label]; const opt = document.createElement('option'); opt.value = optValue; opt.textContent = optLabel; tempOptions.appendChild(opt); }); elem.appendChild(tempOptions); } // Get Identification Types (async function getIdentificationTypes () { try { const identificationTypes = await mp.getIdentificationTypes(); const docTypeElement = document.getElementById('form-checkout__identificationType'); createSelectOptions(docTypeElement, identificationTypes) }catch(e) { return console.error('Error getting identificationTypes: ', e); } })()
Enviar pagamento
Ao finalizar a inclusão do formulário de pagamento e obter os tipos de documento, é necessário encaminhar o e-mail do comprador, tipo e número de documento, o meio de pagamento utilizado e o detalhe do valor a ser pago utilizando nossa API de Pagamentos ou um de nossos SDKs.
Para configurar pagamentos com Paycash, envie um POST com os parâmetros requeridos ao endpoint /v1/paymentsAPI e execute a requisição ou, se preferir, utilize um de nossos SDKs indicados abaixo.
X-Idempotency-Key com sua chave de idempotência para garantir a execução e reexecução de requisições evitando situações indesejadas, como pagamentos duplicados, por exemplo.using MercadoPago.Config;
using MercadoPago.Client.Payment;
using MercadoPago.Resource.Payment;
MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";
var request = new PaymentCreateRequest
{
DateOfExpiration = DateTime.Parse("2026-02-03T20:00:00.000-05:00"),
TransactionAmount = 5000,
Description = "Título do produto",
PaymentMethodId = "paycash",
Payer = new PaymentPayerRequest
{
Email = "test_user_mx@testuser.com",
},
};
var client = new PaymentClient();
Payment payment = await client.CreateAsync(request);curl --location 'https://api.mercadopago.com/v1/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ENV_ACCESS_TOKEN' \
--header 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
--data-raw '{
"transaction_amount": 100,
"description": "Titulo do produto",
"date_of_expiration": "2026-02-03T20:00:00.000-05:00",
"payment_method_id": "paycash",
"payer": { "email": "test_user_mx@testuser.com" }
}'package main
import (
"context"
"fmt"
"time"
"github.com/mercadopago/sdk-go/pkg/config"
"github.com/mercadopago/sdk-go/pkg/payment"
)
func main() {
accessToken := "{{ACCESS_TOKEN}}"
idempotencyKey := "{{SOME_UNIQUE_VALUE}}"
cfg, err := config.New(accessToken)
if err != nil {
fmt.Println(err)
return
}
// Step 4: Initialize the API client
client := payment.NewClient(cfg)
// Step 5: Create the request array
expirationDate, _ := time.Parse(time.RFC3339, "2026-02-03T20:00:00.000-05:00")
request := payment.Request{
TransactionAmount: 5000,
Description: "Titulo do produto",
PaymentMethodID: "paycash",
Payer: &payment.PayerRequest{
Email: "<PAYER_EMAIL>",
},
DateOfExpiration: &expirationDate,
}
// Step 5: Make the request
resource, err := client.Create(context.Background(), request, idempotencyKey)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(resource)
}PaymentCreateRequest paymentCreateRequest = PaymentCreateRequest.builder()
.transactionAmount(new BigDecimal("<TRANSACTION_AMOUNT>"))
.paymentMethodId("<PAYMENT_METHOD_ID>")
.dateOfExpiration(OffsetDateTime.parse("2026-02-03T20:00:00.000-05:00"))
.payer(
PaymentPayerRequest.builder()
.email("<EMAIL>").build()
).build();
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("x-idempotency-key", "<SOME_UNIQUE_VALUE>");
MPRequestOptions requestOptions = MPRequestOptions.builder()
.customHeaders(customHeaders).build();
PaymentClient client = new PaymentClient();
client.create(paymentCreateRequest, requestOptions);import { MercadoPagoConfig, Payments } from 'mercadopago';
const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const payments = new Payments(client);
payments.create({
body: {
transaction_amount: '<TRANSACTION_AMOUNT>',
payment_method_id: '<PAYMENT_METHOD_ID>',
date_of_expiration: "2026-02-03T20:00:00.000-05:00",
payer: {
email: '<EMAIL>'
}
},
requestOptions: { idempotencyKey: '<SOME_UNIQUE_VALUE>' }
})
.then((result) => console.log(result))
.catch((error) => console.log(error));<?php
use MercadoPago\Client\Payment\PaymentClient;
$client = new PaymentClient();
$request_options = new RequestOptions();
$request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);
$payment = $client->create([
"transaction_amount" => (float) $_POST['<TRANSACTION_AMOUNT>'],
"payment_method_id" => $_POST['<PAYMENT_METHOD_ID>'],
"date_of_expiration" => "2026-02-03T20:00:00.000-05:00",
"payer" => [
"email" => $_POST['<EMAIL>']
]
], $request_options);
echo implode($payment);
?>import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")
payment_data = {
"transaction_amount": 100,
"description": "Título do produto",
"payment_method_id": "paycash",
"date_of_expiration": "2026-02-03T20:00:00.000-05:00",
"payer": {
"email": "test_user_mx@testuser.com"
}
}
payment_response = sdk.payment().create(payment_data)
payment = payment_response["response"]require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
payment_request = {
transaction_amount: 100,
description: 'Título do produto',
payment_method_id: 'paycash',
date_of_expiration: '2026-02-03T20:00:00.000-05:00',
payer: {
email: 'test_user_mx@testuser.com'
}
}
payment_response = sdk.payment.create(payment_request)
payment = payment_response[:response]O detalhamento de cada um dos parâmetros enviados no corpo da requisição, bem como seus respectivos valores possíveis, está descrito na tabela a seguir.
| Campo | Tipo | Descrição | Obrigatoriedade | Exemplo |
transaction_amount | number | Valor da transação a ser processada. | Obrigatório | 100 |
description | string | Breve descrição do produto ou serviço. | Opcional | "Título do produto" |
payment_method_id | string | Campo crucial para iniciar o fluxo de pagamento; deve ser preenchido obrigatoriamente com o valor "paycash". | Obrigatório | "paycash" |
date_of_expiration | string | Data de vencimento do ticket de pagamento. Se este campo não for enviado, será definida uma data de vencimento padrão de 2 dias após a criação do ticket. Somente dias completos são considerados tanto para a data de vencimento fornecida quanto para a data padrão. Fins de semana não são contabilizados. Portanto, se o integrador enviar uma data com minutos, a data de vencimento será ajustada para o final do dia enviado. Exemplo: se o integrador enviar "2026-02-03T20:00:00.000-05:00" (3 de fevereiro de 2026 às 20h, UTC-5), a data de vencimento será 3 de fevereiro de 2026, às 23h59. | Opcional | "2026-02-03T20:00:00.000-05:00" |
payer | object | Contém informações detalhadas sobre o pagador, como o endereço de e-mail. | Obrigatório | { "email": "test_user_mx@testuser.com" } |
A resposta mostrará o status pending até que o comprador realize o pagamento. Além disso, na resposta à requisição, o parâmetro external_resource_url retornará uma URL que contém as instruções para que o comprador efetue o pagamento. Você pode redirecioná-lo para este mesmo link para finalizar o fluxo de pagamento.
json
{ "id": 146232108035, "date_created": "2026-02-19T15:25:07.765-05:00", "date_approved": null, "date_last_updated": "2026-02-19T15:25:07.765-05:00", "date_of_expiration": "2026-02-21T00:59:59.000-05:00", "money_release_date": null, "money_release_status": "released", "operation_type": "regular_payment", "issuer_id": "12845", "payment_method_id": "paycash", "payment_type_id": "ticket", "payment_method": { "id": "paycash", "type": "ticket", "issuer_id": "12845", "data": {}, "forward_data": {} }, "status": "pending", "status_detail": "pending_waiting_payment", "currency_id": "PEN", "description": null, "live_mode": true, "sponsor_id": null, "authorization_code": null, "money_release_schema": null, "taxes_amount": 0, "counter_currency": null, "brand_id": null, "shipping_amount": 0, "build_version": "3.143.0-rc-4", "pos_id": null, "store_id": null, "integrator_id": null, "platform_id": null, "corporation_id": null, "charges_execution_info": { "internal_execution": { "date": "2026-02-19T15:25:07.752-05:00", "execution_id": "01KHVNSY80AK1CR7EFNTN1DFHM" } }, "payer": { "type": null, "id": "211339136", "operator_id": null, "email": null, "identification": { "number": null, "type": null }, "phone": { "number": null, "extension": null, "area_code": null }, "first_name": null, "last_name": null, "entity_type": null }, "collector_id": 164720860, "marketplace_owner": null, "metadata": {}, "additional_info": { "tracking_id": "platform:v1-whitelabel,so:ALL,type:N/A,security:none" }, "order": {}, "external_reference": null, "transaction_amount": 100, "transaction_amount_refunded": 0, "coupon_amount": 0, "differential_pricing_id": null, "financing_group": null, "deduction_schema": null, "barcode": { "content": "7041771529112930", "width": 1, "height": 30, "type": "Code128C" }, "installments": 1, "transaction_details": { "payment_method_reference_id": "7041771529112930", "acquirer_reference": null, "barcode": { "content": "7041771529112930", "width": 1, "height": 30, "type": "Code128C" }, "digitable_line": null, "verification_code": "10550843579", "net_received_amount": 0, "total_paid_amount": 100, "overpaid_amount": 0, "external_resource_url": "https://www.mercadopago.com.pe/payments/146232108035/ticket?caller_id=211339136&hash=c67143dd-b538-4a74-ba8b-829ae0a3caeb", "installment_amount": 0, "financial_institution": null, "payable_deferral_period": null }, "fee_details": [], "charges_details": [ { "id": "146232108035-001", "name": "mercadopago_fee", "type": "fee", "accounts": { "from": "collector", "to": "mp" }, "client_id": 0, "date_created": "2026-02-19T15:25:07.767-05:00", "last_updated": "2026-02-19T15:25:07.767-05:00", "amounts": { "original": 5.06, "refunded": 0 }, "metadata": { "source": "proc-svc-charges", "source_detail": "processing_fee_charge", "reason": "" }, "reserve_id": null, "refund_charges": [], "external_charge_id": "01KHVNSY8XPAMY1NVZFG1MF4S4", "update_charges": [] } ], "captured": true, "binary_mode": false, "call_for_authorize_id": null, "statement_descriptor": null, "card": {}, "notification_url": null, "refunds": [], "processing_mode": "aggregator", "merchant_account_id": null, "merchant_number": null, "point_of_interaction": { "type": "UNSPECIFIED", "business_info": { "unit": "online_payments", "sub_unit": "default", "branch": "Merchant Services" }, "transaction_data": {} }, "accounts_info": null, "release_info": null, "tags": null }
Cancelar pagamento
É possível cancelar apenas os pagamentos que estão pendentes ou em processo. Quando o cancelamento é realizado pelo vendedor, o status_detail passa a ser by_collector.
O cancelamento também ocorre de forma automática quando a data atual ultrapassa o valor definido no campo date_of_expiration informado durante a criação do pagamento. Nesse caso, o status_detail será expired.
Para mais informações, consulte Reembolsos e cancelamentos.
Estabelecimentos de pagamento
Ao finalizar a integração, é importante compartilhar com os compradores a informação dos diferentes lugares em que podem realizar o pagamento. Para verificar os estabelecimentos disponíveis para pagamentos com PayCash, visite o site oficial.