Transfer Out
¡Ten en cuenta!
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
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 Hay dos versiones disponibles:
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.
| 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.Campos obligatorios para Colombia:
Tipos de cuenta para Colombia:
Tipos de documento aceptados en Colombia:
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.
| 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 |
| 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 |
| 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 Opcionalmente puedes incluir un objeto Campos de la respuesta:
token del paso anterior. Kushki valida el token y devuelve un ticketNumber junto con el estado de la transacción.webhooks en esta solicitud para recibir notificaciones en tiempo real: revisa la sección Webhook Notifications de más abajo.| 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 Estados posibles:
ticketNumber como parámetro de ruta para confirmar el resultado final.| 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 INITIALIZEDse puede anular con el endpoint Void.
Notificaciones por webhook
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"
]
}
]
}webhooks en la solicitud de la API dispara los dos canales al mismo tiempo.Saldo del wallet
currentBalance (en COP) y el timestamp balanceDate de la última actualización.Autenticación
| 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 |
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.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.¿Tienes una sugerencia sobre esta documentación? Contáctanos.
Modified at 2026-09-11 14:48:31