Transfer out

Transfer Out te permite dispersar fondos de forma programática, enviando dinero directamente a la cuenta bancaria de un destinatario con el saldo de tu wallet de Kushki. En Colombia 🇨🇴 se soportan dos modos de transferencia: ACH (transferencias estándar a cuenta bancaria) y Bre-B (transferencias instantáneas por llave de pago).

¡Ten en cuenta!

Por nuestras políticas de riesgo, los métodos de pago disponibles y el tipo de integración pueden variar una vez completes la afiliación. Te indicaremos cómo proceder si este proceso aplica a tu comercio.

Modos de transferencia

ACH (cuenta bancaria)

Bre-B (llave de pago)

Transferencias bancarias estándar. Requiere el número de cuenta bancaria del destinatario (accountNumber), el tipo de cuenta (CC o CA) y el bankId. Usa el endpoint Get Bank List para obtener los bancos disponibles.

Flujo de pago

Un Transfer Out en Colombia consta de 4 pasos secuenciales: obtener la lista de bancos (solo ACH), tokenización, inicialización y confirmación del estado.

Obtén la lista de bancos

Obligatorio solo para las transferencias ACH. Llama al endpoint Get Bank List con tu Public Merchant ID para obtener la lista de bancos de destino disponibles.

Muéstrale la lista al operador y guarda el code que elija: lo enviarás como bankId en la solicitud del token.

En las transferencias Bre-B este paso no es necesario: no existe el campo bankId.

Hay dos versiones disponibles:

Endpoint	Notas
Get Bank List v1	Lista de bancos básica
Get Bank List v2	Lista de bancos ampliada: recomendada

Solicita un token de Transfer Out

Llama al endpoint del token con tu Public Merchant ID. Incluye los datos del destinatario, el monto y los campos del modo de transferencia.

Reglas del token: los tokens expiran en 30 minutos y son de un solo uso. Si la transacción falla o el token expira, solicita uno nuevo.

Campos obligatorios para Colombia:

Campo	ACH (CC/CA)	Bre-B (KI/KP/KE/KA/KM)
`accountType`	✅ Obligatorio	✅ Obligatorio
`accountNumber`	✅ Obligatorio	✅ Obligatorio
`totalAmount`	✅ Obligatorio	✅ Obligatorio
`currency`	✅ Obligatorio (`COP`)	✅ Obligatorio (`COP`)
`documentType`	✅ Obligatorio	Opcional
`documentNumber`	✅ Obligatorio	Opcional
`bankId`	✅ Obligatorio	No se requiere
`name`	✅ Obligatorio	Opcional

Tipos de cuenta para Colombia:

Valor	Modo	Descripción
`CC`	ACH	Cuenta Corriente
`CA`	ACH	Cuenta Ahorros
`KI`	Bre-B	Número de identificación nacional
`KP`	Bre-B	Número de celular
`KE`	Bre-B	Correo electrónico
`KA`	Bre-B	Alias alfanumérico
`KM`	Bre-B	Código de comercio

Tipos de documento aceptados en Colombia:

Valor	Documento
`CC`	Cédula de Ciudadanía 🇨🇴
`NIT`	Número de Identificación Tributaria 🇨🇴
`CE`	Cédula de Extranjería 🇨🇴
`TI`	Tarjeta de Identidad 🇨🇴
`PP`	Pasaporte 🇨🇴

Inicia la transacción

Con tu Private Merchant ID, llama al endpoint Init Transaction con el token del paso anterior. Kushki valida el token y devuelve un ticketNumber junto con el estado de la transacción.

Opcionalmente puedes incluir un objeto webhooks en esta solicitud para recibir notificaciones en tiempo real: revisa la sección Webhook Notifications de más abajo.

Campos de la respuesta:

Campo	Descripción
`ticketNumber`	Identificador único de la transacción. Úsalo para consultar el estado y para las anulaciones.
`status`	Estado inicial de la transacción
`details`	Detalles de la transacción, incluido `keyResolution` en las transferencias Bre-B
`keyResolution`	Solo Bre-B: datos del destinatario resueltos (nombre del titular, banco, tipo de cuenta)

Consulta el estado de la transacción

Llama al endpoint Get Status usando el ticketNumber como parámetro de ruta para confirmar el resultado final.

Estados posibles:

Estado	Significado
`INITIALIZED`	La transacción se creó pero aún no se procesa
`APPROVAL`	La transferencia se completó con éxito
`DECLINED`	La transferencia fue rechazada

Una transacción en estado INITIALIZED se puede anular con el endpoint Void.

Notificaciones por webhook

Incluye el objeto webhooks en tu solicitud de Init Transaction para recibir notificaciones en tiempo real:

{
  "webhooks": [
    {
      "events": ["approvedTransaction", "declinedTransaction"],
      "headers": [
        { "label": "Authorization", "value": "Bearer your-token" }
      ],
      "urls": [
        "https://merchant.example.com/webhooks/transfer-out"
      ]
    }
  ]
}

Si ya tienes un webhook configurado en la Console, agregar el objeto webhooks en la solicitud de la API dispara los dos canales al mismo tiempo.

Saldo del wallet

Antes de iniciar dispersiones, puedes consultar el saldo actual de tu wallet de Kushki con el endpoint Balance for Payouts.

La respuesta devuelve tu currentBalance (en COP) y el timestamp balanceDate de la última actualización.

Autenticación

Cada paso usa una credencial distinta:

Paso	Cabecera	Tipo de llave
Get Bank List	`Public-Merchant-Id`	Public Key
Solicitar un token	`Public-Merchant-Id`	Public Key
Init Transaction	`Private-Merchant-Id`	Private Key
Get Status	`Private-Merchant-Id`	Private Key
Void	`Private-Merchant-Id`	Private Key
Balance for Payouts	`Private-Merchant-Id`	Private Key

Nunca expongas tu Private-Merchant-Id en código del cliente ni del frontend. Las solicitudes de token y las llamadas a la lista de bancos que usan la Public Key se pueden hacer desde el frontend; todas las demás deben salir de tu backend.

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Obtener lista de bancos

Obtén la lista de bancos de destino disponibles. Obligatorio para las transferencias ACH. Usa v2 para la mejor experiencia.

Obtener lista de bancos V2

Endpoint de lista de bancos ampliada. Recomendado.

Solicitar un token de Transfer Out

Tokeniza los datos del destinatario y el monto. Soporta los modos ACH y Bre-B. El token es válido 30 minutos y de un solo uso.

Iniciar transacción

Inicia la dispersión con el token. Devuelve un ticketNumber para hacer seguimiento del estado.

Consultar estado

Consulta el estado actual de una transacción de Transfer Out con su ticketNumber.

Saldo para dispersiones

Devuelve el saldo disponible actual en tu wallet de dispersión de Kushki.

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

Modos de transferencia#

Flujo de pago#

Notificaciones por webhook#

Saldo del wallet#

Autenticación#

Uso de la API#

Endpoints disponibles#

Modos de transferencia

Flujo de pago

Notificaciones por webhook

Saldo del wallet

Autenticación

Uso de la API

Endpoints disponibles