Integración centralizada de pagos
PagoDirecto centraliza operaciones de pago mediante una API REST. Comprende dos servicios: Payins para ingresos y Payouts para transferencias.
¿Cómo funciona PagoDirecto?
Visión de alto nivel del flujo transaccional: así se mueve el dinero desde que el usuario final inicia el pago hasta que tu sistema confirma la operación.
Este mismo patrón aplica a los 6 métodos de la plataforma (3 de cobro, 3 de desembolso). Solo cambia quién paga a quién y qué canal usa el dinero para moverse.
Guía rápida de integración
Cuatro componentes son suficientes para completar una primera transacción de prueba, sin recorrer toda la referencia técnica:
Mostrar voucher
Incrusta el payment_token en un iframe para que el cliente pague.
Cada solicitud se autentica con un Bearer token en el header Authorization. PagoDirecto te entrega tus llaves durante el onboarding.
Las pruebas y ejemplos de esta guía utilizan el ambiente de Staging. Los dominios y credenciales de Producción serán proporcionados una vez finalizado el proceso de Certificación.
Authorization: Bearer <tu-api-key> Content-Type: application/json
# Certificación (pruebas) Payins: https://stg-payins-api.pagodirecto.pe Payouts CCI: https://payouts-api-functionapp-stg.azurewebsites.net/api/payouts Payouts Wallet: https://stg-payouts-api-wallet.azurewebsites.net/api/payouts
Los ejemplos de esta guía usan URLs de nuestro ambiente de staging. Recibirás los dominios definitivos de producción junto con tus credenciales una vez finalizado el proceso de certificación.
Métodos de pago disponibles
Payins genera un voucher de pago que el usuario final completa desde su banco o billetera.
El mismo endpoint soporta tres métodos de integración; el valor de deposit_channel determina el canal utilizado.
El cliente recibe un código de pago y lo abona desde su app bancaria, agente o cajero. Confirmación en minutos.
Se muestra un QR en tu checkout o app que el cliente escanea con la app de su banco o billetera. Confirmación casi instantánea, 100% online.
Débito automático desde Yape. Si el cliente no está afiliado, PagoDirecto gestiona la suscripción y luego cobra - todo con una sola llamada.
Los bancos y billeteras mostrados en el CIP corresponden a las plantillas internas que manejamos. Cada opción permite generar las instrucciones o frame específico para el banco o billetera seleccionado. Esta lista no representa una limitación de los canales de pago disponibles.
Genera un voucher de pago. Devuelve un payment_id y un payment_token que usarás para mostrarle las instrucciones al cliente.
También existen client_city, client_province y client_country_code como campos opcionales para enriquecer el registro.
El voucher expira automáticamente en 7 días una vez creado.
curl -X POST https://stg-payins-api.pagodirecto.pe \ -H "Authorization: Bearer <tu-api-key>" \ -H "Content-Type: application/json" \ -d '{ "payment_reference_code": "REF-2026-000123", "payment_amount": "2500", "payment_currency": "PEN", "payment_concept": "Orden #123", "client_name": "Juan Perez", "client_email": "juan@example.com", "deposit_channel": "qr", "callback_url": "https://tutienda.com/payins/callback", "metadata": { "order_id": "123" } }'
const res = await fetch("https://stg-payins-api.pagodirecto.pe", { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ payment_reference_code: "REF-2026-000123", payment_amount: "2500", payment_currency: "PEN", client_email: "juan@example.com", deposit_channel: "qr", callback_url: "https://tutienda.com/payins/callback" }) }); const data = await res.json();
import requests res = requests.post( "https://stg-payins-api.pagodirecto.pe", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "payment_reference_code": "REF-2026-000123", "payment_amount": "2500", "payment_currency": "PEN", "client_email": "juan@example.com", "deposit_channel": "qr", "callback_url": "https://tutienda.com/payins/callback" } ) data = res.json()
Location: https://stg-payins-api.pagodirecto.pe/102030 { "object": "payins", "payment_id": 102030, "payment_token": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }
Guarda el payment_id (para consultar) y el payment_token (para mostrar el voucher).
{
"object": "error",
"error_type": "parameter_error",
"error_code": "400",
"params": [
{ "param": "client_email",
"user_message": "No es una dirección email válida" }
]
}
Existen dos variantes de URL según cómo quieras presentar el voucher. Ambas usan el payment_token devuelto al crear el pago.
Renderiza el QR o las instrucciones de pago dentro de un frame propio de PagoDirecto. Ideal para incrustar en un iframe dentro de tu checkout o abrir en un WebView móvil.
Devuelve el contenido del voucher sin el frame de PagoDirecto. Útil para integrar el diseño dentro de tu propio flujo de UI sin contenedor visual externo.
| Variante | URL | Ideal para |
|---|---|---|
| Con frame | /payins/{token} | iframe · WebView · pestaña nueva |
| Sin frame | /payins/{token}/info | Integración en UI propia |
Al crear el pago, PagoDirecto también envía automáticamente un email con las instrucciones al client_email. Mostrar el voucher es un refuerzo recomendado.
# Voucher con frame GET https://stg-payins-iframe.pagodirecto.pe/payins/{payment_token}
# Voucher sin frame GET https://stg-payins-iframe.pagodirecto.pe/payins/{payment_token}/info
El contenido detecta el canal (qr, CIP…) y renderiza automáticamente el QR o el código de pago correspondiente.
CIP Bancario
CIP permite realizar pagos mediante un código numérico que el usuario ingresa en los canales habilitados por su entidad financiera, como banca móvil, agentes o cajeros.
POST https://stg-payins-api.pagodirecto.pe con deposit_channel: "bcp" (o el banco elegido).callback_url.Usa el mismo endpoint de Payins, cambiando deposit_channel. Ejemplo completo y código listo para copiar en la Referencia técnica ↓.
{ "deposit_channel": "bcp", // también: bbva, ibk...
"payment_amount": "2500", "payment_currency": "PEN" }
Voucher con el código CIP, el banco elegido y el monto. El cliente lo copia en su app bancaria o lo lleva a un agente.
Mismo formato que todos los métodos de Payins — ver ejemplo completo ↓.
Resultado esperado: al recibir payment_status = 3, acredita al cliente y marca el pedido como pagado. Si recibes 98 (expirado), invita a generar un nuevo voucher.
QR Interoperable
El QR Interoperable elimina la necesidad de capturar datos de tarjeta o cuenta bancaria. Un único código es compatible con múltiples aplicaciones (Yape, Plin, banca móvil), lo que reduce la fricción de integración del lado del checkout.
POST https://stg-payins-api.pagodirecto.pe con deposit_channel: "qr".Ejemplo completo (cURL, Node.js, Python) en la Referencia técnica ↓.
{ "deposit_channel": "qr",
"payment_amount": "2500", "payment_currency": "PEN" }
QR dinámico embebido en tu checkout vía iframe. El cliente lo escanea desde cualquier app compatible.
Mismo formato que todos los métodos de Payins — ver ejemplo completo ↓.
Resultado esperado: al recibir payment_status = 3, confirma la orden de inmediato — la experiencia esperada es que el cliente vea éxito en segundos.
Yape On File
Yape On File permite ejecutar débitos automáticos sobre una cuenta Yape previamente autorizada por el usuario. La afiliación se gestiona una única vez; los cobros posteriores no requieren intervención del cliente.
- Facilitar el pago reduciendo la cantidad de interacciones que hace el usuario.
- Quieres reducir el churn por pagos manuales olvidados.
- Tus clientes ya usan Yape habitualmente.
Minutos (usuarios nuevos)
Izquierda: pantalla de afiliación (solo la primera vez). Derecha: pantalla de éxito, idéntica en cada cobro posterior.
yapeofPOST con deposit_channel: "yapeof". No necesitas lógica condicional de tu lado.payment_status: 3 = pagado · 98 = expirado . 99 = Anulado. Actúa solo con estados finales.↓
Cobro automático
↓
Webhook
directo
↓
Webhook
Los estados intermedios no generan callback. Actúa solo al recibir 3 (pagado), 98 o 99.
Ejemplo completo (cURL, Node.js, Python) en la Referencia técnica ↓.
{ "deposit_channel": "yapeof",
"payment_amount": "2500",
"payment_currency": "PEN",
"client_phone_mobile": "51999999999",
"client_email": "juan@example.com" }
Respuesta al suscribirse
El primer pago con Yape-on-file dispara el flujo de suscripción, se recibirá en el Response en el campo flow el valor SUBSCRIPTION.
{ "object": "payins",
"payment_id": "00000000",
"payment_token": "a0a0a0a0-b1b1-c2c2-d3d3-ab66802c560b",
"flow": "SUBSCRIPTION",
"yape_link": "https://www.yape.com.pe/app/checkout/ocp/subscription?subscriptionRequestId=000000&origin=deeplink-externo&origin_detail=mobile",
"yape_detail": "Successful operation." }
Respuesta al estar suscrito
Una vez suscrito a Yape-on-file se recibirá en el Response en el campo flow el valor DEPOSIT.
{ "object": "payins",
"payment_id": "00000000",
"payment_token": "a0a0a0a0-b1b1-c2c2-d3d3-ab66802c560b",
"flow": "DEPOSIT",
"yape_link": null,
"yape_detail": "Successful operation." }
Los Deeplinks (yape_link) se reciben en el Response solamente cuando se envía como parámetro payment_source con valor mobile.
La recibes al instante cuando llamas al endpoint.
↓
Flujo iniciado
Llega después, de forma asíncrona, cuando el cobro concluye.
↓
Pago confirmado ✅
Cuando se realiza el primer pago con un cliente se recibirán 2 callbacks:
Aprobación de suscripción
{ "subscriptionId": 102808,
"chargeType": "ON_DEMAND",
"customerId": "juan@example.com",
"status": "AUTHORIZED",
"statusDescription": "Subscription confirmed",
"errorDetails": null }
Confirmación de pago
{ "object": "payins",
"payment_id": "00000000",
"payment_token": "a0a0a0a0-b1b1-c2c2-d3d3-ab66802c560b",
"payment_status": "3",
"payment_paid_date": "1788967242",
"payment_reference_code": "TestYape",
"payment_concept": "Test Yape OnFile",
"payment_currency": "PEN",
"payment_amount": "10000",
"payment_expire_date": "1789157825",
"client_name": "Cliente de Prueba",
"client_email": "juan@example.com",
"client_id_type": "DNI",
"client_id_number": "12345678",
"client_city": "Lima",
"client_province": "Lima",
"client_country_code": "PE",
"client_phone_mobile": "999999999",
"metadata": {} }
Una vez suscrito los callbacks con este canal mantienen el mismo formato que todos los métodos de Payins (Response 2 en esta sección) — ver ejemplo completo ↓. Además del endpoint compartido en la Referencia técnica ↓, usa deposit_channel: "yapeof".
Resultado esperado: guarda al cliente como “afiliado” en tu sistema tras el primer éxito. Los siguientes cobros serán automáticos — solo espera el webhook cada vez que factures.
Elimina la suscripción del cliente en Yape. Se debe especificar el celular y correo electrónico del cliente.
curl -X POST https://stg-payins-api.pagodirecto.pe/subscriptions/cancel \ -H "Authorization: Bearer <tu-api-key>" \ -H "Content-Type: application/json" \ -d '{ "client_phone_mobile": "999999999", "client_email": "juan@example.com" }'
const res = await fetch("https://stg-payins-api.pagodirecto.pe/subscriptions/cancel", { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ client_phone_mobile: "999999999", client_email: "juan@example.com" }) }); const data = await res.json();
import requests res = requests.post( "https://stg-payins-api.pagodirecto.pe/subscriptions/cancel", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "client_phone_mobile": "999999999", "client_email": "juan@example.com" } ) data = res.json()
{
"success": true,
"operation_detail": "Successful operation."
}
Consulta el estado y los datos completos de un voucher en cualquier momento — útil si el callback no llegó. Requiere tu private key.
El campo clave es payment_status. Determina si el voucher está pendiente, pagado, confirmado, expirado o anulado.
curl https://stg-payins-api.pagodirecto.pe/102030 \ -H "Authorization: Bearer <private-key>"
{
"object": "payins",
"payment_token": "c0984b7a-f79b-f111-93b2-8f4adacb067d",
"payment_status": 1,
"payment_creation_date_ts": 1787162264.6340404,
"payment_paid_date": null,
"payment_reference_code": "pruebas122",
"payment_concept": "TEST-payins",
"payment_currency": "PEN",
"payment_amount": "162",
"payment_expire_date": 1787335063.80248,
"payment_callback": "https://prueb225.requestcatcher.com/test",
"payment_deposit_channel": "QR",
"client_name": "Prueba1",
"client_email": "juan@example.com",
"client_id_type": "1",
"client_id_number": "",
"client_city": "Lima",
"client_province": "Lima",
"client_country_code": "PEN",
"client_phone_mobile": "99999999",
"partner_id": 402,
"metadata": {}}
}
Cuando el cliente paga o el voucher expira, PagoDirecto envía un POST a tu callback_url con la misma estructura del GET. El header Authorization incluye tu llave para que verifiques el origen.
- Pago exitoso:
payment_status = 3(Paid) → acredita al cliente. - Voucher expirado:
payment_status = 98conpayment_paid_date: null→ invita a generar un nuevo voucher. - Voucher anulado:
payment_status = 99→ el voucher fue cancelado antes de recibir pago.
Reintentos: tu handler debe ser idempotente y responder HTTP 200. Si no respondes, PagoDirecto reintenta la entrega.
POST /payins/callback HTTP/1.1 Authorization: Bearer <private-key> Content-Type: application/json { "object": "payins", "payment_id": "13745571", "payment_token": "00d35cdc-109b-f111-93b2-8f4adacb067d", "payment_status": "3", "payment_paid_date": "1787063436.4010353", "payment_reference_code": "Prueba payins", "payment_concept": "TEST321", "payment_currency": "PEN", "payment_amount": "10000", "payment_expire_date": "1787236015.398", "client_name": "Prueba1", "client_email": "juan@example.com", "client_id_type": "70127294", "client_id_number": "70127294", "client_city": "Lima", "client_province": "Lima", "client_country_code": "PEN", "client_phone_mobile": "937535099", "metadata": {} }
Estados de Payins
El campo payment_status te dice en qué punto está el pago. Actúa solo en estados finales.
| Valor | Estado | Significado | Tipo |
|---|---|---|---|
| 1 | Created | Voucher generado, esperando el pago del cliente. | Intermedio |
| 3 | Paid | Voucher pagado y acreditado. | Final cliente |
| 4 | Confirmed | Estado interno luego de notificar al cliente (Callback interno exitoso). | Final PagoDirecto |
| 98 | Expired | El voucher venció sin recibir pago. | Final |
| 99 | Annulled | Voucher anulado antes de recibir pago. | Final |
Métodos de desembolso disponibles
Payouts ejecuta transferencias hacia una billetera, en segundos vía Open Banking, o a cualquier cuenta bancaria del Perú.
Envía el dinero directo a la billetera digital del destinatario. Sin necesidad de que tenga una cuenta bancaria tradicional.
Transferencia bancaria en segundos mediante integración Open Banking, sin pasar por los tiempos tradicionales de liquidación interbancaria.
Transferencia Host-to-Host directa a cualquier cuenta bancaria peruana usando el CCI. La cobertura más amplia del mercado.
Host-to-Host (H2H)
Transferencia directa a cualquier cuenta bancaria peruana usando el CCI. La cobertura más amplia del mercado.
H2H ejecuta transferencias a cuentas bancarias peruanas identificadas por CCI. El sistema recibe el request, valida los datos del destinatario y encola la transferencia hacia el banco correspondiente sin intervención manual.
- El destinatario no tiene o no usa billetera digital.
- Necesitas la máxima cobertura posible (bancos, financieras, cajas municipales).
- El desembolso puede tardar minutos — no es urgente al segundo.
POST con el CCI y el monto.callback_url.Ejemplo completo (cURL, Node.js, Python) en la Referencia técnica ↓.
Resultado esperado: al recibir payment_status = 5 (Archive), marca el pago como completado. Si recibes 6 (Void), revisa payment_notes.
Digital Wallets
Envía dinero directo a Yape o Plin. El destinatario lo recibe en su billetera en segundos, sin necesitar cuenta bancaria.
Wallets envía desembolsos directamente a una billetera Yape o Plin, identificando al destinatario por su número de celular afiliado. No requiere CCI ni cuenta bancaria.
- Solo cuentas con el celular afiliado del destinatario, no su CCI.
- El destinatario espera recibir el dinero casi al instante.
- El monto es en
PENúnicamente.
POST wallets con el celular y payment_wallet (1=Yape, 2=Plin).Contrato técnico completo en Referencia Wallets ↓.
Resultado esperado: al recibir payment_status = 5 (Archive) el destinatario ya tiene el dinero en su app. Si es 6 (Void) revisa payment_notes. Rejected (7) y Cancelled (8) no generan callback — consúltalos vía GET si necesitas el detalle.
Open Banking (Instant Payouts - BCP)
Transferencia bancaria en segundos mediante integración Open Banking, evitando los tiempos tradicionales de liquidación interbancaria.
Cuando se requiere mayor agilidad en una transferencia, Open Banking permite conectar directamente con las entidades financieras para procesar las operaciones de forma rápida, segura y automatizada.
Envía dinero a cualquier cuenta bancaria peruana usando el CCI (Código de Cuenta Interbancario). PagoDirecto valida los datos, encola la solicitud y la procesa vía integración directa con los bancos.
La respuesta exitosa (201) no tiene body. Extrae el payment_id del header Location y guárdalo de inmediato.
curl -X POST https://payouts-api-functionapp-stg.azurewebsites.net/api/payouts \ -H "Authorization: Bearer <tu-api-key>" \ -H "Content-Type: application/json" \ -d '{ "payment_reference": "PAYOUT-001", "customer_name": "Maria Torres Flores", "customer_id_type": "DNI", "customer_id_number": "12345678", "account_cci": "00219213866047808638", "account_currency": "SOLES", "payment_amount": "150.00", "payment_currency": "PEN", "callback_url": "https://tuapp.com/payouts/callback" }'
const res = await fetch("https://payouts-api-functionapp-stg.azurewebsites.net/api/payouts", { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ payment_reference: "PAYOUT-001", customer_name: "Maria Torres Flores", customer_id_type: "DNI", customer_id_number: "12345678", account_cci: "00219213866047808638", account_currency: "SOLES", payment_amount: "150.00", payment_currency: "PEN" }) });
import requests res = requests.post( "https://payouts-api-functionapp-stg.azurewebsites.net/api/payouts", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "payment_reference": "PAYOUT-001", "customer_name": "Maria Torres Flores", "customer_id_type": "DNI", "customer_id_number": "12345678", "account_cci": "00219213866047808638", "account_currency": "SOLES", "payment_amount": "150.00", "payment_currency": "PEN" } )
Location: https://payouts-api-functionapp-stg.azurewebsites.net/api/payouts/5574127 // El payment_id es el número final del path → 5574127
{
"code": 8,
"message": "Validation Failed",
"errors": [
{ "code": 1000, "field": "payment_amount",
"message": "Amount can not be empty" }
]
}
Obtiene el estado operativo del desembolso, junto con notas del procesamiento bancario (útil para diagnosticar rechazos).
Revisa payment_status para conocer el estado del desembolso. Cuando algo falla, payment_notes explica la razón.
{
"payment_id": "5574119",
"payment_reference": "PAYOUT-001",
"customer_name": "Maria Torres Flores",
"account_cci": "00219213866047808638",
"account_currency": "SOLES",
"payment_amount": "150.00",
"payment_currency": "PEN",
"payment_status": "5",
"payment_notes": "Transferencia completada."
}
// Éxito { "payment_status": "5" } // Fallo — revisa payment_notes { "payment_status": "6", "payment_notes": "Bank account validation failed." }
Solo los estados Archive (5) y Void (6) generan callback.
Endpoint dedicado para envíos instantáneos a Yape o Plin. A diferencia de H2H, identificas al destinatario por su número de celular, no por CCI.
A diferencia de H2H, la respuesta 201 sí incluye body completo con los datos del payout, además del header Location.
curl -X POST https://stg-payouts-api-wallet.azurewebsites.net/api/payouts \ -H "Authorization: Bearer <tu-api-key>" \ -H "Content-Type: application/json" \ -d '{ "payment_reference": "PO-WALLET-001", "customer_name": "Jose Andres Polanco Gonzales", "customer_id_type": "DNI", "customer_id_number": "42553791", "customer_phone_number": "51919468262", "payment_amount": "50.00", "payment_currency": "PEN", "payment_wallet": "1", "callback_url": "https://tuapp.com/payouts/callback" }'
Location: https://stg-payouts-api-wallet.azurewebsites.net/api/payouts/5433533 { "payment_id": 5566808, "payment_reference": "PO-WALLET-001", "customer_name": "Jose Andres Polanco Gonzales", "payment_amount": "50.00", "payment_currency": "PEN", "payment_date": "28/10/2025", "payment_time": "17:21:26", "payment_status": "2" // Process (encolado) }
{
"code": 400,
"errors": [
{ "code": 1000, "field": "customer_phone_number",
"message": "customer_phone_number cannot be empty." }
],
"message": "Validation Failed"
}
// Éxito — payment_status = 5 { "payment_status": "5" }
Solo Archive (5) y Void (6) generan callback, igual que en H2H.
Estados de un desembolso
El campo payment_status indica el estado operativo del payout. Los estados 7 y 8 son exclusivos de Wallets.
| Valor | Estado | Significado | Canal |
|---|---|---|---|
| 1 | Pending | Retenido para revisión manual del equipo PagoDirecto. | H2H · Wallet |
| 2 | Process | Encolado para procesamiento. | H2H · Wallet |
| 4 | Sent | Enviado al banco o billetera, esperando respuesta. | H2H · Wallet |
| 5 | Archive | Éxito: dinero enviado al destinatario. Genera callback. | H2H · Wallet |
| 6 | Void | Fallo confirmado. Ver payment_notes. Genera callback. | H2H · Wallet |
| 7 | Rejected | Rechazado por la billetera. Ver payment_notes. No genera callback. | Wallet |
| 8 | Cancelled | Cancelado antes de procesar. No genera callback. | Wallet |
ⓘ Solo Archive (5) y Void (6) generan callback. Rejected y Cancelled deben consultarse vía GET.
Bancos y cajas aceptados
Cuentas CCI de estas entidades pueden recibir desembolsos vía Payouts. Cada CCI empieza con el código del banco.
Y más de 40 entidades incluyendo financieras y cajas rurales. Lista completa disponible en el onboarding.
Errores comunes al integrar
Los problemas más frecuentes durante la integración, y cómo resolverlos rápido.
No autorizado
Tu Authorization falta o la llave es inválida.
Verifica que uses Bearer <key> y que la llave corresponda al ambiente (Sandbox vs. Producción).
Recurso no encontrado
El payment_id consultado no existe.
Confirma que guardaste el ID correcto desde la respuesta del POST (o el header Location en Payouts).
Datos inválidos
Uno o más campos no pasaron la validación.
Revisa el array params o errors de la respuesta — indica campo por campo qué falta corregir.
Timeout
La solicitud tardó demasiado en responder.
Reintenta con backoff exponencial. Si persiste, consulta el estado por GET antes de crear un pago duplicado.
El webhook no llega
Tu servidor no recibe el callback esperado.
Confirma que tu callback_url sea HTTPS público y que hayas autorizado las IPs de PagoDirecto ↓. Mientras tanto, consulta por GET.
IP bloqueada
Tus llamadas son rechazadas por el firewall.
Reporta tus IPs de producción y sandbox para whitelisting durante el onboarding.
Tu callback responde distinto de 200
PagoDirecto interpreta esto como entrega fallida.
Responde HTTP 200 apenas recibas el webhook (antes de procesarlo si es necesario) para evitar reintentos duplicados.
La API usa códigos HTTP estándar. Los errores 400 y 500 incluyen un objeto error con detalle por campo.
| HTTP | Significado |
|---|---|
| 200 | Operación exitosa (GET) |
| 201 | Recurso creado (POST) |
| 204 | Exitoso sin contenido (DELETE) |
| 400 | Parámetro faltante o inválido |
| 401 | Token inválido o ausente |
| 403 | Sin permisos para el recurso |
| 404 | Recurso no encontrado |
| 429 | Demasiadas solicitudes (rate limit) |
| 500 | Error interno del servidor |
| error_type | Cuándo |
|---|---|
| parameter_error | Uno o más campos con valores inválidos (revisa params). |
| invalid_request_error | El JSON no se pudo leer / procesar. |
| limit_api_error | Se excedió el límite de peticiones. |
| api_error | Error interno de la API. |
{
"object": "error",
"error_type": "parameter_error",
"error_code": "400",
"merchant_message": "Petición inválida, los valores en el JSON no son correctos",
"user_message": "El valor de uno o más campos no es correcto",
"params": [
{ "param": "client_email",
"user_message": "No es una dirección email válida" },
{ "param": "payment_amount",
"user_message": "No puede ser vacío" }
]
}
merchant_message es para tus logs; user_message puedes mostrarlo al cliente.
Para operar en producción, tu red y la de PagoDirecto deben reconocerse mutuamente. Coordina estos pasos con tu equipo de infraestructura.
- Reportas tus IPs (test y producción) para el whitelisting en el firewall de PagoDirecto.
- Autorizas las IPs de PagoDirecto que envían los callbacks hacia tu servidor.
- Reportas el/los dominios desde donde se mostrará el iFrame en tu web.
- Reportas tu
callback_urlpara habilitar las conexiones salientes de PagoDirecto.
Cada callback incluye tu llave en el header Authorization. Verifícala siempre antes de procesar el evento.
Autoriza estas IPs en tu firewall para recibir los webhooks. Las direcciones definitivas se confirman durante el onboarding.
Checklist antes de pasar a producción
Revisa cada punto antes de activar tus llaves productivas. Evita el 90% de los incidentes de integración.
- API Key de producción solicitada y activa
- Callback URL sirve sobre HTTPS válido
- Tu endpoint de callback responde siempre HTTP 200
- Verificas la llave/firma antes de procesar cada webhook
- Whitelist de IPs de PagoDirecto configurada en tu firewall
- Timeouts configurados en tus llamadas salientes a la API
- Reintentos con backoff implementados para errores 5xx/timeout
- Handler de webhooks es idempotente (soporta reintentos de PagoDirecto)
- Casos de prueba completados: éxito, error, expiración
- Monitoreo/alertas activos sobre tu endpoint de callback