Creating Bill Payment

Introduction

This is used to issue and manage boletos (Brazilian bank slips) through the TraceFinance banking gateway.

How to Create a Bill Payment

To create a boleto, you need to call the Create review endpoint:

curl --location --request POST 'https://faas.sandbox.tracefinance.io/boleto/api/boletos' \
  --header 'Content-Type: application/json' \
  --header 'authorization: Bearer {accessToken}' \
  --data '{
    "amount": {
      "value": {amount},
      "currency": "BRL"
    },
    "type": "DM",
    "dueDate": "{dueDate}",
    "payer": {
      "name": "{payerName}",
      "taxId": "{taxId}",
      "address": {
        "street": "{street}",
        "number": "{number}",
        "district": "{district}",
        "city": "{city}",
        "state": "{state}",
        "zipCode": "{zipCode}"
      }
    }
}
'

Parameters:

{amount}: The boleto amount in cents (e.g., 10000 for R$100.00).
{dueDate}: The payment due date in YYYY-MM-DD format.
{taxId}: The payer's tax ID, which can be either CPF (11 digits) or CNPJ (14 digits).
{payerName}: The payer's full name.
{street}, {number}, {district}, {city}, {state}, {zipCode}: The payer's address. State must be 2 characters (e.g., SP) and zipCode must be 8 digits with no dashes.

Optional fields:

{interest}: Penalty charge applied after due date (percentage and daysAfterDueDate).
{fine}: Fine applied after due date (percentage and daysAfterDueDate).
{discounts}: Array of early payment discounts (deadlineDate and percentage).

Resulting Status:

The endpoint will respond with a status code of 201 with the response below:

{
   "data":{
      "bankAccountId":"019540f6-a870-7927-b97b-cdbbeb13f390",
      "id":"123e4567-e89b-12d3-a456-426614174000",
      "companyId":"company_789",
      "amount":{
         "value":10000,
         "currency":"BRL"
      },
      "type":"DM",
      "barCode":"34191090010000000001234567890123456789",
      "line":"34191.09001 00000.000012 34567.890123 4 09001000000000",
      "ourNumber":"00001649435",
      "referenceNumber":"REF-123456",
      "payer":{
         "name":"John Doe",
         "taxId":"12345678901",
         "address":{
            "street":"Av. Paulista",
            "number":"1000",
            "district":"Bela Vista",
            "city":"São Paulo",
            "state":"SP",
            "zipCode":"01310000"
         }
      },
      "dueDate":"2025-08-29",
      "states":[
         {
            "status":"CREATED",
            "reason":null,
            "atTime":"2025-08-01T10:00:00Z"
         }
      ],
      "currentState":{
         "status":"CREATED",
         "reason":null,
         "atTime":"2025-08-01T10:00:00Z"
      },
      "amountPaid":null,
      "paidAt":null,
      "createdAt":"2025-08-01T10:00:00Z",
      "updatedAt":"2025-08-01T10:00:00Z"
   }
}

Webhooks are sent for every status change step.

Webhooks

The BOLETO_CREATED webhook is triggered when a boleto is created.
The BOLETO_PAID webhook is triggered when a boleto is paid.
The BOLETO_EXPIRED webhook is triggered when a boleto expires.
The BOLETO_DELETED webhook is triggered when a boleto is deleted.

Sandbox Environment

In the sandbox environment, the boleto status after creation is determined by the last digit of the amount.value field:

If the last digit is 2, the boleto will change to PAID after creation (e.g., amount.value: 15072).
If the last digit is 3, the boleto will change to EXPIRED after creation (e.g., amount.value: 15073).
Any other last digit, the boleto will stay as CREATED (e.g., amount.value: 15075).

Please note that the status change may have a delay between the boleto creation and the status update routine.

The corresponding webhook events will also be triggered.