Bank slips
The Bank slips feature enables payments of different kinds of bills, such as utilities, taxes, rent, and so on. Boleto is a common method of cash payment in Brazil. It is a bank voucher (printed or virtual) that can be paid in various financial institutions.
The client can validate and pay a bill by scanning a barcode (if that technology is available) or by typing the digitable line (the numbers that represent the barcode information). Pismo will connect with the charge holder and return to the client the confirmation about the payment or the error message, in case it is impossible to finish the payment.
There are two types of boleto: Boleto de Concessionária and Boleto Bancário.
- Boletos de Concessionárias are usually known as “consumer bills.” The most popular are electricity bills, water bills, gas bills, etc. They are separated into four fields and the last number of the sequence is isolated.
Example:
12345678912-3 12345678912-3 12345678912-3 12345678912-3 - Boletos Bancários are the slips generated by banking institutions and they are separated into five fields that should be filled for the payment to happen. Example:
123 4 56789 1 123456 7891 2 1234567891 2 123456789123456
The fields for both types of boleto usually have between 44 and 48 digits.
Payment flow
On the Pismo platform, paying a boleto consists of three steps: validation, payment, and proof of payment (receipt):
Step | Description |
---|---|
Validation | The customer submits the boleto for payment using an app to scan a QR code or by entering the barcode manually. Pismo transmits the data to the payer’s banking provider to get information about the bill and return it to the client. This information includes the amount of the bill and to whom the client is paying. If the validation does not succeed, the provider returns the information to Pismo, who sends it to the client and a new validation request must be performed. |
Payment | Pismo calls the payment provider to execute the payment and settle the transaction. Provider notifies Pismo that the payment is settled. Pismo sends confirmation to the client. If the boleto is not settled, the provider notifies Pismo of the canceled payment. Pismo forwards this message to the customer. In this case, the transaction is canceled and a new payment request must be performed. |
Proof of payment (receipt) | When a payer requests a payment receipt through an app, Pismo forwards the request to the provider, who then generates the receipt. Pismo then forwards the receipt information to the customer. |
Endpoints
HTTP | Endpoint | Type |
---|---|---|
POST | https://developers.pismo.io/pismo-docs/reference/post-integrated-payments-api-v1-bankslips-validate | Validate the bank slip |
POST | https://developers.pismo.io/pismo-docs/reference/post-integrated-payments-api-v1-bankslips-pay | Pay bank slips |
GET | https://developers.pismo.io/pismo-docs/reference/get-integrated-payments-api-v1-bankslips-receipts | Retrieve proof of payment (receipt) |
Triggered SNS Events
The following event is posted whenever a transaction is successfully completed:
Financial transaction status changed
Payment Slips | PAID | Payment confirmed by provider |
---|---|---|
ERROR | Request error | |
REVERTED | Payment reverted by the provider due to an error in the beneficiary account |
How to use the endpoints
1. Validate the barcode or digitable line
Validate the barcode or digitable line before confirming the payment.
POST /v1/bankslips/validate
The following shows a sample of a request to validate the digitable line:
Payload:
{
"type": 1,
"digitable_line": "20890001091000001090980008176705191030000002000"
}
Response:
{
"assignor": "BANCO BTG PACTUAL S/A ",
"digitable_line": "20890001091000001090980008176705191030000002000",
"bar_code": "",
"external_authorization": "",
"type": 1,
"beneficiary_document_number": "30306294000145",
"beneficiary_name": "BTG PACTUAL SA",
"payer_document_number": "14737229776",
"payer_name": "Davi Ferreira de Sousa",
"due_date": "2022-09-09T00:00:00Z",
"limit_date": "2022-09-11T00:00:00Z",
"settle_date": "2022-09-09T00:00:00Z",
"max_value": 20,
"min_value": 20,
"discount_value": 0,
"interest_value": 1.31,
"fine_value": 2,
"original_value": 20,
"amount": 23.31
}
2. Pay the bill
After validating the bank slip, execute the payment.
POST/integrated-payments/v1/bankslips/pay
The following shows a sample of a request to pay the bank slip:
Payload:
{
“account_id”: {{sourceAccountID}},
“amount”: 20.00,
“bankslip”: {
“original_amount”: 20.00,
“type”: 1,
“digitable_line”: 20890001091000001090980008176705191030000002000”,
“due_datetime”: “2022-09-26T00:00:00Z”
}
}
Response:
{
“account_id”: 12434,
“amount”: 20.00,
“authorization_id”: 12434,
“bar_code”: “22323423423423423”,
“customer_name”: “Customer Name”,
“digitable_line”: 20890001091000001090980008176705191030000002000”,
“due_datetime”: “2022-09-26T00:00:00Z”,
“external_id”: “124234”,
“payment_datetime”: “202-05-25T00:00:00Z”,
“status”: “PROCESSING”
}
3. Get a payment receipt
After you have paid, get proof of payment.
GET/integrated-payments/v1/bankslips/receipts
The following shows a sample of a request to get the receipt:
Payload:
curl - - request GET
- - url <https://api-sandbox.pismolabs.io/integrated-payments/v1/bankslips/receipts>
- - header ‘accept: application/json’
Response:
{
"authorization_id": 49475666,
"account_id": 110702467,
"customer_name": "Davi Ferreira de Sousa",
"beneficiary_name": "BTG PACTUAL SA",
"description": "Boleto integral",
"amount": 20,
"discount": 0,
"interest": 1.37,
"status": "ERROR",
"payment_datetime": "2023-02-10T17:50:04.267862Z",
"due_datetime": "2022-09-26T00:00:00Z"
}
Sequence Diagram
Updated about 2 months ago