Transfer Out

Transfer Out te permite enviar fondos desde tu wallet de Kushki a la cuenta bancaria de un destinatario. Úsalo para dispersiones, pagos a proveedores, reembolsos o cualquier flujo de payout en el que necesites sacar dinero.

¡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 la lista de bancos

Llama a GET /payouts/transfer/v1/bankList (o a v2 para metadata extendida) para obtener los bancos de destino disponibles. Usa el valor code como bankId en la solicitud de token.

Solicita un token de Transfer Out

Llama a POST /payouts/transfer/v1/tokens con los datos de la cuenta del destinatario y la información del pago. Devuelve un token de un solo uso.

{
  "bankId": "002",
  "accountType": "CC",
  "accountNumber": "1234567890123",
  "currency": "PEN",
  "totalAmount": 500.00,
  "documentType": "DNI",
  "documentNumber": "12345678",
  "name": "Carlos Ramirez",
  "mail": "user@example.com",
  "paymentDescription": "Supplier payment #789"
}

Inicia la dispersión

Llama a POST /payouts/transfer/v1/init con el token. La respuesta devuelve un ticketNumber y un transactionReference.

{
  "token": "V0OzRB100000xhxQB8035251pHLBQsq5",
  "fullResponse": "v2"
}

Respuesta:

{
  "status": "INITIALIZED",
  "ticketNumber": "1574298975417951",
  "transactionReference": "aef8884f-cd4d-4b9b-9efa-ad582629e4f2"
}

Consulta el estado de la transacción

Llama a GET /payouts/transfer/v1/transaction/{ticketNumber} para verificar que la dispersión se procesó.

Revisa el campo status:

Valor	Significado
`INITIALIZED`	Transferencia aceptada y en cola para procesarse
`APPROVAL`	Fondos enviados correctamente al destinatario
`DECLINED`	Transferencia rechazada
`VOIDED`	Transferencia anulada antes de procesarse

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 cuenta

Perú admite los siguientes tipos de cuenta bancaria para transferencias ACH:

Valor	Descripción
`CC`	Cuenta Corriente
`CA`	Cuenta Ahorros
`CM`	Cuenta maestra (solo Perú)

Formato del número de cuenta

Condición	Formato
BCP (`bankId: "002"`) con `CC`	Exactamente 13 dígitos
BCP (`bankId: "002"`) con `CA`	Exactamente 14 dígitos
Cualquier otro banco	CCI (Código de Cuenta Interbancaria): exactamente 20 dígitos, sin espacios, guiones ni caracteres especiales

Campos de la solicitud de token

Campo	Requerido	Descripción
`bankId`	Sí	Código del banco de destino, obtenido del endpoint de lista de bancos.
`accountType`	Sí	Tipo de cuenta bancaria: `CC`, `CA` o `CM`.
`accountNumber`	Sí	Número de cuenta bancaria del destinatario. Revisa las reglas de formato de arriba.
`currency`	Sí	`PEN` o `USD`.
`totalAmount`	Sí	Monto total a dispersar.
`documentType`	Sí	Tipo de documento del destinatario.
`documentNumber`	Sí	Número de documento del destinatario.
`name`	Sí	Nombre completo del destinatario. En Perú no se permiten caracteres especiales.
`mail`	No	Correo electrónico del destinatario.
`paymentDescription`	No	Descripción del pago, que se muestra en el estado de cuenta bancario.

Anular una transferencia

Para cancelar una transacción de Transfer Out antes de que se procese, llama a:

DELETE /payouts/transfer/v1/transaction/{ticketNumber}

Envía el ticketNumber que devuelve el endpoint de estado. Las anulaciones solo son posibles mientras la transacción está en estado INITIALIZED.

Consulta el saldo del wallet

Antes de iniciar una dispersión, verifica que tu wallet de Kushki tenga fondos suficientes:

GET /wallet/v1/merchant/balance

Respuesta:

{
  "balanceDate": 1687371952224,
  "currency": "PEN",
  "currentBalance": 717169.22
}

Webhooks

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

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

Lista de bancos: v1 vs v2

Endpoint	Descripción
`GET /payouts/transfer/v1/bankList`	Devuelve el `code` y el `name` del banco. Úsalo para transferencias ACH estándar.
`GET /payouts/transfer/v2/bankList`	Respuesta extendida con `internationalCodes` y metadata adicional.

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 de destino soportados con su code y name.

Obtener lista de bancos V2

Lista de bancos extendida con códigos internacionales y metadata adicional.

Solicitar un token de Transfer Out

Tokeniza la dispersión con los datos de la cuenta del destinatario. Devuelve un token de un solo uso.

Iniciar transacción

Inicia la dispersión por transferencia bancaria. Devuelve un ticket number para el seguimiento.

Consultar estado

Consulta el estado actual de una transacción de Transfer Out por ticket number.

Anular una transacción

Cancela una transacción de Transfer Out antes de que se procese.

Saldo de la wallet

Obtén el saldo disponible actual en tu wallet de payouts de Kushki.

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

Flujo de pago#

Monedas#

Tipos de documento#

Tipos de cuenta#

Formato del número de cuenta#

Campos de la solicitud de token#

Anular una transferencia#

Consulta el saldo del wallet#

Webhooks#

Lista de bancos: v1 vs v2#

Autenticación#

Uso de la API#

Endpoints disponibles#

Flujo de pago

Monedas

Tipos de documento

Tipos de cuenta

Formato del número de cuenta

Campos de la solicitud de token

Anular una transferencia

Consulta el saldo del wallet

Webhooks

Lista de bancos: v1 vs v2

Autenticación

Uso de la API

Endpoints disponibles