Pagamento de contas

Operações de boletos e guias pela conta do parceiro. A disponibilidade depende da habilitação do produto e do liquidante configurado. A lista de convênios de arrecadação é dinâmica; IPVA só está disponível quando o catálogo vigente autoriza o convênio. Este canal não comprova, por si, integração da baixa do contas a pagar.

Autenticação OAuth2 Bearer. Leituras exigem payment:read; comandos exigem payment:write. Conta, instituição e ator vêm da credencial; não informe ator/instituição no corpo. Cada comando POST exige Idempotency-Key de 8 a 180 bytes, conservada em todas as tentativas do mesmo comando. Use chaves diferentes para cotar, confirmar e cancelar.

HTTP	Rota	Escopo
GET	/api/partner/v1/bill-payments/capabilities	payment:read
GET	/api/partner/v1/bill-payments/institutions	payment:read
GET	/api/partner/v1/bill-payments	payment:read
POST	/api/partner/v1/bill-payments/quotes	payment:write
GET	/api/partner/v1/bill-payments/{id}	payment:read
POST	/api/partner/v1/bill-payments/{id}/confirm	payment:write
POST	/api/partner/v1/bill-payments/{id}/cancel	payment:write
GET	/api/partner/v1/bill-payments/{id}/receipt	payment:read

Contrato e estados

POST /quotes recebe account_id (conta do parceiro), barcode (44, 47 ou 48 dígitos) e type opcional: 0 automático,1 guia,2 boleto. payable_id é opcional e só aceita título correspondente à conta/instituição/código. Valores enviados pelo cliente não substituem os autorizados. A cotação responde 201 quando criada ou 200 no replay, com data.id e valores inteiros em centavos BRL.

POST /{id}/confirm recebe amount_cents, inteiro exatamente igual a total_amount_cents da cotação. Uma resposta 202 confirma aceitação do comando assíncrono; consulte o estado até obter desfecho. Não trate 202 como liquidação. A cotação expira em 30 minutos e também está sujeita à janela de pagamento. POST /{id}/cancel recebe corpo vazio; o estado pode impedir o cancelamento.

Cotação indeterminada: 202 com error.code=provider_unconfirmed, operation_id e cabeçalho Location; consulte essa operação. Repetir a mesma chave não cria nova autorização. Catálogo indeterminado: 503 provider_unconfirmed. Boleto já pago: 409 bill_already_paid. Recusa definitiva: 422 provider_rejected.

Comprovante: 200 somente com operação settled e recibo disponível; 409 receipt_pending significa que liquidou e falta o comprovante; 409 not_settled significa que a liquidação ainda não foi comprovada. O status e o recibo devem ser consultados separadamente. Código de barras e documento do beneficiário são mascarados.

Listagem: filtros status, source_account_id e limit (1–100, padrão 50). GET /{id} expõe estado, conta, vínculo com contas a pagar, tipo, valores original/desconto/acréscimo/total, datas, janela, vencimento da cotação, falha pública e transação. GET /{id}/receipt inclui autenticação e conteúdo do comprovante.

Os exemplos da coleção Postman são sintéticos. Não representam homologação bancária. Use somente ambiente e credenciais autorizados.