⌘K

Pagar por Código do Boleto

Inicie o pagamento de um boleto informando o código do boleto (linha digitável ou código de barras), indicado para boletos previamente consultados.

Fluxo recomendado: consulte o boleto via POST /billets/info para obter o valor atualizado (totalUpdated) e validar os dados do beneficiário, e então pague via POST /billets/pay usando o mesmo billetCode.

A API retorna erro 422 quando o boleto está vencido ou quando a requisição é feita fora do horário limite de liquidação diária.

O valor liquidado é sempre o valor atualizado do boleto, incluindo juros e multas calculados na data de liquidação.

POST/api/v2/billets/pay

Inicia o pagamento de um boleto a partir do código do boleto. Requer o escopo billets.write e o header x-idempotency-key.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo do conteúdo da requisição
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2 (escopo billets.write)
`x-idempotency-key`	billet-req-id-001	Obrigatório. Chave única alfanumérica (1 a 50 caracteres, [a-zA-Z0-9]) para evitar pagamentos duplicados.

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`billetCode`	string	Obrigatorio	Linha digitável ou código de barras do boleto, apenas números, com até 50 caracteres. Use o mesmo código consultado em /billets/info.
`description`	string	Obrigatorio	Descrição do pagamento.
`paymentFlow`	string	Opcional	"INSTANT" (padrão, processa imediatamente) ou "APPROVAL_REQUIRED" (retém o pagamento para aprovação manual no painel).
`payment`	object	Opcional	Objeto com currency ("BRL") e amount (valor em reais com decimais). Ex: { "currency": "BRL", "amount": 150.75 }
`payment.currency`	string	Opcional	Moeda do pagamento. Sempre "BRL".
`payment.amount`	number	Opcional	Valor em reais com decimais. Ex: 150.75 = R$ 150,75.

Exemplo de Request

{
  "billetCode": "00190000090267490000732810452179696530000015075",
  "description": "Pagamento Fornecedor Infra",
  "paymentFlow": "INSTANT",
  "payment": {
    "currency": "BRL",
    "amount": 150.75
  }
}

Exemplo de Response

{
  "id": 776543210,
  "idempotencyKey": "billet-req-id-001",
  "eventDate": "2026-06-12T16: 45:22Z",
  "digitableCode": "00190000090267490000732810452179696530000015075",
  "description": "Pagamento Fornecedor Infra",
  "paymentFlow": "INSTANT",
  "status": "ON_QUEUE",
  "transactionType": "BILLET",
  "creditDebitType": "DEBIT",
  "payment": {
    "currency": "BRL",
    "amount": 150.75
  }
}

Exemplos de Codigo

curl -X POST https://pagamentos.basspago.com.br/api/v2/billets/pay \
  --cert ./client.crt \
  --key ./client.key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-idempotency-key: billet-req-id-001" \
  -d '{
    "billetCode": "00190000090267490000732810452179696530000015075",
    "description": "Pagamento Fornecedor Infra",
    "paymentFlow": "INSTANT",
    "payment": {
      "currency": "BRL",
      "amount": 150.75
    }
  }'

Erros

Os erros seguem o formato RFC 7807 (application/problem+json).

Código	Descrição
`400`	Código do boleto inválido ou requisição malformada.
`401`	Token de acesso inválido ou expirado.
`403`	Sem permissão para executar a operação (escopo billets.write ausente).
`412`	x-idempotency-key já utilizada em outra requisição.
`422`	Boleto vencido ou fora do horário limite de liquidação diária.
`429`	Limite de requisições excedido (rate limit).
`500 / 503 / 504`	Falha técnica no processamento. Tente novamente mais tarde.