> ## 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. # Pagar um boleto > Pague um boleto bancário ou uma conta de consumo a partir de uma carteira: crie o pagamento pelo código de barras, defina os detalhes e confirme-o Pagar um boleto é um fluxo de etapas separadas. Você **cria** o pagamento a partir do código de barras do boleto, o que consulta o boleto no banco e informa quem você está pagando e o valor; **define os detalhes**, se faltar algum; e então o **confirma** — só aí o dinheiro é movimentado. Se as políticas de negócio da sua organização exigirem aprovação para o pagamento, você o **envia para aprovação** em vez de confirmá-lo — veja [Políticas de negócio e aprovações](https://developers.portao3.com.br/pt-BR/guides/policies-and-approvals.md). ## Fluxo ```mermaid theme={null} sequenceDiagram participant You as Você participant P3 as Portão 3 You->>P3: POST .../boleto (criar, com o código de barras) P3->>You: _id, beneficiário, valor, policy — status REQUESTED opt categoria ainda faltando, ou outro valor ou dia You->>P3: PUT .../boleto/{boletoId} P3->>You: detalhes definidos, policy atualizada end You->>P3: POST .../boleto/{boletoId}/confirm P3->>You: status PAID ``` ## Etapa 1: Criar o pagamento Envie a **linha digitável** do boleto (47 dígitos para um boleto bancário, 48 para uma conta de consumo ou guia de tributo) ou o seu **código de barras** (44 dígitos) em `barcode`. Envie só os dígitos; os dígitos verificadores precisam estar corretos. ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' \ -H 'Content-Type: application/json' \ -d '{ "barcode": "34191790011010435100147910201509416260000150000", "category": "FLEX_INTERNATIONAL", "description": "Folders da campanha de novembro" }' ``` | Campo | Observações | | - | - | | `barcode` | A linha digitável ou o código de barras. Obrigatório. | | `amount` | Em centavos. Omita-o para pagar o que o boleto cobra hoje (`txnUpdatedAmount`). | | `category` | A categoria de saldo da carteira a debitar. Com ela, você pode confirmar logo depois de criar. | | `description` | Uma observação guardada com o pagamento. Ela não é enviada ao beneficiário. | | `scheduledAt` | Um dia futuro para pagar (`YYYY-MM-DD`) — veja [Pagar em um dia futuro](#pagar-em-um-dia-futuro). | | `customFields` | Os campos personalizados de transação da sua organização, por `slug`. | O boleto é consultado no banco e o pagamento é criado como `REQUESTED` — nada é pago ainda. Revise quem você está pagando (`payee`, `payeeDocument`) e quanto (`txnUpdatedAmount`) antes de continuar: ```json theme={null} { "_id": "6726b1c2b4d3e80012c9a4a1", "status": "REQUESTED", "type": "GENERIC", "barcode": "34194162600001500001790010104351004791020150", "payee": "Gráfica Aurora Ltda", "payeeDocument": "12345678000195", "issuer": "Itaú Unibanco S.A.", "dueDate": "2026-11-10T00:00:00.000Z", "txnOriginalAmount": 150000, "txnDiscountAmount": 0, "txnFineAmount": 0, "txnInterestAmount": 0, "txnUpdatedAmount": 150000, "pendingConfirmation": { "amount": 150000, "category": "FLEX_INTERNATIONAL", "description": "Folders da campanha de novembro" }, "policy": { "actions": { "autoAction": "APPROVE" } } } ``` Guarde o **`_id`** do pagamento — ele é o `{boletoId}` de todas as próximas etapas. `txnUpdatedAmount` é o valor nominal (`txnOriginalAmount`) com o desconto, a multa e os juros de hoje aplicados. `pendingConfirmation` guarda o que será pago, e `policy`, o que as políticas de negócio da sua organização dizem sobre ele. `type` distingue os dois tipos de boleto: `GENERIC` é um boleto bancário, com vencimento; `UTILITY_BILL` é uma conta de consumo ou guia de tributo (energia, água, telefone, impostos). > [!WARNING] > > Um boleto que já foi pago não pode ser pago de novo: a criação do pagamento responde `422 ALREADY_PAID`, e nada é criado. Referência: [Criar um pagamento de boleto](https://developers.portao3.com.br/api-reference/banking/boleto-payments/create-a-boleto-payment.md) ## Etapa 2: Definir os detalhes, se faltar algum A confirmação paga exatamente o que está em `pendingConfirmation`, então exige o **valor** e a **categoria de saldo**. O valor costuma ser conhecido depois da criação — o que você enviou ou, senão, o que o boleto cobra (`txnUpdatedAmount`, ou o valor de face quando ele é `0`); só um boleto que não informa valor nenhum o deixa de fora. Se o pagamento já tem os dois, pule esta etapa. Caso contrário — ou para pagar outro valor, mudar o dia ou preencher campos personalizados —, defina-os: ```bash theme={null} curl -X PUT \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' \ -H 'Content-Type: application/json' \ -d '{ "amount": 150000, "category": "FLEX_INTERNATIONAL" }' ``` `amount` e `category` são obrigatórios aqui, e o que você envia substitui o que estava armazenado. Um boleto que aceita uma faixa de valores recebe um valor entre `txnMinAmount` e `txnMaxAmount`; o banco verifica o valor quando o pagamento é confirmado. A resposta traz uma `policy` atualizada. Referência: [Definir os detalhes de um pagamento de boleto](https://developers.portao3.com.br/api-reference/banking/boleto-payments/set-a-boleto-payments-details.md) ## Etapa 3: Confirmar o pagamento Quando `policy.actions.autoAction` for `APPROVE`, confirme o pagamento — sem corpo: ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}/confirm' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' ``` Uma confirmação bem-sucedida responde `200` com o pagamento `PAID`: o dinheiro saiu da carteira, e `confirmedAmount` e `confirmedAt` registram isso. Se o banco recusar o pagamento — por saldo insuficiente ou por um limite, por exemplo —, ele passa a `FAILED`, com o motivo em `failReason`, e você recebe o erro. Um pagamento `FAILED` não pode ser tentado de novo: crie outro. Quando `autoAction` for `NONE`, o pagamento precisa de aprovação: [envie-o para aprovação](https://developers.portao3.com.br/pt-BR/guides/policies-and-approvals.md#etapa-3b-enviar-o-pagamento-para-aprovação) em vez de confirmá-lo. Com `DENY`, as políticas o recusam. Referência: [Confirmar um pagamento de boleto](https://developers.portao3.com.br/api-reference/banking/boleto-payments/confirm-a-boleto-payment.md) ## Pagar em um dia futuro Envie `scheduledAt` (`YYYY-MM-DD`) ao criar o pagamento, ou com `PUT`, para pagar em um dia futuro. A confirmação então responde `201` com o agendamento, e o pagamento passa a `SCHEDULED`; nesse dia, um novo pagamento é criado a partir do mesmo código de barras e pago. * Um **boleto bancário** (`GENERIC`) só pode ser agendado para o vencimento — ou, quando o vencimento cai em um fim de semana ou feriado, para o próximo dia útil. Qualquer outro dia futuro é recusado com `422 SCHEDULED_AT_NOT_ALLOWED`, cuja mensagem informa o dia permitido. Um boleto bancário sem vencimento pode ser agendado para qualquer dia útil. * Uma **conta de consumo ou guia de tributo** (`UTILITY_BILL`) pode ser agendada para qualquer dia futuro. * Um dia anterior a hoje é recusado com `422 INVALID_SCHEDULED_AT`. Na criação, com o dia de hoje ou sem `scheduledAt`, o pagamento é feito assim que é confirmado. Com `PUT`, deixar `scheduledAt` de fora mantém o dia já definido; envie o dia de hoje para voltar a pagar assim que for confirmado. * Nesse dia, o novo pagamento é debitado da categoria de saldo de uso geral (`FLEX_INTERNATIONAL`), qualquer que seja a `category` que você definiu, e não leva nenhum dos campos personalizados do pagamento — por isso ele falha se a sua organização tiver um campo personalizado de transação obrigatório. Nesses casos, pague o boleto no próprio dia. * O valor de um pagamento para um dia futuro precisa ser um que o boleto aceite (entre `txnMinAmount` e `txnMaxAmount`, quando ele os informa); senão a confirmação é recusada com `400 INVALID_AMOUNT` e nada é agendado. ## Cancelar um pagamento Um pagamento que ainda não foi pago — `REQUESTED`, aguardando aprovação ou `SCHEDULED` — pode ser [cancelado](https://developers.portao3.com.br/api-reference/banking/boleto-payments/cancel-a-boleto-payment.md). Cancelar um pagamento agendado também cancela o agendamento dele: ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}/cancel' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' ``` ## Erros comuns Os erros vêm no [envelope de erro](https://developers.portao3.com.br/pt-BR.md#erros), com um `code` estável. Quando o banco recusa um boleto, `code` traz o motivo do banco — alguns motivos vêm em minúsculas, com a mensagem `Unknown error`, então baseie sua lógica no `code`, não na mensagem. | Status | `code` | Quando | O que fazer | | - | - | - | - | | `422` | `BAD_REQUEST` | Um campo é inválido — por exemplo, um `barcode` com dígitos verificadores errados. `fields` lista cada um. | Corrija a requisição. | | `422` | `ALREADY_PAID` | O boleto já foi pago. | Não há nada a pagar. | | `422` | `barcode_not_found` | O banco não encontrou nenhum boleto com este código de barras. | Confira o código de barras. | | `422` | `cannot_be_paid_after_expiration_date` | O último dia para pagar o boleto já passou. | Peça um novo boleto ao beneficiário. | | `422` | `SCHEDULED_AT_NOT_ALLOWED` | Um boleto bancário foi agendado para um dia diferente do vencimento. | Use o dia que a mensagem informa, ou pague hoje. | | `422` | `PAYMENT_PARAMETERS_MISSING` | O valor ou a categoria de saldo ainda não foi definido. | Defina-os com `PUT`. | | `422` | `CUSTOM_FIELD_INVALID_VALUE` | O valor de um campo personalizado é inválido, ou um campo obrigatório está vazio. | Corrija-o com `PUT`. | | `403` | `BOLETO_REQUIRES_APPROVAL` | Uma política exige aprovação. | [Envie-o para aprovação](https://developers.portao3.com.br/pt-BR/guides/policies-and-approvals.md#etapa-3b-enviar-o-pagamento-para-aprovação). | | `422` | `INSUFFICIENT_FUNDS` | O saldo da carteira não cobre o valor. O pagamento agora está `FAILED`. | Adicione saldo à carteira e crie outro pagamento. | | `422` | `LIMIT_EXCEEDED` | O pagamento está acima de um limite de transação. O pagamento agora está `FAILED`. | Crie outro pagamento dentro do limite. | | `409` | `INVALID_BANK_SLIP_STATE` | O pagamento já foi pago, agendado ou cancelado, ou falhou. | Consulte o pagamento. | | `500` / `502` / `503` / `504` | `BANKING_PROVIDER_UNAVAILABLE` | O banco não respondeu. | Tente de novo. Se isso aconteceu durante a confirmação, confira o extrato da carteira antes de pagar de novo. | A página de referência de cada endpoint lista todos os erros que ele pode retornar. ## Acompanhar um pagamento [Consulte o pagamento](https://developers.portao3.com.br/api-reference/banking/boleto-payments/get-a-boleto-payment.md) para ver o `status` dele, ou [liste os pagamentos de boleto de uma carteira](https://developers.portao3.com.br/api-reference/banking/boleto-payments/list-a-wallets-boleto-payments.md) — filtre por `status`, por exemplo `?status=PAID,FAILED`. Para ser notificado, assine o [webhook](https://developers.portao3.com.br/pt-BR/guides/webhooks.md) `BANK_SLIP_PAID`, enviado quando um boleto é pago a partir de uma carteira. ## Próximos passos > [card] [Políticas de negócio e aprovações](https://developers.portao3.com.br/pt-BR/guides/policies-and-approvals.md) > > Envie pagamentos para aprovação quando as políticas da sua organização exigirem. > [card] [Enviar um pagamento Pix](https://developers.portao3.com.br/pt-BR/guides/send-pix.md) > > Pague por chave Pix, QR Code ou dados bancários. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.