Cobrar com boleto

Para receber dinheiro por boleto, crie uma cobrança por boleto (boleto-billing) em uma carteira. O Portão 3 registra o boleto no banco e retorna a linha digitável e o código de barras, que você compartilha com o pagador — ou envie a ele o PDF do boleto. Quando ele paga, o valor é creditado na carteira. Uma cobrança por boleto não tem webhook: consulte-a para acompanhá-la.

Fluxo

Etapa 1: Criar a cobrança

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto-billing' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "txnCurrency": "986",
    "txnAmount": 150000,
    "txnDivergentAmountType": "NOT_ALLOW_DIFFERENT_AMOUNT",
    "dueDate": "2026-11-20",
    "expiresAt": "2026-12-20",
    "description": "Mensalidade de novembro",
    "customer": {
      "name": "Padaria Pão Dourado Ltda",
      "document": "11222333000181",
      "address": {
        "street": "Rua das Laranjeiras",
        "number": "250",
        "complement": "Loja 2",
        "neighborhood": "Centro",
        "postalCode": "01310-100",
        "city": "São Paulo",
        "state": "SP"
      }
    }
  }'

Campo	Observações
`txnCurrency`	`986` (real) — a única moeda de um boleto.
`txnAmount`	Em centavos, até `24999900` (R$ 249.999,00).
`txnDivergentAmountType`	Envie `NOT_ALLOW_DIFFERENT_AMOUNT`. O boleto é sempre emitido por exatamente `txnAmount`: o pagador não pode pagar outro valor, seja qual for o enviado.
`dueDate`	O vencimento (`YYYY-MM-DD`): hoje ou depois.
`expiresAt`	O último dia em que o boleto pode ser pago (`YYYY-MM-DD`), depois de `dueDate`.
`description`	Uma descrição da cobrança.
`customer`	O pagador: `name`, `document` (CPF ou CNPJ) e `address`, com o CEP no formato `00000-000` e a sigla do estado.
`txnDiscountAmount`, `txnFineAmount`, `txnInterestAmount`	Opcionais — veja Desconto, multa e juros.

O banco registra o boleto na hora, então a cobrança volta CREATED, com o digitableLine e o barcode:

{
  "_id": "6727c3d4b4d3e80012c9b5c2",
  "status": "CREATED",
  "digitableLine": "34191090080123456789001234567890116210000150000",
  "barcode": "34191162100001500001090000012345678901234567",
  "txnAmount": 150000,
  "txnDivergentAmountType": "NOT_ALLOW_DIFFERENT_AMOUNT",
  "dueDate": "2026-11-20T00:00:00.000Z",
  "expiresAt": "2026-12-20T00:00:00.000Z",
  "customer": {
    "name": "Padaria Pao Dourado Ltda",
    "document": "11222333000181",
    "address": { "street": "Rua das Laranjeiras", "number": "250", "complement": "Loja 2", "neighborhood": "Centro", "postalCode": "01310-100", "city": "Sao Paulo", "state": "SP" }
  },
  "confirmedAmount": 0
}

O nome e o endereço do pagador são impressos no boleto como o banco os guarda — sem acentos, com o nome cortado em 50 caracteres, a rua em 40 e o bairro em 20 — e a cobrança os mostra assim. Raramente a cobrança volta INITIATED, ainda sem digitableLine e barcode: consulte-a até ela ficar CREATED. Referência: Criar uma cobrança por boleto

Etapa 2: Compartilhar o boleto

Mostre ao pagador o digitableLine (a linha digitável), que ele digita no app do banco, ou renderize o barcode. Para enviar o próprio boleto, baixe o PDF. A resposta é o arquivo PDF codificado em base64, como texto puro — decodifique-o para salvar o arquivo:

curl \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto-billing/{boletoId}/download/pdf' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  | base64 --decode > boleto.pdf

No navegador, prefixe o texto com data:application/pdf;base64, para abrir ou baixar o arquivo. Referência: Baixar o PDF de uma cobrança por boleto

Etapa 3: Saber quando foi pago

Uma cobrança por boleto não tem webhook. Consulte a cobrança para acompanhar o status, ou liste as cobranças da carteira filtrando pelo status — por exemplo ?status=PAID. Uma cobrança paga traz o que foi creditado na carteira em confirmedAmount (com desconto, multa ou juros aplicados) e quando em confirmedAt; o pagamento também aparece nas transações da carteira.

Status	Significado
`CREATED`	Registrado e pagável.
`PAID`	Pago e creditado na carteira.
`CANCELED`	Baixado sem pagamento pelo banco, algumas semanas depois de `expiresAt`. Não pode mais ser pago.
`INITIATED`, `REQUESTED`, `ENQUEUED`	Em registro no banco, ainda sem código de barras.
`PROCESSING`	Em emissão. Uma cobrança que ficou `PROCESSING` depois de a criação responder um erro nunca recebe código de barras — veja Erros antes de criá-la de novo.
`PROCESSING_PAYMENT`	Pago e sendo creditado.
`ERROR`	O banco não conseguiu emiti-lo.

Não é possível cancelar uma cobrança pela API: um boleto não pago continua pagável até expiresAt, e depois o banco o baixa (CANCELED).

Desconto, multa e juros

Os valores são em centavos. Os percentuais são frações de txnAmount: 0.02 é 2%, de 0.01 (1%) a 1 (100%).

{
  "txnDiscountAmount": [
    { "date": "2026-11-15", "amount": 0.05, "amountType": "PERCENT_UNTIL_INFORMED_DATE" }
  ],
  "txnFineAmount": { "date": "2026-11-21", "amount": 0.02, "amountType": "PERCENT" },
  "txnInterestAmount": { "date": "2026-11-21", "amount": 0.01, "amountType": "PERCENT_POINT_PER_MONTH_CALENDAR_DAYS" }
}

Regra	Tipos	Observações
Desconto (uma lista)	`FIXED_AMOUNT_UNTIL_INFORMED_DATE`, `PERCENT_UNTIL_INFORMED_DATE` — se pago até `date`. `AMOUNT_PER_ANTICIPATION_`, `PERCENT_PER_ANTICIPATION_` — por dia corrido ou útil de antecipação.	Cada `date` deve ser anterior a `dueDate`.
Multa	`PERCENT`, `FIXED_VALUE`	Cobrada uma vez, a partir de `date`, que deve ser posterior a `dueDate`.
Juros	`AMOUNT_CALENDAR_DAYS`, `AMOUNT_WORKING_DAYS` — centavos por dia de atraso, abaixo de 3,3% de `txnAmount`. `PERCENT_POINT_PER_MONTH_CALENDAR_DAYS`, `PERCENT_POINT_PER_MONTH_WORKING_DAYS` — uma taxa mensal.	Correm a partir de `date`, que deve ser posterior a `dueDate`.

PERCENT_POINT_PER_DAY_CALENDAR_DAYS e PERCENT_POINT_PER_DAY_WORKING_DAYS são aceitos, mas o boleto é emitido com o mesmo número como taxa por mês: 0.01 é cobrado como 1% ao mês, não 1% ao dia. A cobrança volta com o tipo PERCENT_POINT_PER_MONTH_* correspondente. Envie uma taxa mensal.

Erros

Status	`code`	Significado	O que fazer
`422`	`BAD_REQUEST`	Um campo é inválido; `fields` lista cada um.	Corrija a requisição.
`400`	`ACCOUNT_LIMITS_EXCEEDED`	O recebimento por boleto está desativado na conta, ou `txnAmount` passa do máximo por boleto.	Reduza o valor ou fale com o suporte.
`400`	`ACCOUNT_NOT_OPEN` · `WALLET_NOT_ACTIVE`	A conta não está aberta, ou a carteira não está `ACTIVE`.	Use uma carteira ativa.
`422`	`BANKING_PROVIDER_VALIDATION_ERROR`	O banco rejeitou um campo; `fields` o indica quando o banco diz qual.	Corrija o campo e crie a cobrança de novo.
`500` / `502` / `503` / `504`	`BANKING_PROVIDER_UNAVAILABLE` · `BANKING_PROVIDER_INTEGRATION_ERROR`	O banco não respondeu, ou a resposta não pôde ser lida. A cobrança fica `PROCESSING`, sem código de barras — mas o banco pode ter registrado o boleto mesmo assim, e o pagador pode encontrá-lo no app do banco dele.	Fale com o suporte antes de criar a cobrança de novo, para o pagador não ser cobrado duas vezes.

Quando o banco recusa o boleto (um 4xx), a cobrança também fica PROCESSING; criá-la de novo é seguro. A página de referência de cada endpoint lista todos os erros que ele pode retornar.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Fluxo

Etapa 1: Criar a cobrança

Etapa 2: Compartilhar o boleto

Etapa 3: Saber quando foi pago

Desconto, multa e juros

Erros

Próximos passos

Cobrar com PIX

Cobrança recorrente com PIX Automático

​Fluxo

​Etapa 1: Criar a cobrança

​Etapa 2: Compartilhar o boleto

​Etapa 3: Saber quando foi pago

​Desconto, multa e juros

​Erros

​Próximos passos

Cobrar com PIX

Cobrança recorrente com PIX Automático

Fluxo

Etapa 1: Criar a cobrança

Etapa 2: Compartilhar o boleto

Etapa 3: Saber quando foi pago

Desconto, multa e juros

Erros

Próximos passos