Transfer In

Transfer In permite que tus clientes paguen por transferencia bancaria. El cliente se redirige al portal en línea de su banco, completa el pago ahí y regresa a tu callback URL al terminar.

¡Ten en cuenta!

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

Flujo de pago

Obtén los bancos disponibles

Llama a GET /transfer/v1/bankList para obtener la lista de bancos soportados con su code y su name. Muestra esta lista para que el cliente elija su banco.

Solicita un token de Transfer In

Llama a POST /transfer/v1/tokens con los datos del pago. Devuelve un token de un solo uso.

{
  "bankId": "1022",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 150.00,
    "iva": 0
  },
  "currency": "PEN",
  "callbackUrl": "https://yoursite.com/payment/return",
  "userType": "0",
  "documentType": "DNI",
  "documentNumber": "12345678",
  "email": "user@example.com",
  "paymentDescription": "Order #1234"
}

⚠️ callbackUrl es obligatorio en Perú. El cliente se redirige a esta URL después de completar (o abandonar) el pago.

Inicia la transacción

Llama a POST /transfer/v1/init con el token. La respuesta devuelve un redirectUrl: envía ahí al cliente para que complete la transferencia bancaria.

{
  "token": "V0OzRB100000xhxQB8035251pHLBQsq5",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 150.00,
    "iva": 0,
    "currency": "PEN"
  },
  "fullResponse": "v2"
}

Respuesta:

{
  "redirectUrl": "https://api.kushkipagos.com/transfer/v1/agent?token=...",
  "transactionReference": "28e6ac31-0af1-479a-9a6f-1a596bba6aea"
}

Consulta el estado de la transacción

Cuando el cliente regrese por el callbackUrl, llama a GET /transfer/v1/status/{token} para confirmar el estado final.

Revisa el campo status en la respuesta:

Valor	Significado
`approvedTransaction`	Pago completado correctamente
`declinedTransaction`	El banco rechazó el pago
`initializedTransaction`	El pago sigue pendiente
`expiredTransaction`	El token o la sesión expiraron sin pago

Monedas

Moneda	Código
Sol peruano	`PEN`
Dólar estadounidense	`USD`

Tipos de documento

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

Tipos de usuario

Valor	Descripción
`0`	Persona natural
`1`	Persona jurídica

Campos de la solicitud de token

Campo	Requerido	Descripción
`bankId`	No	Código del banco de destino. Si lo omites, el cliente elige el banco en el portal bancario.
`amount`	Sí	Desglose del monto del pago (`subtotalIva`, `subtotalIva0`, `iva`).
`currency`	Sí	`PEN` o `USD`.
`callbackUrl`	Sí	URL a la que se redirige al cliente después del pago. Obligatorio en Perú.
`documentType`	No	Tipo de documento del cliente.
`documentNumber`	No	Número de documento del cliente. Obligatorio si envías `documentType`.
`email`	No	Correo electrónico del cliente.
`userType`	No	`0` = persona natural, `1` = persona jurídica.
`paymentDescription`	No	Descripción de texto libre que se muestra al cliente en el portal bancario.

Campos de la solicitud init

Campo	Requerido	Descripción
`token`	Sí	Token que devuelve el endpoint de token.
`amount`	No	Desglose del monto, incluida la `currency`. Obligatorio si es distinto del monto del token.
`expirationDate`	No	Fecha y hora de expiración de la transacción. Solo para Perú.
`webhooks`	No	Array de URLs a notificar cuando cambia el estado de la transacción.
`fullResponse`	No	Envía `"v2"` para recibir el detalle completo de la transacción en la respuesta.
`metadata`	No	Pares clave-valor personalizados para tu propio seguimiento.

Webhooks

Incluye un array webhooks en tu solicitud init para recibir notificaciones de estado en tiempo real:

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

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Obtener lista de bancos

Devuelve la lista de bancos soportados con su code y name. Muéstrala al cliente antes de tokenizar.

Solicitar un token de Transfer In

Tokeniza la solicitud de transferencia. Devuelve un token de un solo uso para una única transacción.

Iniciar transacción

Inicia la transferencia bancaria. Devuelve una URL de redirección para enviar al cliente al portal de su banco.

Consultar estado

Consulta el estado final de una transacción de transferencia por token.

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Flujo de pago#

Monedas#

Tipos de documento#

Tipos de usuario#

Campos de la solicitud de token#

Campos de la solicitud init#

Webhooks#

Autenticación#

Uso de la API#

Endpoints disponibles#

Flujo de pago

Monedas

Tipos de documento

Tipos de usuario

Campos de la solicitud de token

Campos de la solicitud init

Webhooks

Autenticación

Uso de la API

Endpoints disponibles