Objetivo

A consulta é recomendada como etapa prévia ao pagamento, pois permite validar valor, vencimento, beneficiário e restrições operacionais do boleto.

🔼
POST urlServidor/v1/marketplace/payments/check-billet

Obs: A palavra urlServidor deve ser substituída pela url do servidor.

Parâmetros da Requisição

Nome	Tipo	Obrigatório	Descrição
`integration-key`	string	Sim	Chave de integração.
`x-token`	string	Sim	Token utilizado para autenticação. Pode ser encontrado no portal da API.
`Authorization`	Auth Type Bearer Token	Sim	Inserir o Bearer Token, gerado na rota Auth

Exemplo de header da requisição

curl--request POST \
--location 'urlServidor/v1/marketplace/payments/check-billet' \
--header 'integration-key: your_integration_key' \
--header 'x-token: your_x_token' \
--header 'Authorization: Bearer {{bearer_token}}' \

Modelo da requisição

{
  "barcode": "23793381286000000000000000000000000000000000"
}

{
   "digitable":""
}

Variáveis

Campo	Tipo	Obrigatório	Descrição
`barcode`	string	Não*	Código de barras do boleto.
`digitable`	string	Não*	Linha digitável do boleto.

É necessário informar ao menos um dos campos abaixo:

Modelo response

Detalhe response

Objeto principal

Campo	Tipo	Obrigatório	Descrição
`barcode`	string	Sim	Código de barras do boleto.
`digitable_line`	string	Sim	Linha digitável do boleto.
`expected_on`	date-time	Sim	Data de vencimento do boleto.
`type`	number	Sim	Tipo do boleto.
`amount`	number	Sim	Valor calculado para pagamento.
`nominal_amount`	number	Sim	Valor nominal original do boleto.
`discount`	number	Sim	Valor de desconto aplicado.
`fine`	number	Sim	Valor de multa aplicado.
`interest`	number	Sim	Valor de juros aplicado.
`max_amount`	number	Sim	Valor máximo permitido para pagamento.
`min_amount`	number	Sim	Valor mínimo permitido para pagamento.
`transaction_id`	string	Sim	Identificador da transação de consulta.

Recipient

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do beneficiário.
`document`	string	Sim	Documento do beneficiário.

Payer

Campo	Tipo	Obrigatório	Descrição
`document`	string	Sim	Documento do pagador.
`name`	string	Sim	Nome do pagador.

billet_details

Campo	Tipo	Obrigatório	Descrição
`installments_paid`	number	Sim	Quantidade de parcelas já pagas.
`total_amount_paid`	number	Sim	Valor total já pago.
`document_final_recipient`	string	null	Sim	Documento do destinatário final, quando aplicável.
`final_recipient`	string	null	Sim	Nome do destinatário final, quando aplicável.
`billet_type`	string	Sim	Tipo do boleto consultado.

Observação

A validação do barcode antes da liquidação é uma prática importante em produção.

Ela evita pagamentos com: valor divergente, boleto vencido, beneficiário inesperado, restrições operacionais impostas pelo banco emissor.

Códigos de resposta

Consulte a página com os status: Status de respostas

Para mais detalhes sobre os parâmetros e funcionamento da API, acesse a documentação oficial da Paytime.