Bills & Payments

Todos os endpoints de bills exigem Authorization: Bearer <token> e o header x-client-id (tenant).

Visão geral

A API de Bills & Payments permite que o seu tenant pague boletos em nome de uma conta e emita/consulte cobranças através do provedor bancário configurado. O gateway resolve o provedor bancário automaticamente a partir da conta operada (accountFrom / accountId / receiver.account) — você não envia nenhum campo de provedor.

A API expõe exatamente cinco endpoints, todos POST:

Endpoint	Finalidade
POST /v1/bills/payBill	Paga um boleto pelo código de barras / linha digitável
POST /v1/bills/checkBill	Consulta os dados de um boleto antes do pagamento
POST /v1/bills/CreateCharge	Cria uma cobrança (emissão de boleto) no provedor
POST /v1/bills/CheckCharge	Consulta uma cobrança já criada pelo transactionId
POST /v1/bills/getChargePDF	Obtém o PDF da cobrança (boleto) pelo transactionId

---

POST /v1/bills/payBill

Paga um boleto existente pelo código de barras / linha digitável, debitando a conta de origem. Se o accountFrom estiver ausente, a requisição é rejeitada com 400 { "message": "Missing accountFrom" }.

Headers:

Header	Valor	Obrigatório
x-client-id	O id do seu tenant — mesmo valor do Client_ID do OAuth (detalhes)	Sim
Authorization	Bearer token	Sim

Request Body:

{
  "accountFrom": "30054029183",
  "cpfcnpj": "11122233344",
  "barCode": {
    "type": "NPC",
    "digitable": "23793.38128 60000.000003 00000.000400 1 84340000010000",
    "barCode": "23791843400000100003381286000000000000000040"
  },
  "billData": {
    "value": 100.00,
    "originalValue": 100.00,
    "valueWithDiscount": 95.00,
    "valueWithAdditional": 102.00
  },
  "dueDate": "2026-03-20",
  "transactionIdAuthorize": 123456,
  "externalNSU": "123456",
  "externalTerminal": "TERM001"
}

Campo	Tipo	Obrigatório	Descrição
accountFrom	string	Sim	Id da conta de origem (a ser debitada). Ausente → 400
cpfcnpj	string	Não	CPF/CNPJ do pagador
barCode.type	string	Não	Tipo do código de barras (ex.: NPC)
barCode.digitable	string	Não	Linha digitável (código de barras formatado)
barCode.barCode	string	Não	Valor numérico do código de barras
billData.value	number	Não	Valor a pagar
billData.originalValue	number	Não	Valor original do boleto
billData.valueWithDiscount	number	Não	Valor com desconto aplicado
billData.valueWithAdditional	number	Não	Valor com multa/juros
dueDate	string	Não	Data de vencimento
transactionIdAuthorize	number	Não	Referência da transação de autorização
externalNSU	string	Não	Referência externa da transação
externalTerminal	string	Não	Id do terminal (POS/ATM)

Response 200 OK:

Em caso de sucesso, o corpo traz message e data (o resultado do pagamento); em caso de falha, { "message": "..." } com o status HTTP correspondente:

{
  "message": null,
  "data": {
    "errorCode": "0",
    "message": "Bill paid successfully",
    "status": 200,
    "transactionId": "7110444"
  }
}

---

POST /v1/bills/checkBill

Retorna os dados de um boleto (cedente, valores, data de vencimento, linha digitável) antes de iniciar o pagamento. O provedor é resolvido a partir de accountFrom ou accountId, quando presentes.

Request Body:

{
  "barCode": {
    "type": "NPC",
    "digitable": "23793.38128 60000.000003 00000.000400 1 84340000010000",
    "barCode": "23791843400000100003381286000000000000000040"
  },
  "externalNSU": "123456",
  "externalTerminal": "TERM001"
}

Campo	Tipo	Obrigatório	Descrição
barCode.type	string	Não	Tipo do código de barras
barCode.digitable	string	Não	Linha digitável
barCode.barCode	string	Não	Valor numérico do código de barras
externalNSU	string	Não	Referência externa da transação
externalTerminal	string	Não	Id do terminal
accountFrom / accountId	string	Não	Usado apenas para resolver o provedor bancário

Response 200 OK:

{
  "assignor": "EMPRESA EXEMPLO LTDA",
  "registerData": {
    "originalValue": "100.00",
    "totalUpdated": "102.00",
    "totalWithDiscount": "95.00",
    "discountValue": "5.00",
    "fineValueCalculated": "1.00",
    "interestValueCalculated": "1.00",
    "payDueDate": "2026-03-20",
    "allowChangeValue": "false"
  },
  "settleDate": "2026-03-20",
  "dueDate": "2026-03-20",
  "digitable": "23793.38128 60000.000003 00000.000400 1 84340000010000",
  "transactionId": "7110444",
  "type": "NPC",
  "value": "100.00",
  "maxValue": "100.00",
  "minValue": "100.00",
  "status": "success",
  "errorCode": "0",
  "message": ""
}

---

POST /v1/bills/CreateCharge

Cria uma cobrança (emissão de boleto) no provedor bancário configurado. O gateway repassa o corpo da requisição como está para a API de cobrança do provedor; o único campo que o próprio gateway lê é a conta recebedora (receiver.account, ou accountFrom / accountId), usada para resolver o provedor.

Request Body:

O payload de criação de cobrança aceito pelo provedor bancário. Ele inclui um objeto receiver cujo account é usado para o roteamento do provedor.

{
  "receiver": {
    "account": "30054029183"
  }
}

Campo	Tipo	Obrigatório	Descrição
receiver.account	string	Não	Conta recebedora; usada para resolver o provedor

Os demais campos são os exigidos pela API de cobrança do provedor bancário subjacente e são repassados sem alteração. Consulte a especificação de cobrança do seu provedor para a lista completa de campos.

Response 200 OK:

Retorna o objeto da cobrança tal como devolvido pelo provedor bancário (data). Os campos são definidos pelo provedor; um transactionId que identifica a cobrança criada é incluído e pode ser usado com CheckCharge / getChargePDF.

{
  "transactionId": "7110444",
  "status": "PENDING"
}

---

POST /v1/bills/CheckCharge

Retorna as informações de uma cobrança já criada, identificada pelo transactionId.

Request Body:

{
  "transactionId": "7110444"
}

Campo	Tipo	Obrigatório	Descrição
transactionId	string	Sim	Identificador da cobrança a consultar
accountId / receiverAccount	string	Não	Usado apenas para resolver o provedor bancário

Response 200 OK:

Retorna o objeto da cobrança tal como devolvido pelo provedor bancário (data).

{
  "transactionId": "7110444",
  "status": "PENDING"
}

---

POST /v1/bills/getChargePDF

Retorna o PDF de uma cobrança (boleto), identificada pelo transactionId.

Request Body:

{
  "transactionId": "7110444"
}

Campo	Tipo	Obrigatório	Descrição
transactionId	string	Sim	Identificador da cobrança cujo PDF será retornado
accountId / receiverAccount	string	Não	Usado apenas para resolver o provedor bancário

Response 200 OK:

Retorna o PDF da cobrança tal como produzido pelo provedor bancário (data).

{
  "transactionId": "7110444",
  "pdf": "JVBERi0xLjQKJeLj...[base64 encoded PDF]"
}

---