Cash In

Cash In permite que tus clientes paguen en efectivo en un punto de una red de recaudo física (por ejemplo, Payvalida). Kushki genera un código PIN que el cliente presenta en el punto de recaudo. Una vez pagado, recibes una notificación por webhook y puedes confirmar el estado con el endpoint Transaction Status.

¡Ten en cuenta!

La generación del token requiere tu Private Key (Private-Merchant-Id). Nunca la expongas en código de cliente o frontend: llama siempre al endpoint del token desde tu backend.

Cómo funciona

Solicita un token de Cash In

Llama a POST /cash/v1/tokens con los datos personales del cliente y el monto total. Kushki devuelve un token de un solo uso que expira en 30 minutos.

{
  "name": "Carlos",
  "lastName": "Ramirez",
  "identification": "12345678",
  "documentType": "DNI",
  "email": "user@example.com",
  "totalAmount": 500,
  "currency": "PEN",
  "description": "Order #1234"
}

Respuesta:

{
  "token": "b209ff69ae02be9bc0e58dee225fd8f5"
}

Inicializa la transacción

Llama a POST /cash/v1/charges/init con el token y el desglose del monto. Kushki devuelve un PIN que el cliente usa para pagar en el punto de recaudo, además de la URL del comprobante.

{
  "token": "b209ff69ae02be9bc0e58dee225fd8f5",
  "amount": {
    "currency": "PEN",
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "iva": 0,
    "ice": 0
  },
  "expirationDate": "2026-06-10 00:00:00",
  "fullResponse": "v2"
}

Respuesta:

{
  "pin": "7929926379",
  "ticketNumber": "193222411482",
  "transactionReference": "fa3cb92f-f53f-46e8-a9f9-0c40e9ae2df2",
  "pdfUrl": "https://api.kushkipagos.com/cash/v1/charges/193222411482/receipt"
}

Comparte el pin y el pdfUrl (comprobante) con tu cliente. El PIN es válido hasta expirationDate (7 días por defecto; máximo 15 días en Perú).

El cliente paga en el punto de recaudo

El cliente visita un punto de la red de recaudo participante y paga con el PIN. No necesitas hacer nada de tu lado: Kushki te notifica por webhook cuando el pago se confirma.

Verifica el estado de la transacción

Llama a GET /cash/v1/status/{ticketNumber} para confirmar el estado final de la transacción.

{
  "ticketNumber": "2347529752172881",
  "status": "approvedTransaction",
  "totalAmount": 500,
  "currency": "PEN",
  "merchantName": "Mi Comercio Perú",
  "name": "Carlos",
  "lastName": "Ramirez",
  "documentType": "DNI",
  "identification": "12345678",
  "pin": "7929926379"
}

Campos de la solicitud del token

Campo	Requerido	Descripción
`name`	Sí	Nombre del cliente.
`lastName`	Sí	Apellido del cliente.
`identification`	Sí	Número de documento del cliente.
`documentType`	Sí	`DNI`, `CE`, `PAS` o `RUC`.
`totalAmount`	Sí	Monto total a recaudar.
`currency`	Sí	`PEN` o `USD`.
`email`	No	Correo electrónico del cliente.
`description`	No	Descripción del pago.

Campos de la solicitud de Init Transaction

Campo	Requerido	Descripción
`token`	Sí	Token de un solo uso devuelto por el endpoint del token.
`amount`	Sí	Objeto de monto: consulta Desglose del monto.
`expirationDate`	No	Fecha de expiración del PIN en `YYYY-MM-DD HH:mm:ss` (UTC). Debe ser al menos un día después de la creación. Por defecto: 7 días; máximo 15 días en Perú.
`webhooks`	No	Arreglo de URLs a notificar cuando el cliente pague.
`fullResponse`	No	Envía `"v2"` para obtener el detalle completo de la transacción en la respuesta.
`metadata`	No	Pares clave-valor personalizados para tu propio seguimiento.

Desglose del monto

{
  "currency": "PEN",
  "subtotalIva": 0,
  "subtotalIva0": 500,
  "iva": 0,
  "ice": 0
}

Campo	Requerido	Descripción
`currency`	Sí	`PEN` o `USD`.
`subtotalIva`	Sí	Subtotal afecto a IGV. Envía `0` si no aplican impuestos.
`subtotalIva0`	Sí	Subtotal no afecto a IGV (monto exonerado).
`iva`	Sí	Monto de IGV. Envía `0` si no aplican impuestos.
`ice`	Sí	ICE (Impuesto a Consumos Especiales). Envía `0` si no aplica.

Tipos de documento

Valor	Descripción
`DNI`	Documento Nacional de Identidad 🇵🇪
`CE`	Carné de Extranjería 🇵🇪
`PAS`	Pasaporte 🇵🇪
`RUC`	Registro Único de Contribuyentes 🇵🇪

Webhooks

Incluye un arreglo webhooks en tu solicitud de init para recibir una notificación cuando el cliente complete el pago:

{
  "webhooks": ["https://yoursite.com/kushki/notify"]
}

Pruebas en Sandbox

Usa los siguientes valores de identification para simular distintos resultados de transacción:

`identification`	Resultado simulado
Cualquier valor válido	Transacción exitosa
`9999999999`	Inicializada (pago pendiente)
`1000000000`	Transacción declinada

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de Cash In

Genera un token de un solo uso con los datos del cliente y el monto total. El token expira en 30 minutos.

Iniciar transacción

Inicia la transacción en efectivo. Devuelve el PIN para que el cliente pague en el punto de recaudo y la URL del comprobante en PDF.

Consultar el estado de la transacción

Consulta el estado actual de una transacción en efectivo por número de ticket.

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Cómo funciona#

Campos de la solicitud del token#

Campos de la solicitud de Init Transaction#

Desglose del monto#

Tipos de documento#

Webhooks#

Pruebas en Sandbox#

Autenticación#

Uso de la API#

Endpoints disponibles#

Cómo funciona

Campos de la solicitud del token

Campos de la solicitud de Init Transaction

Desglose del monto

Tipos de documento

Webhooks

Pruebas en Sandbox

Autenticación

Uso de la API

Endpoints disponibles