> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cobrar com boleto > Emita um boleto que cobra um cliente, compartilhe a linha digitável ou o PDF e saiba quando ele foi pago 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 ```mermaid theme={null} sequenceDiagram participant You participant P3 as Portão 3 participant Payer participant Bank You->>P3: POST .../boleto-billing P3->>You: 201 CREATED (digitableLine, barcode) You->>P3: GET .../boleto-billing/{boletoId}/download/pdf You->>Payer: Linha digitável ou PDF Payer->>Bank: Paga Bank->>P3: Pagamento recebido You->>P3: GET .../boleto-billing/{boletoId} (até o status PAID) ``` ## Etapa 1: Criar a cobrança ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto-billing' \ -H 'Authorization: Bearer ' \ -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](#desconto-multa-e-juros). | O banco registra o boleto na hora, então a cobrança volta `CREATED`, com o `digitableLine` e o `barcode`: ```json theme={null} { "_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](https://developers.portao3.com.br/api-reference/banking/boleto-billing/get-a-boleto-charge.md) até ela ficar `CREATED`. Referência: [Criar uma cobrança por boleto](https://developers.portao3.com.br/api-reference/banking/boleto-billing/create-a-boleto-charge.md) ## 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: ```bash theme={null} curl \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto-billing/{boletoId}/download/pdf' \ -H 'Authorization: Bearer ' \ -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](https://developers.portao3.com.br/api-reference/banking/boleto-billing/download-a-boleto-charges-pdf.md) ## Etapa 3: Saber quando foi pago Uma cobrança por boleto não tem webhook. [Consulte a cobrança](https://developers.portao3.com.br/api-reference/banking/boleto-billing/get-a-boleto-charge.md) para acompanhar o `status`, ou [liste as cobranças da carteira](https://developers.portao3.com.br/api-reference/banking/boleto-billing/list-a-wallets-boleto-charges.md) 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](#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%). ```json theme={null} { "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`. | > [!WARNING] > > `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. ## Próximos passos > [card] [Cobrar com PIX](https://developers.portao3.com.br/pt-BR/guides/collect-pix.md) > > Gere um QR Code Pix. > [card] [Cobrança recorrente com PIX Automático](https://developers.portao3.com.br/pt-BR/guides/pix-automatico.md) > > Cobre um cliente todo mês, com o boleto como alternativa. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.