Pagar um boleto

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.

Fluxo

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.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto' \
  -H 'Authorization: Bearer <accessToken>' \
  -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.
`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:

{
  "_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).

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

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:

curl -X PUT \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -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

Etapa 3: Confirmar o pagamento

Quando policy.actions.autoAction for APPROVE, confirme o pagamento — sem corpo:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -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 em vez de confirmá-lo. Com DENY, as políticas o recusam. Referência: Confirmar um pagamento de boleto

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. Cancelar um pagamento agendado também cancela o agendamento dele:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}/cancel' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

Erros comuns

Os erros vêm no envelope de erro, 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.
`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 para ver o status dele, ou liste os pagamentos de boleto de uma carteira — filtre por status, por exemplo ?status=PAID,FAILED. Para ser notificado, assine o webhook BANK_SLIP_PAID, enviado quando um boleto é pago a partir de uma carteira.

Próximos passos

Políticas de negócio e aprovações

Envie pagamentos para aprovação quando as políticas da sua organização exigirem.

Enviar um pagamento Pix

Pague por chave Pix, QR Code ou dados bancários.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Fluxo

Etapa 1: Criar o pagamento

Etapa 2: Definir os detalhes, se faltar algum

Etapa 3: Confirmar o pagamento

Pagar em um dia futuro

Cancelar um pagamento

Erros comuns

Acompanhar um pagamento

Próximos passos

Políticas de negócio e aprovações

Enviar um pagamento Pix

​Fluxo

​Etapa 1: Criar o pagamento

​Etapa 2: Definir os detalhes, se faltar algum

​Etapa 3: Confirmar o pagamento

​Pagar em um dia futuro

​Cancelar um pagamento

​Erros comuns

​Acompanhar um pagamento

​Próximos passos

Políticas de negócio e aprovações

Enviar um pagamento Pix

Fluxo

Etapa 1: Criar o pagamento

Etapa 2: Definir os detalhes, se faltar algum

Etapa 3: Confirmar o pagamento

Pagar em um dia futuro

Cancelar um pagamento

Erros comuns

Acompanhar um pagamento

Próximos passos