Paying bills and Boletos

📘

Available Providers

Not all Custody Providers support emitting paying bills and boletos, currently BRLD only.

In BT Core, we give the ability for consumers to pay bills and boletos using their account, the flow is basically like this:
First you need to get the boleto informations before paying it. This request gets the barCode sent by you and retrieves informations about this bill or Boleto(the system already checks if it's one or the other and does the correct flow automatically). You can do that using the validate endpoint sending the bar code:

// Validate boleto / bill information and status in the NPC / CIP
const info = await bitcapital.boletos().getPaymentInfo(barCode);
curl --location --request POST 'https://instance-url.btcore.app/boletos/validate?barCode=23794000000000000003391090108000009400076740' \
--header 'Authorization: Bearer 0000000000000000000000000000000000000000'\
--header 'Content-Type: application/json' \
--header 'X-Request-Signature: 140cf378103cb985a938fa3080401f9eb72524172f1a9725482c74a003d4993b' \
--header 'X-Request-Timestamp: 1578678110828' \
  1. Second you should pay the boleto sending the correct fields like described below.
const me = await bitcapital.users().me();
 const source = me.wallets[0];

// Validate boleto / bill information and status in the NPC / CIP
const info = await bitcapital.boletos().getPaymentInfo(barCode);

const amount = info.type === 1 
  ? info.boletoNPCInfo.totalAmount    // NPC Boleto 
  : info.convenantChargeInfo.amount;  // The amount due for payment

// Perform the Boleto / Bill payment using the current user wallet
const transaction = await bitcapital.boletos().pay({ 
  source, 
  barCode, 
  amount 
});
curl --location --request POST 'https://instance-url.btcore.app/boletos/pay' \
--header 'Authorization: Bearer 0000000000000000000000000000000000000000'\
--header 'Content-Type: application/json' \
--header 'X-Request-Signature: 140cf378103cb985a938fa3080401f9eb72524172f1a9725482c74a003d4993b' \
--header 'X-Request-Timestamp: 1578678110828' \
--data-raw '{
  "source": "8b6b6963-b515-46ba-b61f-7ba0829575a2",
  "barCode": "23794000000000000003391090108000009400076740",
  "amount": "12.45",
  "extra": {}
}'

Depending on your custody provider you should expect different results from the API, for example, in BRLD asset, the validate endpoint returns:

{
    "Barcode": "33690000090001001000929652642439182690000002000",
    "Result": {
        "Success": true,
        "BillPaymentTypeId": 1,
        "BillPaymentTypeDescription": "NPC",
        "HasEnoughBalance": true,
        "WasPaid": false,
        "PaymentSchedulingDate": "N/A",
        "ReachedLimit": false,
        "ValidateBarCode": {
            "Id": 0,
            "Description": "",
            "Value": 0,
            "DueDate": "",
            "IsOutTime": false,
            "TimeWindow": 0,
            "MinTime": "",
            "MaxTime": "",
            "IsDefaultTime": false,
            "PaymentType": 0,
            "HasDueDate": false,
            "BarCodeNumber": "",
            "CurrentDate": ""
        },
        "PaymentInfoNPC": {
            "Id": 0,
            "ContractNumber": "2020052501208703658",
            "IdentificationNumber": "2020052501208703658",
            "DueDate": "2020-05-28",
            "BillValue": 20,
            "TaxBreakValue": 0,
            "PaymentLimitDate": "2020-05-29",
            "OpeningPaymentschedule": "07:30h",
            "ClosingPaymentschedule": "20:30h",
            "IsValidDate": true,
            "IsBeforeWindow": false,
            "IsValidWindow": true,
            "NextUtilDay": "20200526",
            "BarCodeNumber": "33690000090000001000929652642439182690000002000",
            "Traders": {
                "Recipient": "BANCO C6 S.A.",
                "RecipientDocument": "31872495000172",
                "PayerName": "JOAO BRITO",
                "PayerDocument": "01234567890"
            },
            "ReceivingDivergentValue": {
                "Code": 3,
                "Description": "Não aceitar pagamento com valor divergente"
            },
            "ReceiptRules": {
                "TypeOfPaymentMin": "",
                "TypeOfPaymentMax": "",
                "MinPaymentValue": 0,
                "MaxPaymentValue": 0
            },
            "ComputedBillValues": {
                "CalculatedInterestAmount": 0,
                "CalculatedFineValue": 0,
                "DiscountValueCalculated": 0,
                "TotalAmountToCharge": 20,
                "PaymentAmountUpdated": 0,
                "ComputedDate": "2020-05-25"
            },
            "BillStatus": {
                "Code": 12,
                "Description": "Boleto encontrado na base centralizada e Cliente Beneficiário apto."
            },
            "Params": {
                "OutOfDate": false,
                "AptoForPayment": true,
                "BlockPaymentOfDate": false
            }
        }
    }
}

If you're using the BRLD integration for paying bills, the amount to be paid may change in case of early payment discount or may even be added to a fine and interest in case of delay. Thus it is recommended to consult the updated value, as shown below.

If you're using the Celcoin(BRLN) integration, you'll see a response like this one:

{
    "assignor": "BANCO BRADESCO S.A.",
    "registerData": {
        "documentRecipient": "02.333.212/0001-76",
        "documentPayer": "012.345.678=90",
        "payDueDate": "2020-06-02T00:00:00",
        "nextBusinessDay": null,
        "dueDateRegister": "2020-04-03T00:00:00",
        "allowChangeValue": false,
        "recipient": "Company LTDA",
        "payer": "ESTEVAM PEREIRA GARCIA",
        "discountValue": 0.0,
        "interestValueCalculated": 0.0,
        "maxValue": 1.0,
        "minValue": 1.0,
        "fineValueCalculated": 0.0,
        "originalValue": 1.0,
        "totalUpdated": 1.0,
        "totalWithDiscount": 0.0,
        "totalWithAdditional": 0.0
    },
    "settleDate": "25/05/2020",
    "dueDate": "2020-04-03T00:00:00Z",
    "endHour": "23:00",
    "initeHour": "07:00",
    "nextSettle": "N",
    "digitable": "23793391009010800006928000767401582140000000100",
    "transactionId": 3760845,
    "type": 2,
    "value": 1.0,
    "maxValue": null,
    "minValue": null,
    "errorCode": "000",
    "message": null,
    "status": 0
}

Here we have a table explaining a little more some of the fields in the validation result:

Field

Description

registerData

Fields that were found in the CIP registry for this Boleto.

registerData.documentRecipient

TaxId of the recipient of the Boleto.

registerData.documentPayer

TaxId of the payer of the Boleto.

registerData.recipient

The recipient's name of the Boleto

registerData.payer

The Boleto's registered payer name.

registerData.allowChangeValue

If true, the Boleto accepts payments of any value

registerData.originalValue

The original value of the Boleto before interests, taxes, and discounts

registerData.discountValue

The discount value of the Boleto

registerData.interestValueCalculated

The interests value calculated

registerData.maxValue

The max value this boleto accepts payments

registerData.minValue

The minimum amount that is accepted in this Boleto.

value

The total amount of the Boleto to be paid.

type

Indicates if this is a Boleto or a Bill Payment

status

The status of this Boleto

As a result of successful payment execution a transaction of type boleto will be created and recorded on the Stellar blockchain and the account balance updated, the transaction should look like this:

{
    "payments": [
        {
            "status": "authorized",
            "type": "boleto",
            "destination": {
                "id": "c6628b29-1a9f-4c42-bedf-9982781fdf6e",
                "root": true,
                "stellar": {
                    "publicKey": "GBUWHPQWFMFSZJS3A3SKRBQRGLD257G3T7EAQGIL5GQIM67ZJKVKXGIN"
                },
                "updatedAt": "2020-03-16T22:34:03.997Z",
                "createdAt": "2020-03-16T22:34:03.997Z"
            },
            "amount": "2",
            "asset": {
                "id": "a767bd7e-79f7-446e-bafe-ab10e4c61bb1",
                "name": "BRL Celcoin",
                "code": "BRLN",
                "root": false,
                "provider": "celcoin-provider",
                "updatedAt": "2020-04-23T17:55:14.453Z",
                "createdAt": "2020-04-23T17:55:14.453Z"
            },
            "scheduleFor": null,
            "updatedAt": "2020-04-23T23:23:26.556Z",
            "createdAt": "2020-04-23T23:23:26.556Z",
            "id": "f347f810-0d59-480c-8a93-be8a6cb0cef2"
        }
    ],
    "source": {
        "id": "df36a3b8-079e-44e0-8714-1c4b4f92e972",
        "stellar": {
            "publicKey": "GCGONO74APLIILAFIPG5NP4DVOVUIIHRT6CIMMOUGZDTTPNCXZ2WSU2Y"
        },
        "updatedAt": "2020-03-16T22:34:04.514Z",
        "createdAt": "2020-03-16T22:34:04.514Z"
    },
    "states": [
        {
            "additionalData": {
                "authorized": [],
                "skipped": [
                    {
                        "provider": "celcoin-provider",
                        "payment": "f347f810-0d59-480c-8a93-be8a6cb0cef2",
                        "asset": "BRLN"
                    }
                ]
            },
            "updatedAt": "2020-04-23T23:23:26.692Z",
            "createdAt": "2020-04-23T23:23:26.692Z",
            "status": "AUTHORIZED",
            "id": "0ee4857f-c566-418c-a864-2d94a9a6ec2f"
        },
        {
            "additionalData": {},
            "updatedAt": "2020-04-23T23:23:26.550Z",
            "createdAt": "2020-04-23T23:23:26.550Z",
            "status": "pending",
            "id": "ee134409-e346-43b0-972b-46ada79127e3"
        }
    ],
    "updatedAt": "2020-04-23T23:23:26.542Z",
    "createdAt": "2020-04-23T23:23:26.542Z",
    "additionalData": {},
    "status": "AUTHORIZED",
    "type": "payment",
    "id": "31dd4035-884c-4875-b14f-722fb478525e"
}

Did this page help you?