Paycash
PayCash es una plataforma de pago en efectivo que permite a los compradores pagar cuentas y servicios en establecimientos físicos autorizados, como bancos, agentes y redes de cobranza. Con esta opción, el comprador genera un código de pago y puede pagarlo presencialmente en cualquier punto habilitado.
Con Checkout API de Mercado Pago, es posible ofrecer pagos con Paycash para que tus compradores finalicen compras online con pago en efectivo.
En esta documentación, encontrarás todas las etapas necesarias para realizar la integración con Paycash.
Obtener medios de pago disponibles
Para obtener una lista detallada con todos los medios de pago disponibles para integración, envía un GET con tu Access TokenClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Credenciales. al endpoint /v1/payment_methodsAPI y ejecuta la solicitud o, si lo prefieres, realiza la solicitud utilizando los SDKs a continuación.
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 la integración de Checkout API, es necesario capturar los datos requeridos para procesar el pago.
Esta captura se realiza a partir de la inclusión de la biblioteca MercadoPago.js en tu proyecto, seguida del formulario de pago. Utiliza el código a continuación para importar la biblioteca MercadoPago.js antes de agregar el formulario de pago.
npm install @mercadopago/sdk-js<body>
<script src="https://sdk.mercadopago.com/js/v2"></script>
</body>Configurar credenciales
Las credenciales son claves únicas con las cuales identificamos una integración en tu cuenta. Se utilizan para capturar pagos en tiendas virtuales y otras aplicaciones de forma segura.
Esta es la primera etapa de una estructura de código completa que debe seguirse para integrar correctamente los pagos. Presta atención a los bloques a continuación para agregarlos según lo indicado.
javascript
const mp = new MercadoPago("YOUR_PUBLIC_KEY");
Agregar formulario de pago
Con la biblioteca MercadoPago.js incluida, agrega el formulario de pago a continuación a tu proyecto para garantizar la captura segura de los datos de los compradores. En esta etapa es importante utilizar la lista que consultaste para obtener los medios de pago disponibles para crear las opciones de pago que deseas ofrecer.
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">Apellido</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="Nombre del Producto"> <br> <button type="submit">Pagar</button> </div> </div> </form>
Obtener tipos de documento
Después de configurar la credencial y agregar el formulario de pago, es necesario obtener los tipos de documento que se utilizarán para completar el formulario de pago.
Al incluir el elemento select con el id: form-checkout__identificationType que está en el formulario, será posible completar automáticamente las opciones disponibles al llamar la siguiente función:
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 pago
Al finalizar la inclusión del formulario de pago y obtener los tipos de documento, es necesario enviar el e-mail del comprador, tipo y número de documento, el medio de pago utilizado y el detalle del valor a pagar utilizando nuestra API de Pagos o uno de nuestros SDKs.
Para configurar pagos con Paycash, envía un POST con los parámetros requeridos al endpoint /v1/paymentsAPI y ejecuta la solicitud o, si lo prefieres, utiliza uno de nuestros SDKs indicados a continuación.
X-Idempotency-Key con tu clave de idempotencia para garantizar la ejecución y reejecución de solicitudes evitando situaciones indeseadas, como pagos duplicados, por ejemplo.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 del producto",
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 del producto",
"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 del producto",
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 del producto",
"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 del producto',
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]El detalle de cada uno de los parámetros enviados en el cuerpo de la solicitud, así como sus respectivos valores posibles, se describe en la tabla a continuación.
| Campo | Tipo | Descripción | Obligatoriedad | Ejemplo |
transaction_amount | number | Valor de la transacción a ser procesada. | Obligatorio | 100 |
description | string | Breve descripción del producto o servicio. | Opcional | "Titulo del producto" |
payment_method_id | string | Campo crucial para iniciar el flujo de pago; debe ser llenado obligatoriamente con el valor "paycash". | Obligatorio | "paycash" |
date_of_expiration | string | Fecha de vencimiento del ticket de pago. Si este campo no es enviado, se establecerá una fecha de vencimiento predeterminada de 2 días después de la creación del ticket. Solo se consideran días completos tanto para la fecha de vencimiento proporcionada como para la fecha predeterminada. Los fines de semana no se contabilizan. Por lo tanto, si el integrador envía una fecha con minutos, la fecha de vencimiento se ajustará al final del día enviado. Ejemplo: si el integrador envía "2026-02-03T20:00:00.000-05:00" (3 de febrero de 2026 a las 20:00, UTC-5), la fecha de vencimiento será el 3 de febrero de 2026, a las 23:59. | Opcional | "2026-02-03T20:00:00.000-05:00" |
payer | object | Contiene información detallada sobre el pagador, como la dirección de correo electrónico. | Obligatorio | { "email": "test_user_mx@testuser.com" } |
La respuesta mostrará el status pending hasta que el comprador realice el pago. Además, en la respuesta a la solicitud, el parámetro external_resource_url devolverá una URL que contiene las instrucciones para que el comprador efectúe el pago. Puedes redirigirlo a este mismo enlace para finalizar el flujo de pago.
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 pago
Solo es posible cancelar los pagos que están pendientes o en proceso. Cuando el cancelamiento es realizado por el vendedor, el status_detail pasa a ser by_collector.
La cancelación también ocurre de forma automática cuando la fecha actual supera el valor definido en el campo date_of_expiration informado durante la creación del pago. En ese caso, el status_detail será expired.
Para más información, consulta Reembolsos y cancelaciones.
Establecimientos de pago
Al finalizar la integración, es importante compartir con los compradores la información de los diferentes lugares en los que pueden realizar el pago. Para verificar los establecimientos disponibles para pagos con PayCash, visita el sitio web oficial.