PagoDirecto — Guía de Integración

Bienvenido a PagoDirecto. Esta guía te explica todo lo necesario para integrar cobros (Payins) y desembolsos (Payouts) en tu plataforma. Cada sección incluye el flujo completo, los campos requeridos y ejemplos listos para usar.

— Autenticación

Incluye tu API key en el header de cada solicitud.

HTTP HEADER

Authorization: Bearer {TU_API_KEY}
Content-Type:  application/json

🔐

Tu API key te la proporciona el equipo de PagoDirecto durante el proceso de onboarding. La misma key también autentica los callbacks que PD envía a tu servidor.

API Payins — Cobros

01 Qué es

Recibe pagos de tus usuarios a través de bancos peruanos y billeteras digitales.

La API Payins genera vouchers de pago que tus usuarios usan para depositar fondos. Soporta dos modalidades según el canal elegido:

Modalidad	Canal (deposit_channel)	Cómo paga el usuario	Ideal para
CIP Bancario	`bcp` `bbva` `ibk` `yape` `yapeof`	Ingresa el código CIP en su app bancaria, agente o ATM	E-commerce, recargas, depósitos remotos
QR	`qr`	Escanea un QR dinámico con su app bancaria	Punto de venta presencial, kiosco, pantalla

Casos de uso:

Recarga de saldo o fondeo de cuentas.
Checkout sin tarjeta de crédito o débito.
Cobros presenciales mediante código QR.
Pagos con billeteras digitales y otros canales habilitados.

02 Flujo

El ciclo de vida es idéntico para CIP y QR — solo cambia cómo el usuario paga.

PASO 1 · Tu Backend → PagoDirecto

🏪

Crear voucher de pago

Llamas al endpoint con los datos del usuario, el monto y el canal. Para CIP elige el banco; para QR usa deposit_channel: "qr".

POST / payment_reference_code payment_amount deposit_channel

PASO 2 · PagoDirecto → Tu Frontend

🔑

PD retorna el voucher

PD responde con un payment_id y un payment_token. Usa el token para mostrar el iframe de pago al usuario — funciona igual para CIP y QR.

payment_id payment_token ● CREATED (1)

PASO 3 · Usuario paga

💳

CIP bancario o escaneo de QR

CIP: el usuario ingresa el código en su app bancaria, agente o ATM.
QR: el usuario escanea el código QR con su app bancaria al instante.

App bancaria Agente / ATM Yape / Plin QR

PASO 4 · PagoDirecto → Tu Backend

📡

Notificación de pago confirmado

PD confirma el pago con el banco y envía un POST a tu callback_url con el estado final. Mismo formato para CIP y QR.

● CONFIRMED (4)

PASO 5 · Opcional

🔍

Consultar estado en cualquier momento

Puedes consultar el estado de un voucher en cualquier momento sin esperar el callback.

GET /{payment_id}

03 Crear Voucher — POST /

Un único endpoint para CIP y QR. El campo deposit_channel determina la modalidad.

📤 Endpoint REQUEST

POST https://api.payins.pagodirecto.pe/

Campo	Tipo	Requerido	Descripción
payment_reference_code	string	SÍ	Tu identificador único para este pago.
payment_amount	string	SÍ	Monto en dígitos. Los últimos 2 son centavos: `"10050"` = PEN 100.50
payment_currency	string	SÍ	`PEN` o `USD`
client_email	string	SÍ	Email del usuario. PD envía aquí la confirmación de pago.
payment_concept	string	NO	Descripción del pago.
payment_expire_date	timestamp	NO	Expiración en Unix timestamp. Si se omite, PD aplica un TTL por defecto.
client_name	string	NO	Nombre del usuario.
client_id_type	string	NO	`DNI` o `CE`
client_id_number	string	NO	Número de documento.
client_city	string	NO	Ciudad del usuario.
client_province	string	NO	Provincia o región.
client_country_code	string	NO	Código de país ISO. Ej: `PE`
client_phone_mobile	string	NO	Celular del usuario.
deposit_channel	string	NO	Canal de pago. Ver tabla abajo. Si se omite, el iframe muestra todos los canales.
callback_url	string	NO	URL donde PD enviará las notificaciones de estado.
metadata	object	NO	Datos adicionales clave-valor. PD los reenvía en los callbacks sin modificarlos.

Canales disponibles

deposit_channel	Tipo	Canal	Descripción
`bcp`	CIP	BCP	App, agente o ventanilla BCP.
`bbva`	CIP	BBVA	App o agente BBVA.
`ibk`	CIP	Interbank	App o agente Interbank.
`yape`	CIP	Yape	Billetera Yape.
`yapeof`	CIP	Yape On File	Débito automático desde Yape.
`qr`	QR	QR	QR dinámico. Pago inmediato. Ideal para punto de venta y kiosco.

Ejemplo — CIP (Yape)

POST /

{
  "payment_reference_code": "ORDER-001",
  "payment_currency":       "PEN",
  "payment_amount":         "10050",   // PEN 100.50
  "client_email":          "usuario@correo.com",
  "deposit_channel":       "yape",
  "callback_url":          "https://tuapp.com/webhooks/payins"
}

Ejemplo — QR

POST / · QR

{
  "payment_reference_code": "CAJA-001",
  "payment_currency":       "PEN",
  "payment_amount":         "15075",   // PEN 150.75
  "client_email":          "usuario@correo.com",
  "deposit_channel":       "qr",   // ← activa QR dinámico
  "callback_url":          "https://tuapp.com/webhooks/payins"
}

Response · 201 Created

{
  "object":        "payins",
  "payment_id":    4005197,
  "payment_token": "72c925c3-e002-f111-b905-000d3a42271a"
}

💡

Mismo token para CIP y QR. El payment_token funciona igual en ambas modalidades. El iframe detecta el canal y muestra automáticamente el código CIP o el QR.

Response · 400 — Validación

{
  "status":     400,
  "error_type": "parameter_error",
  "params": [
    { "param": "payment_currency", "user_message": "value is empty" }
  ]
}

04 Consultar Estado — GET /{payment_id}

Obtén el estado y datos completos de un voucher en cualquier momento.

📥 Endpoint REQUEST

GET https://api.payins.pagodirecto.pe/{payment_id}

Response · 200 OK

{
  "object":                "payins",
  "payment_status":        4,                      // ← campo clave
  "payment_paid_date":     "2024-11-23T14:30:00Z", // null si pendiente
  "payment_reference_code": "ORDER-001",
  "payment_currency":       "PEN",
  "payment_amount":         "10050",
  "payment_concept":        "Pago por Orden #001",
  "client_name":            "Carlos Gómez",
  "client_email":           "usuario@correo.com",
  "metadata":              { "order_id": "001" }
}

05 Mostrar Voucher al Usuario

Dos formas de presentar las instrucciones de pago: iframe embebido o página HTML directa.

Método	URL	Ideal para
iFrame RECOMENDADO	`https://iframe.payins.pagodirecto.pe/payins/{token}`	Checkout web, embebido en tu página
HTML directo	`GET https://api.payins.pagodirecto.pe/payins/{token}`	Apps móviles con WebView, pantallas dedicadas

ℹ️

Ambas opciones muestran el mismo contenido: instrucciones CIP con datos bancarios, o el QR escaneable según el canal seleccionado al crear el voucher.

06 Webhooks

PD envía un POST a tu callback_url cada vez que el estado del pago cambia. El formato es el mismo para CIP y QR.

🔐

Verificación: Cada callback incluye tu API key en el header Authorization. Verifica siempre que coincida antes de procesar el evento.

Webhook entrante

POST /webhooks/payins HTTP/1.1
Authorization: Bearer {TU_API_KEY}

{
  "payment_id":            4005197,
  "payment_status":        4,   // ✅ Pago confirmado
  "payment_reference_code": "ORDER-001",
  "payment_amount":        "10050",
  "payment_currency":      "PEN",
  "metadata":             { "order_id": "001" }
}

🔄

Reintentos automáticos: Si tu endpoint no responde o devuelve un error, PD reintenta la entrega. Tu handler debe ser idempotente y responder siempre con HTTP 200.

07 Estados

El campo payment_status aplica igual para CIP y QR.

Valor	Estado	Descripción	¿Final?
`1`	Created	Voucher generado. Esperando pago del usuario.	Intermedio
`3`	Paid	Pago recibido por el banco. PD está conciliando.	Intermedio
`4`	Confirmed	✅ Pago confirmado. Activa tu lógica de negocio.	✓ Final
`98`	Expired	El voucher venció sin recibir pago.	✓ Final
`99`	Canceled	Voucher cancelado.	✓ Final

🔴

Actúa solo cuando payment_status = 4. Los estados 98 y 99 son terminales — el usuario debe iniciar un pago nuevo.

08 Ejemplos Completos

Flujo A — CIP Bancario (Yape)

1 · Crear voucher

POST /

{ "payment_reference_code": "TXN-001", "payment_amount": "15000",
  "payment_currency": "PEN", "client_email": "usuario@correo.com",
  "deposit_channel": "yape", "callback_url": "https://tuapp.com/webhooks/payins" }

● 201 CREATED

2 · Mostrar iFrame al usuario

iFrame

https://iframe.payins.pagodirecto.pe/payins/{payment_token}

3 · Usuario paga con Yape

El usuario sigue las instrucciones del iframe y completa el pago desde su app Yape.

4 · Recibes el callback → acreditas al usuario

Webhook

{ "payment_status": 4 } // ✅ Confirmar y acreditar

Flujo B — QR (Punto de venta)

1 · Crear voucher QR

POST /

{ "payment_reference_code": "CAJA-001", "payment_amount": "15075",
  "payment_currency": "PEN", "client_email": "usuario@correo.com",
  "deposit_channel": "qr", "callback_url": "https://tuapp.com/webhooks/payins" }

● 201 CREATED

2 · Mostrar QR en pantalla de caja

iFrame

https://iframe.payins.pagodirecto.pe/payins/{payment_token}

3 · Cliente escanea el QR

El cliente escanea con su app bancaria (BCP, BBVA, Yape…). Pago confirmado en segundos.

4 · Recibes el callback → confirmas la venta

Webhook

{ "payment_status": 4 } // ✅ Venta confirmada

API Payouts — Desembolsos

01 Qué es

Envía dinero directamente a cuentas bancarias peruanas usando el CCI.

La API Payouts te permite desembolsar fondos a cualquier cuenta bancaria peruana usando el CCI (Código de Cuenta Interbancario) — el número interbancario estándar de 20 dígitos.

Casos de uso:

Pagos a vendedores de un marketplace.
Comisiones o pagos de afiliados.
Reembolsos a clientes.
Planillas o desembolsos masivos.

02 Flujo

PASO 1 · Tu Backend → PagoDirecto

📤

Enviar solicitud de desembolso

Envías los datos del destinatario (nombre, documento, CCI) y el monto.

POST /api/payouts account_cci payment_amount

PASO 2 · PagoDirecto valida y encola

⚙️

PD confirma la recepción

PD valida los datos y devuelve 201 Created. El payment_id viene en el header Location — sin body.

Location: /api/payouts/{id} ● QUEUED

PASO 3 · PagoDirecto procesa la transferencia

🏦

Transferencia bancaria

PD valida el CCI, verifica el destinatario y procesa la transferencia al banco destino.

● SENT (4)

PASO 4 · PagoDirecto → Tu Backend

📡

Notificación del resultado

PD te notifica cuando el payout llega a un estado final: éxito (Archive) o fallo (Void). Los estados intermedios no generan callback.

● ARCHIVE (5) = Éxito ● VOID (6) = Fallo

03 Crear Payout — POST /api/payouts

📤 Endpoint REQUEST

POST https://api.payouts.pagodirecto.pe/api/payouts

Campo	Tipo	Requerido	Descripción
payment_reference	string	SÍ	Tu identificador único para este payout.
customer_name	string	SÍ	Nombre completo del destinatario.
customer_id_type	string	SÍ	Tipo de documento: `DNI`, `CE` o `Pasaporte`
customer_id_number	string	SÍ	Número de documento.
account_cci	string (20 dígitos)	SÍ	CCI de la cuenta bancaria destino.
account_currency	string	SÍ	Moneda de la cuenta: `SOLES` o `USD`
payment_amount	string	SÍ	Monto con 2 decimales. Ej: `"150.00"`
payment_currency	string	SÍ	Moneda del pago: `PEN` o `USD`
customer_email	string	NO	Email del destinatario.
customer_reference	string	NO	Tu referencia interna del cliente.
callback_url	string	NO	URL donde PD enviará la notificación del resultado.

Request

{
  "payment_reference":  "PAYOUT-001",
  "customer_name":      "María 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/webhooks/payouts"
}

Response · 201 Created

Location: https://api.payouts.pagodirecto.pe/api/payouts/5574127
// Sin body. El payment_id es el número al final del path → 5574127

🚨

Importante: La respuesta exitosa no tiene body. Extrae el payment_id del header Location y guárdalo de inmediato.

Response · 400 — Validación

{
  "message": "Validation Failed",
  "errors": [
    { "field": "payment_amount",   "message": "Amount can not be empty" },
    { "field": "payment_currency", "message": "Currency can not be empty" }
  ]
}

04 Consultar Estado — GET /api/payouts/{payment_id}

Response · 200 OK

{
  "payment_id":           "5574127",
  "payment_reference":    "PAYOUT-001",
  "payment_amount":       "150.00",
  "payment_currency":     "PEN",
  "payment_status":       "5",    // ← estado operativo
  "payment_final_status": "1",    // ← estado contable
  "payment_notes":        "Transferencia completada exitosamente.",
  "customer_name":        "María Torres Flores",
  "account_cci":          "00219213866047808638"
}

05 Webhooks

PD notifica solo cuando el payout llega a un estado final. Los estados intermedios no generan callback.

Webhook · Éxito

{ "payment_status": "5", "payment_final_status": "1",
  "payment_notes": "Transferencia completada." }  // ✅

Webhook · Fallo

{ "payment_status": "6", "payment_final_status": "2",
  "payment_notes": "Bank account validation failed." }  // ❌

📋

Cuando el payout falla (payment_status = 6), revisa payment_notes — contiene la razón del fallo (cuenta inexistente, validación fallida, etc.).

06 Estados

Estado operativo — payment_status

Valor	Estado	Descripción	¿Final?
`1`	Pending	En revisión. No reenvíes — espera el callback.	Intermedio
`2`	Process	Encolado para procesamiento.	Intermedio
`4`	Sent	Enviado al banco, esperando confirmación.	Intermedio
`5`	Archive	✅ Transferencia completada.	✓ Final
`6`	Void	❌ Transferencia fallida. Ver `payment_notes`.	✓ Final

Estado contable — payment_final_status

Valor	Estado	Descripción
`3`	Not Set	Payout en proceso, aún no liquidado.
`1`	Captured	Fondos entregados correctamente.
`2`	Cancelled	Fondos no entregados.

07 Ejemplo Completo

Marketplace paga PEN 150.00 a la cuenta BCP de un vendedor.

1 · Crear payout

POST /api/payouts

{ "payment_reference": "PAYOUT-001",
  "customer_name": "María 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/webhooks/payouts" }

● 201 CREATEDpayment_id: 5574200

2 · PD procesa la transferencia

PD valida el CCI, verifica el destinatario y envía la transferencia al banco BCP.

● SENT (4)

3 · Recibes el callback → notificas al vendedor

Webhook

{ "payment_status": "5", "payment_final_status": "1" } // ✅

— Bancos Aceptados

Cuentas CCI de estos bancos pueden recibir desembolsos vía API Payouts.

002Banco de Crédito (BCP)

011BBVA Continental

003Interbank

009Scotiabank

049Mi Banco

038BANBIF

035Banco Pichincha

054Banco Falabella

055Banco Ripley

043CrediScotia

058Banco Azteca

018Banco de la Nación

023Banco de Comercio

056Santander Perú

800Caja Metropolitana Lima

801CMAC Piura

803Caja Arequipa

805CMAC Sullana

806CMAC Cuzco

808CMAC Huancayo

902Plin

PagoDirecto · Documentación pública v1 · 2026

Guía de Integración para Desarrolladores

📤 Endpoint REQUEST

Canales disponibles

Ejemplo — CIP (Yape)

Ejemplo — QR

📥 Endpoint REQUEST

Flujo A — CIP Bancario (Yape)

Flujo B — QR (Punto de venta)

📤 Endpoint REQUEST