Skip to main content
O boleto bancario e um método de pagamento assíncrono por natureza — o comprador pode pagar em qualquer banco, internet banking ou casa loteria, e a confirmação chega em D+1 a D+3 dias úteis. Por isso, o crédito na wallet e agendado, não imediato.

​
Diferenca Critica: Crédito Agendado

Ao contrario do PIX (crédito imediato), o pagamento de boleto resulta em PENDING_CREDIT. O saldo real so e liberado após D+3 dias úteis via agendamento automático. Durante esse período, o valor fica em boletoPendingBalance.

​
Visao Geral do Fluxo

​
Emitindo um Boleto

1

Crie a transação BOLETO

curl -X POST https://api.linka.com/transactions \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid_v4_unico}" \
  -d '{
    "amount": 15000,
    "method": "BOLETO",
    "description": "Pedido #456",
    "customer": {
      "name": "Maria Oliveira",
      "email": "[email protected]",
      "document": "98765432100"
    },
    "items": [
      {
        "title": "Produto B",
        "quantity": 2,
        "unitPrice": 7500
      }
    ]
  }'
2

Exiba o boleto para o comprador

A resposta contém a URL de impressao e o código de barras:
Resposta 201
{
  "status": true,
  "data": {
    "id": "txn_uuid_aqui",
    "status": "PENDING",
    "amount": 15000,
    "method": "BOLETO",
    "boleto": {
      "url": "https://boleto.ip.com.br/imprimir/abc123",
      "barcode": "34191.09008 00000.000014 00000.000000 1 00000000015000",
      "dueDate": "2026-04-12T23:59:59.000Z"
    },
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}
Disponibilize o link boleto.url para impressao e o boleto.barcode para pagamento por código.
3

Aguarde o webhook TRANSACTION_PAID

Quando a confirmação bancaria chegar (D+1 a D+3), a Linka dispara o webhook:
Payload TRANSACTION_PAID
{
  "eventType": "TRANSACTION_PAID",
  "signature": "hmac-v1-sha256-...",
  "id": "txn_uuid_aqui",
  "amount": 15000,
  "method": "BOLETO",
  "status": "PAID",
  "boleto": {
    "url": "https://boleto.ip.com.br/imprimir/abc123",
    "barcode": "34191.09008 00000.000014 00000.000000 1 00000000015000",
    "dueDate": "2026-04-12T23:59:59.000Z"
  },
  "paidAt": "2026-04-10T14:30:00.000Z",
  "description": "Pedido #456",
  "customer": { "name": "Ma***", "email": "m***@exemplo.com.br" },
  "createdAt": "2026-04-09T12:00:00.000Z"
}
Ao receber TRANSACTION_PAID, o pedido pode ser confirmado no seu sistema. O valor estara em boletoPendingBalance na wallet, não em balance.
4

Aguarde a liberação do saldo (D+3)

Após D+3 dias úteis do pagamento, o sistema libera automaticamente o saldo. O valor migra de boletoPendingBalance para boletoBalance e fica disponível para saque.Não ha webhook específico para a liberação do saldo — monitore o campo boletoBalance na wallet se precisar rastrear este evento.

​
Campos da Requisicao

CampoTipoObrigatórioDescrição
amountintegerSimValor em centavos
methodstringSimDeve ser "BOLETO"
descriptionstringNãoDescrição no boleto
customer.namestringSimNome do pagador
customer.emailstringSimEmail do pagador
customer.documentstringSimCPF (11) ou CNPJ (14 digitos)
itemsarrayNãoItens do pedido

​
Saldos da Wallet para Boleto

Campo na walletDescrição
boletoPendingBalanceValor pago, aguardando D+3 dias úteis
boletoBalanceSaldo liberado, disponível para saque

​
Boleto Vencido sem Pagamento

Se o comprador não pagar até a data de vencimento, a IP envia um webhook de expiração e a transação muda para FAILED:
Payload TRANSACTION_FAILED
{
  "eventType": "TRANSACTION_FAILED",
  "id": "txn_uuid_aqui",
  "status": "FAILED",
  "method": "BOLETO",
  ...
}
Não ha reembolso em caso de boleto vencido — o comprador simplesmente não pagou. A transação pode ser recriada se o seller quiser emitir um novo boleto.

​
Tratamento de Erros

Status HTTPCódigo de erroCausa
400INVALID_INPUTCampos obrigatórios ausentes
422FEE_EXCEEDS_AMOUNTTaxa maior que o valor da transação
503PROVIDER_UNAVAILABLEIP indisponível

​
Pontos de Atencao

  • O prazo de confirmação varia de D+1 a D+3 conforme a IP configurada e o horario do pagamento.
  • O campo paidAt e fornecido pela IP. Em casos onde a IP não envia esse campo, o sistema usa o timestamp do processamento como fallback.
  • Boletos geralmente tem vencimento de 1-3 dias úteis — configure prazos adequados no seu fluxo de checkout.
  • O customer.document (CPF/CNPJ) e obrigatório para emissão do boleto conforme regulamentacao bancaria.