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

# Criar um Pagamento

> Envie fundos do seu saldo pré-financiado para um beneficiário

## Pré-requisitos

Antes de criar um pagamento você precisa:

1. **Uma conta pré-financiada** — criada via `POST /api/v2/customers/pre-fund/create`
2. **Saldo suficiente** — verifique via `GET /api/v2/customers/balances`
3. **Dados do beneficiário** — conta bancária, endereço de carteira ou alias de pagamento do destinatário

<Card title="Configurar Contas Pré-Financiadas" icon="vault" href="/pt/guides/pre-fund/pre-fund-accounts">
  Ainda não tem uma conta pré-financiada? Comece aqui.
</Card>

## Fluxo Completo de Pagamento

<Steps>
  <Step title="Verificar Saldo Disponível">
    Confirme que você tem fundos suficientes antes de enviar o pagamento.

    ```bash theme={null}
    GET /api/v2/customers/balances
    ```

    ```json Resposta theme={null}
    [
      {
        "id": "balance-id",
        "currency": "COP",
        "amount": "10000000.00",
        "accountId": "prefund-account-id"
      }
    ]
    ```
  </Step>

  <Step title="Criar o Pagamento">
    Envie a solicitação de pagamento com sua conta pré-financiada, valor e beneficiário.

    ```bash theme={null}
    POST /api/v2/payouts
    ```
  </Step>

  <Step title="Acompanhar o Status">
    Consulte o pagamento ou ouça webhooks até atingir um status terminal (`COMPLETED`, `FAILED`, `REJECTED`, `ERROR` ou `REFUNDED`).
  </Step>
</Steps>

## Exemplo de Implementação

<CodeGroup>
  ```bash cURL theme={null}
  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": "BANK",
        "account": {
          "firstName": "Maria",
          "lastName": "Garcia",
          "email": "maria@exemplo.com",
          "phone": "3001234567",
          "document": { "type": "CC", "number": "12345678" },
          "accountNumber": "123456789",
          "bankCode": "001",
          "type": "savings",
          "countryCode": "CO"
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const criarPagamento = async (preFundAccountId, amount, beneficiary) => {
    const response = await fetch(
      'https://sandbox.killb.app/api/v2/payouts',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          preFundAccountId,
          amount,
          beneficiary
        })
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Pagamento falhou: ${JSON.stringify(error)}`);
    }

    return response.json();
  };

  // Exemplo: enviar 500.000 COP via Bank Transfer
  const pagamento = await criarPagamento(
    'prefund-account-id',
    500000,
    {
      type: 'BANK',
      account: {
        firstName: 'Maria',
        lastName: 'Garcia',
        email: 'maria@exemplo.com',
        phone: '3001234567',
        document: { type: 'CC', number: '12345678' },
        accountNumber: '123456789',
        bankCode: '001',
        type: 'savings',
        countryCode: 'CO'
      }
    }
  );

  console.log('ID do Pagamento:', pagamento.id);
  console.log('Status:', pagamento.status);
  ```

  ```python Python theme={null}
  import requests

  def criar_pagamento(pre_fund_account_id, amount, beneficiary, access_token):
      response = requests.post(
          'https://sandbox.killb.app/api/v2/payouts',
          headers={
              'Authorization': f'Bearer {access_token}',
              'Content-Type': 'application/json',
              'Idempotency-Key': f'pagamento-{pre_fund_account_id}-{amount}'
          },
          json={
              'preFundAccountId': pre_fund_account_id,
              'amount': amount,
              'beneficiary': beneficiary
          }
      )
      response.raise_for_status()
      return response.json()

  # Exemplo: enviar 500.000 COP via Bank Transfer
  pagamento = criar_pagamento(
      pre_fund_account_id='prefund-account-id',
      amount=500000,
      beneficiary={
          'type': 'BANK',
          'account': {
              'firstName': 'Maria',
              'lastName': 'Garcia',
              'email': 'maria@exemplo.com',
              'phone': '3001234567',
              'document': {'type': 'CC', 'number': '12345678'},
              'accountNumber': '123456789',
              'bankCode': '001',
              'type': 'savings',
              'countryCode': 'CO'
          }
      },
      access_token=token
  )

  print(f"Pagamento criado: {pagamento['id']} — {pagamento['status']}")
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "id": "payout-abc123",
  "amount": 500000,
  "currency": "COP",
  "status": "PENDING",
  "externalId": "pagamento-2024-001",
  "beneficiary": {
    "type": "BANK",
    "account": { ... }
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

## Tipos de Beneficiário

<Tabs>
  <Tab title="Bank Transfer (Colômbia)">
    Transferência padrão para conta bancária colombiana via Bank Transfer.

    ```json theme={null}
    {
      "type": "BANK",
      "account": {
        "firstName": "Maria",
        "lastName": "Garcia",
        "email": "maria@exemplo.com",
        "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`, `countryCode`

    Use `GET /api/v2/banks` para consultar os valores válidos de `bankCode`.
  </Tab>

  <Tab title="BREB (Colômbia)">
    Desembolso via alias registrado (telefone, email, CPF ou alias BREB).

    ```json theme={null}
    {
      "type": "BREB",
      "account": {
        "firstName": "Carlos",
        "lastName": "Lopez",
        "email": "carlos@exemplo.com",
        "phone": "3109876543",
        "document": {
          "type": "CC",
          "number": "87654321"
        },
        "aliasType": "PHONE",
        "alias": "3109876543",
        "countryCode": "CO"
      }
    }
    ```

    **Tipos de alias:** `NATIONAL_ID`, `PHONE`, `EMAIL`, `ALPHANUMERIC`, `BUSINESS_ID`
  </Tab>
</Tabs>

## Verificar Saldo Antes do Pagamento

Sempre verifique o saldo disponível antes de enviar pagamentos grandes:

```javascript theme={null}
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.

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

<Tip>
  Use um identificador único e estável como chave — seu ID de pagamento interno ou um UUID vinculado à transação funciona bem.
</Tip>

## Listar Pagamentos

Recupere todos os pagamentos com filtros opcionais:

```javascript theme={null}
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

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

  <Card title="Configurar Webhooks" icon="bell" href="/pt/guides/webhooks/setup">
    Configure notificações webhook para PAYOUT
  </Card>
</CardGroup>