> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagamentos

> Envie fundos do seu saldo pré-financiado diretamente para beneficiários

## 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.

<Info>
  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.).
</Info>

## 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

```mermaid theme={null}
sequenceDiagram
    participant Você as Seu Backend
    participant KillB
    participant Banco as Banco / Carteira

    Você->>KillB: POST /api/v2/payouts
    Note over KillB: Debitar saldo pré-financiado
    KillB-->>Você: { id, status: "CREATED" }
    KillB->>Banco: Rotear pagamento pelo pipeline
    Banco-->>KillB: Confirmação
    KillB-->>Você: Webhook: payout.completed
```

## Pré-requisitos

Cada pagamento requer:

1. **Uma conta pré-financiada ativa** — mantém o saldo a ser desembolsado
2. **Saldo suficiente** — igual ou maior que o valor do pagamento
3. **Dados válidos do beneficiário** — correspondentes aos campos exigidos pelo rail de pagamento escolhido

<Card title="Configurar Contas Pré-Financiadas" icon="vault" href="/pt/guides/pre-fund/pre-fund-accounts">
  Aprenda a criar e financiar suas contas pré-financiadas
</Card>

## Ciclo de Vida do Pagamento

```mermaid theme={null}
graph LR
    CREATED --> CashIn[Cash In]
    CashIn --> KYTOut[KYT Out]
    KYTOut --> CashOut[Cash Out]
    CashOut --> COMPLETED

    KYTOut -.-> REVIEW_NEEDED
    REVIEW_NEEDED -.-> REJECTED

    KYTOut -.-> FAILED
    KYTOut -.-> ERROR
    CashOut -.-> FAILED
    CashOut -.-> ERROR
    FAILED --> REFUNDED
    ERROR --> REFUNDED
    REJECTED --> REFUNDED

    CashIn -.->|"terminal"| FAILED
    CashIn -.->|"terminal"| ERROR

    style COMPLETED fill:#22c55e,color:#fff
    style REJECTED fill:#f97316,color:#fff
    style FAILED fill:#ef4444,color:#fff
    style ERROR fill:#ef4444,color:#fff
    style REFUNDED fill:#6366f1,color:#fff
    style REVIEW_NEEDED fill:#eab308,color:#000
```

<Warning>
  `FAILED` e `ERROR` durante a fase de **Cash In** são terminais — nenhum fundo foi coletado, portanto nenhum reembolso é emitido. Para as fases seguintes (KYT Out, Cash Out), esses status iniciam o fluxo de reembolso. `REJECTED` também aciona o fluxo de reembolso, pois ocorre apenas após o Cash In.
</Warning>

### 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 ú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.

```bash theme={null}
Idempotency-Key: <sua-referência-única-de-pagamento>
```

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="O que acontece com meu saldo se um pagamento falhar?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="Qual a diferença entre ERROR, FAILED e REJECTED?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="O que é REVIEW_NEEDED?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="Quando ocorre o status REFUNDED?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="Quanto tempo leva um pagamento?" icon="circle-question">
    Transferências Bank Transfer e BREB tipicamente liquidam em minutos a algumas horas úteis dependendo do banco e dos horários de corte.
  </Accordion>

  <Accordion title="Como funciona a idempotência?" icon="circle-question">
    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.
  </Accordion>
</AccordionGroup>

## Boas Práticas

* **Verifique o saldo primeiro** — sempre chame `GET /api/v2/customers/balances` antes 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 `PAYOUT` para 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

<CardGroup cols={2}>
  <Card title="Criar um Pagamento" icon="paper-plane" href="/pt/guides/payouts/create-payout">
    Guia de implementação passo a passo
  </Card>

  <Card title="Rastreamento de Status" icon="chart-line" href="/pt/guides/payouts/payout-status">
    Monitore pagamentos com webhooks e polling
  </Card>

  <Card title="Contas Pré-Financiadas" icon="vault" href="/pt/guides/pre-fund/pre-fund-accounts">
    Financie suas contas pré-financiadas
  </Card>

  <Card title="Webhooks" icon="bell" href="/pt/concepts/webhooks">
    Notificações de eventos em tempo real
  </Card>
</CardGroup>