Bill payments

The Bill payments 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_v1-bankslips-validate	Validate the bank slip
POST	https://developers.pismo.io/pismo-docs/reference/post_v1-bankslips-pay	Pay bank slips
GET	https://developers.pismo.io/pismo-docs/reference/get_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 endpoint

1. Validate the barcode

Validate the barcode before confirming the payment.

POST /v1/bankslips/validate
The following shows a sample of a request to validate the barcode:

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