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 | Significado |
|---|---|
CREATED | O pagamento foi recebido e persistido, aguardando entrada na fila. |
PENDING | O pagamento está na fila aguardando ser despachado ao provedor de pagamentos. |
PROCESSING | O desembolso foi submetido ao provedor de pagamentos e aguarda confirmação. |
COMPLETED | O provedor confirmou a entrega bem-sucedida dos fundos ao beneficiário. |
ERROR | Erro interno do sistema. Nenhum fundo foi desembolsado. |
FAILED | Desembolso recusado devido a dados de conta do beneficiário inválidos ou incorretos. |
REJECTED | O pagamento foi bloqueado por uma revisão de conformidade e não será processado. |
REFUNDED | Os fundos desembolsados foram devolvidos ao saldo pré-financiado. |
Tipos de Beneficiário Suportados
| Tipo | Região | Descrição |
|---|---|---|
PSE | Colômbia | Transferência para conta bancária via PSE |
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?
Se um pagamento atingir o status
FAILED, nenhum fundo é debitado do seu saldo pré-financiado. O saldo só é debitado quando o pagamento atinge COMPLETED.Posso cancelar um pagamento?
Posso cancelar um pagamento?
Pagamentos em status
PENDING podem ser canceláveis — entre em contato com o suporte. Uma vez que o pagamento muda para PROCESSING, o cancelamento não é mais possível pois os fundos já estão em trânsito.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 e não será processado.
Quando ocorre o status REFUNDED?
Quando ocorre o status REFUNDED?
Um pagamento atinge
REFUNDED quando os fundos desembolsados são devolvidos ao seu saldo pré-financiado — seja após uma entrega FAILED ou, em alguns casos, após um pagamento COMPLETED que foi posteriormente revertido pelo banco do beneficiário.Quanto tempo leva um pagamento?
Quanto tempo leva um pagamento?
Transferências PSE 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