O que são Pagamentos?
Pagamentos são desembolsos de saída que permitem enviar fundos do seu saldo pré-financiado da KillB para qualquer beneficiário — contas bancárias, carteiras cripto ou aliases de pagamento locais. É a forma mais simples de distribuir dinheiro em escala: sem etapa de cotação, sem URL de pagamento, sem aguardar ação do usuário final. Você tem o saldo; a KillB roteia para o destino.Pagamentos são um recurso B2B projetado para empresas que precisam desembolsar fundos para muitos destinatários (folha de pagamento, pagamentos a fornecedores, liquidações de marketplace, distribuições cripto, etc.).
Pagamentos vs. Ramps
Tanto pagamentos quanto ramps movem dinheiro, mas servem propósitos diferentes:| Pagamentos | Off-Ramps | |
|---|---|---|
| Direção | Pré-financiado → Beneficiário | Carteira cripto → Conta fiat |
| Quem inicia | Seu backend | Seu usuário final |
| Cotação necessária? | Não | Sim |
| URL de pagamento? | Não | Sim |
| Caso de uso | Desembolsos em lote, folha, liquidações | Saques do usuário |
| Fonte do saldo | Conta pré-financiada | Carteira cripto do usuário |
Como Funciona
Pré-requisitos
Cada pagamento requer:- Uma conta pré-financiada ativa — mantém o saldo a ser desembolsado
- Saldo suficiente — igual ou maior que o valor do pagamento
- Dados válidos do beneficiário — correspondentes aos campos exigidos pelo rail de pagamento escolhido
Configurar Contas Pré-Financiadas
Aprenda a criar e financiar suas contas pré-financiadas
Ciclo de Vida do Pagamento
Status
| Status | Fase | Significado |
|---|---|---|
CREATED | Inicial | O pagamento foi recebido e persistido, aguardando entrada na fila |
CASH_IN_PENDING | Cash In | Coleta de fundos recebidos na fila |
CASH_IN_PROCESSING | Cash In | Coletando fundos do saldo pré-financiado |
CASH_IN_COMPLETED | Cash In | Fundos coletados com sucesso |
KYT_OUT_PENDING | KYT Out | Transação de saída na fila para verificação de conformidade |
KYT_OUT_PROCESSING | KYT Out | Revisão de conformidade em andamento (saída) |
KYT_OUT_COMPLETED | KYT Out | Verificação de conformidade de saída aprovada |
CASH_OUT_PENDING | Cash Out | Desembolso ao beneficiário na fila |
CASH_OUT_PROCESSING | Cash Out | Fundos submetidos ao provedor de pagamentos |
CASH_OUT_COMPLETED | Cash Out | Provedor de pagamentos confirmou a entrega |
COMPLETED | Terminal | Pagamento totalmente liquidado |
REVIEW_NEEDED | Revisão | Transação sinalizada para revisão manual de conformidade |
FAILED | Estado de Erro | Operação falhou. Terminal durante Cash In; inicia fluxo de reembolso se ocorrer em fase posterior. |
REJECTED | Estado de Erro | Pagamento bloqueado por revisão de conformidade. Sempre aciona o fluxo de reembolso, pois ocorre apenas após o Cash In. |
ERROR | Estado de Erro | Erro interno do sistema. Terminal durante Cash In; inicia fluxo de reembolso se ocorrer em fase posterior. |
REFUND_PENDING | Reembolso | Reembolso ao saldo pré-financiado na fila |
REFUND_PROCESSING | Reembolso | Reembolso em andamento |
REFUNDED | Terminal | Fundos devolvidos ao saldo pré-financiado |
Tipos de Beneficiário Suportados
| Tipo | Região | Descrição |
|---|---|---|
BANK | Colômbia | Transferência para conta bancária via Bank Transfer |
BREB | Colômbia | Alias registrado (telefone, email, CPF) |
Idempotência
Para evitar desembolsos duplicados em novas tentativas de rede, passe um header únicoIdempotency-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.
Perguntas Frequentes
O que acontece com meu saldo se um pagamento falhar?
O que acontece com meu saldo se um pagamento falhar?
Depende da fase em que a falha ocorre:
- Durante Cash In — Nenhum fundo foi coletado, portanto nada é debitado do seu saldo pré-financiado.
- Após Cash In (KYT Out, Cash Out) — Os fundos já foram coletados. O pagamento segue para o fluxo de reembolso (
REFUND_PENDING→REFUND_PROCESSING→REFUNDED), devolvendo-os ao seu saldo pré-financiado.
Qual a diferença entre ERROR, FAILED e REJECTED?
Qual a diferença entre ERROR, FAILED e REJECTED?
Cada status reflete uma origem de falha distinta:
ERROR— Erro interno do sistema na KillB. Nenhum fundo foi desembolsado.FAILED— O banco do beneficiário recusou a transferência devido a dados de conta inválidos ou incorretos fornecidos pelo remetente.REJECTED— O pagamento foi bloqueado por uma revisão de conformidade na KillB. Os fundos são devolvidos ao seu saldo pré-financiado via fluxo de reembolso.
O que é REVIEW_NEEDED?
O que é REVIEW_NEEDED?
Um pagamento entra em
REVIEW_NEEDED quando a verificação KYT Out sinaliza a transação para revisão manual. Nenhuma ação é necessária da sua parte — o pagamento será retomado automaticamente após a conclusão da revisão ou mudará para REJECTED se bloqueado.Quando ocorre o status REFUNDED?
Quando ocorre o status REFUNDED?
Um pagamento atinge
REFUNDED quando FAILED ou ERROR ocorre após a fase de Cash In (KYT Out ou Cash Out), ou quando o pagamento é REJECTED por compliance. Como os fundos já foram coletados, o pagamento passa automaticamente por REFUND_PENDING → REFUND_PROCESSING → REFUNDED.Se FAILED ou ERROR ocorrer durante Cash In, nenhum fundo foi coletado e nenhum reembolso é emitido.Quanto tempo leva um pagamento?
Quanto tempo leva um pagamento?
Transferências Bank Transfer e BREB tipicamente liquidam em minutos a algumas horas úteis dependendo do banco e dos horários de corte.
Como funciona a idempotência?
Como funciona a idempotência?
Passe um header único
Idempotency-Key nas solicitações de criação de pagamentos. Se a mesma chave for recebida duas vezes (ex.: em uma nova tentativa), a KillB retorna o pagamento original em vez de criar um desembolso duplicado.Boas Práticas
- Verifique o saldo primeiro — sempre chame
GET /api/v2/customers/balancesantes de criar um pagamento para evitar falhas por saldo insuficiente - Use
Idempotency-Key— sempre passe uma chave única por desembolso para retentar com segurança sem duplicatas - Assine webhooks — configure webhooks de eventos
PAYOUTpara atualizações de status em tempo real - Monitore pagamentos REJECTED — registre dados completos do beneficiário na rejeição para identificar e corrigir detalhes inválidos de conta
- Reconcilie diariamente — obtenha todos os pagamentos do dia anterior e compare com seu livro-razão interno
Guias Relacionados
Criar um Pagamento
Guia de implementação passo a passo
Rastreamento de Status
Monitore pagamentos com webhooks e polling
Contas Pré-Financiadas
Financie suas contas pré-financiadas
Webhooks
Notificações de eventos em tempo real