Transfer In

Transfer In cobra directamente desde la cuenta bancaria de un cliente, sin tarjeta. En Perú funciona con procesadores, el flujo tradicional por el portal del banco y Yape, a través de los mismos endpoints bajo /transfer/v1. Toda integración empieza preguntando qué procesadores tiene el comercio.

Endpoints

Endpoint	Método y ruta	Credencial	Propósito	Lo usa
Consultar la configuración de Transfer In	`GET /transfer/v1/config`	Pública	Empieza aquí. Lista los procesadores habilitados para el comercio y, cuando aplica, los `supportedFlows` de cada uno	Todos
Consultar lista de bancos	`GET /transfer/v1/bankList`	Pública	Bancos soportados (`code`, `name`)	Tradicional
Solicitar un token de Transfer In	`POST /transfer/v1/tokens`	Pública	Crea un token de un solo uso	Todos
Iniciar transacción	`POST /transfer/v1/init`	Privada	Inicia la transacción con el token	Todos
Consultar estado	`GET /transfer/v1/status/{token}`	Privada	Estado final de la transacción	Todos

Flujo de integración

Consulta los procesadores

Llama a Consultar la configuración de Transfer In con la credencial Public-Merchant-Id. processors[] lista los procesadores habilitados para el comercio. Es el punto de partida de toda integración directa por API.

Elige el procesador

Una entrada sin supportedFlows es el procesador tradicional. Una entrada con supportedFlows es un procesador con flujos de pago (Yape), y además eliges el flujo. Si el comercio tiene varios, usa los supportedFlows de cada entrada para decidir cómo armar cada token.

Solicita el token

El cuerpo depende del procesador; consulta Procesadores de un vistazo más abajo. Los tokens son de un solo uso.

Inicia la transacción

Envía el token y repite el mismo monto. La respuesta depende del procesador: redirectUrl (tradicional), o ticketNumber y consentId (Yape), además de deepLink con DEEPLINK.

Confirma el estado final

Por webhook o con Consultar estado.

Kajita y Kushki.js

Estas herramientas no soportan el objeto processor: con ellas no hay consulta de procesadores y la tokenización sigue el proceso tradicional. Yape requiere una integración directa por API, donde el token se solicita desde tu backend.

Procesadores de un vistazo

Los procesadores con flujos de pago, como Yape, también se conocen como APM (métodos alternativos de pago).

	Tradicional	Yape
Se identifica por	Entrada de `config` sin `supportedFlows`	Entrada de `config` con `supportedFlows`
Solicitud del token	`amount`, `currency` y `callbackUrl` requeridos; `bankId`, `userType`, `documentType`, `documentNumber`, `email` y `paymentDescription` opcionales. Sin objeto `processor`.	`amount`, `currency` y `processor: { name, flowType }`, copiados tal cual de `config`; además `phoneNumber` en `PUSH`.
Lista de bancos	Opcional: sin `bankId`, el cliente elige el banco en el portal del banco	No se usa
Respuesta de `init`	`redirectUrl`	`deepLink` (`DEEPLINK`) o la confirmación del push (`PUSH`), ambas con `ticketNumber` y `consentId`
Experiencia del cliente	Completa el pago en el portal en línea de su banco	Aprueba el pago en la app de Yape: redirección directa desde mobile (`DEEPLINK`), o notificación push desde web o desktop (`PUSH`)
Moneda	`PEN` o `USD`	`PEN`
Tipos de integración	API directa, Kajita, Kushki.js	Solo API directa
Disponibilidad	General	Beta, en comercios con el procesador habilitado

El token queda ligado al procesador con el que fue generado, y Iniciar transacción lo valida:

Token generado	Procesador del comercio	Resultado
Sin `processor`	Tradicional	Continúa; la respuesta incluye `redirectUrl`.
Con `processor` de Yape	Yape	Continúa; la respuesta incluye `ticketNumber` y `consentId` (y `deepLink` con `DEEPLINK`).
Con `processor`	Otro procesador	`422 E046`
Sin `processor`	Yape	`422 E046`

Detalle por procesador

Tradicional

Yape (Beta)

Campos de la solicitud del token

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

{
  "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"
}

La respuesta de init devuelve el redirectUrl al que debes enviar al cliente:

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

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 init

Campo	Requerido	Descripción
`token`	Sí	Token devuelto por el endpoint de token.
`amount`	Sí	Desglose del monto, incluida la `currency`. Debe coincidir con el monto usado al tokenizar.
`expirationDate`	No	Fecha y hora de expiración de la transacción. Solo Perú.
`webhooks`	No	Arreglo de URLs a notificar cuando cambie el estado de la transacción.
`fullResponse`	No	`"v2"` devuelve el detalle completo de la transacción.
`metadata`	No	Pares clave-valor personalizados para tu propio seguimiento.

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

Estados

Confirma el resultado final con Consultar estado (GET /transfer/v1/status/{token}). El webhook y los estados son los mismos para todos los procesadores.

Estado	Significado
`approvedTransaction`	El pago se completó correctamente.
`declinedTransaction`	El pago fue rechazado por el banco o por el procesador.
`initializedTransaction`	El pago sigue pendiente.
`expiredTransaction`	El token o la sesión expiraron sin pago.

Webhooks

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

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

Errores

Procesador	Endpoint	HTTP	Código	Cuándo ocurre	Qué hacer
Todos	`GET /transfer/v1/config`	`500`	`E002`	Error al consultar la configuración del comercio («Ha ocurrido un error inesperado.»).	Reintenta; contacta a soporte si persiste.
Yape	`POST /transfer/v1/tokens`	`400`	—	El cuerpo no cumple el contrato: falta un campo requerido (incluido `phoneNumber` con `PUSH`), valor fuera del enumerado (`processor.name`, `processor.flowType`) o propiedad adicional dentro de `processor`.	Corrige el cuerpo según `config`.
Todos	`POST /transfer/v1/init`	`422`	`E046`	El token no es compatible con el procesador resuelto.	Regenera el token para el procesador correcto.
Todos	Cualquiera	`401`	—	Credencial ausente o inválida.	Revisa `Public-Merchant-Id` o `Private-Merchant-Id`, según el endpoint.

Rechazos de Yape. Cuando Yape declina la transacción, retorna el código 006 con el mensaje «Transacción declinada». Es el único código de rechazo y se usa para todos los casos, por lo que no permite distinguir el motivo.

Autenticación y entornos

Las credenciales se envían en un header; cada endpoint usa una de ellas (consulta la columna Credencial de arriba):

Header	Credencial	Uso
`Public-Merchant-Id`	Pública	Configuración, lista de bancos y tokenización.
`Private-Merchant-Id`	Privada	Init, estado y cancelación. Nunca la expongas en código de frontend.

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints#

Flujo de integración#

Procesadores de un vistazo#

Detalle por procesador#

Monedas#

Tipos de documento#

Tipos de usuario#

Campos de la solicitud init#

Estados#

Webhooks#

Errores#

Autenticación y entornos#