Prerrequisitos Antes de crear un pago necesitas:
Una cuenta pre-financiada — creada vía POST /api/v2/customers/pre-fund/createSaldo suficiente — verifica vía GET /api/v2/customers/balancesDatos del beneficiario — cuenta bancaria, dirección de billetera o alias de pago del destinatario
Configurar Cuentas Pre-Financiadas ¿Aún no tienes una cuenta pre-financiada? Comienza aquí.
Flujo Completo de Pago
Verificar Saldo Disponible
Confirma que tienes fondos suficientes antes de enviar el pago. GET /api/v2/customers/balances
[ { "id" : "balance-id" , "currency" : "COP" , "amount" : "10000000.00" , "accountId" : "prefund-account-id" } ]
Crear el Pago
Envía la solicitud de pago con tu cuenta pre-financiada, monto y beneficiario.
Seguir el Estado
Consulta el pago o escucha webhooks hasta que alcance un estado terminal (COMPLETED, ERROR, FAILED, REJECTED o REFUNDED).
Ejemplo de Implementación curl -X POST https://sandbox.killb.app/api/v2/payouts \ -H "Authorization: Bearer TU_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pago-2024-001" \ -d '{ "preFundAccountId": "prefund-account-id", "amount": 500000, "externalId": "pago-2024-001", "beneficiary": { "type": "PSE", "account": { "firstName": "Maria", "lastName": "Garcia", "email": "[email protected] ", "phone": "3001234567", "document": { "type": "CC", "number": "12345678" }, "accountNumber": "123456789", "bankCode": "001", "type": "savings", "countryCode": "CO" } } }'
Respuesta: { "id" : "payout-abc123" , "amount" : 500000 , "currency" : "COP" , "status" : "PENDING" , "externalId" : "pago-2024-001" , "beneficiary" : { "type" : "PSE" , "account" : { ... } }, "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T10:30:00.000Z" }
Tipos de Beneficiario PSE (Colombia)
BREB (Colombia)
Transferencia estándar a cuenta bancaria colombiana vía PSE. { "type" : "PSE" , "account" : { "firstName" : "Maria" , "lastName" : "Garcia" , "email" : "[email protected] " , "phone" : "3001234567" , "document" : { "type" : "CC" , "number" : "12345678" }, "accountNumber" : "123456789" , "bankCode" : "001" , "type" : "savings" , "countryCode" : "CO" } }
Campos requeridos: firstName o companyName, lastName, email, phone, document, accountNumber, bankCode, type, countryCodeUsa GET /api/v2/banks para consultar los valores válidos de bankCode. Dispersión vía alias registrado (teléfono, email, cédula o alias BREB). { "type" : "BREB" , "account" : { "firstName" : "Carlos" , "lastName" : "Lopez" , "email" : "[email protected] " , "phone" : "3109876543" , "document" : { "type" : "CC" , "number" : "87654321" }, "aliasType" : "PHONE" , "alias" : "3109876543" , "countryCode" : "CO" } }
Tipos de alias: NATIONAL_ID, PHONE, EMAIL, ALPHANUMERIC, BUSINESS_IDVerificar Saldo Antes del Pago Siempre verifica el saldo disponible antes de enviar pagos grandes:
const verificarSaldo = async ( preFundAccountId , montoRequerido ) => { const balances = await fetch ( '/api/v2/customers/balances' , { headers: { 'Authorization' : `Bearer ${ token } ` } }). then ( r => r . json ()); const cuenta = balances . find ( b => b . accountId === preFundAccountId ); if ( ! cuenta || parseFloat ( cuenta . amount ) < montoRequerido ) { throw new Error ( `Saldo insuficiente. Disponible: ${ cuenta ?. amount ?? 0 } , Requerido: ${ montoRequerido } ` ); } return cuenta ; };
Idempotencia Para evitar dispersiones duplicadas en reintentos de red, envía un header único Idempotency-Key en cada solicitud de creación de pago. Si se recibe la misma clave dos veces, KillB devuelve el pago original en lugar de crear uno nuevo.
Idempotency-Key: < tu-referencia-única-de-pag o >
Usa un identificador único y estable como clave — tu ID de pago interno o un UUID vinculado a la transacción funciona bien.
Listar Pagos Recupera todos los pagos con filtros opcionales:
const listarPagos = async ({ status , externalId , page = 1 , limit = 20 } = {}) => { const params = new URLSearchParams ({ page , limit }); if ( status ) params . set ( 'status' , status ); if ( externalId ) params . set ( 'externalId' , externalId ); const response = await fetch ( `https://sandbox.killb.app/api/v2/payouts? ${ params } ` , { headers: { 'Authorization' : `Bearer ${ token } ` } } ); return response . json (); // { payouts: [...], totalPage: N } }; // Obtener todos los pagos pendientes const pendientes = await listarPagos ({ status: 'PENDING' });
Próximos Pasos
Seguimiento de Estado Monitorea pagos con polling y webhooks
Configurar Webhooks Configura notificaciones webhook para PAYOUT
