Pré-requisitos Antes de criar um pagamento você precisa:
Uma conta pré-financiada — criada via POST /api/v2/customers/pre-fund/createSaldo suficiente — verifique via GET /api/v2/customers/balancesDados do beneficiário — conta bancária, endereço de carteira ou alias de pagamento do destinatário
Configurar Contas Pré-Financiadas Ainda não tem uma conta pré-financiada? Comece aqui.
Fluxo Completo de Pagamento
Verificar Saldo Disponível
Confirme que você tem fundos suficientes antes de enviar o pagamento. GET /api/v2/customers/balances
[ { "id" : "balance-id" , "currency" : "COP" , "amount" : "10000000.00" , "accountId" : "prefund-account-id" } ]
Criar o Pagamento
Envie a solicitação de pagamento com sua conta pré-financiada, valor e beneficiário.
Acompanhar o Status
Consulte o pagamento ou ouça webhooks até atingir um status terminal (COMPLETED, ERROR, FAILED, REJECTED ou REFUNDED).
Exemplo de Implementação curl -X POST https://sandbox.killb.app/api/v2/payouts \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pagamento-2024-001" \ -d '{ "preFundAccountId": "prefund-account-id", "amount": 500000, "externalId": "pagamento-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" } } }'
Resposta: { "id" : "payout-abc123" , "amount" : 500000 , "currency" : "COP" , "status" : "PENDING" , "externalId" : "pagamento-2024-001" , "beneficiary" : { "type" : "PSE" , "account" : { ... } }, "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T10:30:00.000Z" }
Tipos de Beneficiário PSE (Colômbia)
BREB (Colômbia)
Transferência padrão para conta bancária colombiana via 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 obrigatórios: firstName ou companyName, lastName, email, phone, document, accountNumber, bankCode, type, countryCodeUse GET /api/v2/banks para consultar os valores válidos de bankCode. Desembolso via alias registrado (telefone, email, CPF ou 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 do Pagamento Sempre verifique o saldo disponível antes de enviar pagamentos grandes:
const verificarSaldo = async ( preFundAccountId , valorNecessario ) => { const balances = await fetch ( '/api/v2/customers/balances' , { headers: { 'Authorization' : `Bearer ${ token } ` } }). then ( r => r . json ()); const conta = balances . find ( b => b . accountId === preFundAccountId ); if ( ! conta || parseFloat ( conta . amount ) < valorNecessario ) { throw new Error ( `Saldo insuficiente. Disponível: ${ conta ?. amount ?? 0 } , Necessário: ${ valorNecessario } ` ); } return conta ; };
Idempotência Para evitar desembolsos duplicados em novas tentativas de rede, passe um header único Idempotency-Key em cada solicitação de criação de pagamento. Se a mesma chave for recebida duas vezes, a KillB retorna o pagamento original em vez de criar um novo.
Idempotency-Key: < sua-referência-única-de-pagament o >
Use um identificador único e estável como chave — seu ID de pagamento interno ou um UUID vinculado à transação funciona bem.
Listar Pagamentos Recupere todos os pagamentos com filtros opcionais:
const listarPagamentos = 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 } }; // Obter todos os pagamentos pendentes const pendentes = await listarPagamentos ({ status: 'PENDING' });
Próximos Passos
Rastreamento de Status Monitore pagamentos com polling e webhooks
Configurar Webhooks Configure notificações webhook para PAYOUT
