Criar um Pagamento

Pré-requisitos

Antes de criar um pagamento você precisa:

Uma conta pré-financiada — criada via POST /api/v2/customers/pre-fund/create
Saldo suficiente — verifique via GET /api/v2/customers/balances
Dados 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

Resposta

[
  {
    "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.

POST /api/v2/payouts

Acompanhar o Status

Consulte o pagamento ou ouça webhooks até atingir um status terminal (COMPLETED, FAILED, REJECTED, ERROR 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": "BANK",
      "account": {
        "firstName": "Maria",
        "lastName": "Garcia",
        "email": "[email protected]",
        "phone": "3001234567",
        "document": { "type": "CC", "number": "12345678" },
        "accountNumber": "123456789",
        "bankCode": "001",
        "type": "savings",
        "countryCode": "CO"
      }
    }
  }'

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: '[email protected]',
      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);

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': '[email protected]',
            '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']}")

Resposta:

{
  "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

Bank Transfer (Colômbia)
BREB (Colômbia)

Transferência padrão para conta bancária colombiana via Bank Transfer.

{
  "type": "BANK",
  "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_ID

Verificar 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-pagamento>

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' });

Começar

Conceitos Principais

Usuários e KYC

Contas

Contas Pré-Financiadas

Pagamentos

On/Off Ramps

Poupanças e Custódia

Webhooks

Recursos

Pré-requisitos

Configurar Contas Pré-Financiadas

Fluxo Completo de Pagamento

Exemplo de Implementação

Tipos de Beneficiário

Verificar Saldo Antes do Pagamento

Idempotência

Listar Pagamentos

Próximos Passos

Rastreamento de Status

Configurar Webhooks

​Pré-requisitos

Configurar Contas Pré-Financiadas

​Fluxo Completo de Pagamento

​Exemplo de Implementação

​Tipos de Beneficiário

​Verificar Saldo Antes do Pagamento

​Idempotência

​Listar Pagamentos

​Próximos Passos

Rastreamento de Status

Configurar Webhooks

Pré-requisitos

Fluxo Completo de Pagamento

Exemplo de Implementação

Tipos de Beneficiário

Verificar Saldo Antes do Pagamento

Idempotência

Listar Pagamentos

Próximos Passos