Boleto Bancário is a popular payment method in Brazil, where the majority of the population does not use a credit card. Consumers are presented with a generated voucher containing a barcode, which they can use to pay in several different ways - either taking it to a local store and paying in cash, scanning the barcode at an ATM, or copying the barcode number into their bank's online environment. Learn more.


Markets	`BR`
Processing currencies	`BRL`
Consumer currencies	`BRL`
Settlement currencies	`BRL`
Minimum Amount	0.02 BRL
Maximum Amount	250,000 BRL
Recurring payments	No
Separate captures	No
Timeout	Default: 3 days
Refund Types	Full - Partial
Refund Validity	365 days
Chargeback	No
Sandbox Availability	PPRO provided

Make a Boleto Payment

Request

To make a payment with Boleto, you'll need to provide the following data when you call our Payment Charges API:

Data Field	Required	Description
paymentMethod	Y	BOLETO
paymentDescriptor		A descriptor for the payment.
amount.value	Y	The amount to be paid in the smallest units of the currency used.
amount.currency	Y	The currency used for the payment
consumer.name	Y	The full name of the consumer
consumer.email		The consumer's email address
consumer.country	Y	The country where the consumer is shopping
consumer.taxIdentification	Y	The consumer's Brazilian tax id (CPF format). It has 11 digits, with the last 2 digits being an arithmetic check for validity. When testing, you can use a CPF generator tool to generate valid samples.
consumer.billingAddress	Y	Required fields: street, postal code, city and region
authenticationSettings: SCAN_CODE settings.scanBy		You have the option to specify a custom expiry date by which the consumer must scan the Boleto voucher code.
webhooksUrl		You should include the endpoint url where you want to receive webhooks for updates to the payment charge.

POST /v1/payment-charges

{
    "paymentMethod": "BOLETO",
    "paymentDescriptor": "Your Optional Payment Descriptor",
    "amount": {
        "value": 100,
        "currency": "BRL"
    },
    "consumer": {
        "name": "John Smith",
        "country": "BR",
        "taxIdentification": "014.325.740-43",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "street": "Bela Vista 41",
            "postalCode": "02366-140",
            "city": "São Paulo",
            "region": "SP"
        }
    },
    "authenticationSettings": [
        {
            "type": "SCAN_CODE",
            "settings": {
                "scanBy": "2035-10-30T00:00:00.000Z"
            }
        }
    ]
}

Response

You'll receive one of our standard payment charge responses (see potential responses in the API Reference)

{
  "id": "charge_SFixoMZGlaD7qEwhnIVSL",
  "status": "AUTHENTICATION_PENDING",
  "authenticationMethods": [
    {
      "type": "SCAN_CODE",
      "details": {
        "codeDocument": "url.ppro.com/linktoboletodocument",
        "codePayload": "1231293120391203912039102391",
        "scanBy": "2022-11-03T11:23:47.123Z"
      }
    }
  ]
}

Consumer Authentication

Boleto requires authentication by the consumer, which they do by scanning the voucher barcode or copying the barcode number. Learn more about the SCAN_CODE authentication type in the Payment Authentication guide.

The authenticationMethods array in the response will contain the SCAN_CODE authentication type with the link to the Boleto voucher.

Make sure to present both the PDF linked in the codeDocument field as well as the raw barcode number in the codePayload field - this gives the consumer more options to complete the payment.

Handling the Payment Result

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer validates the Boleto barcode and pays the amount. After this, the charge will transition to the CAPTURED state.

If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED state.

You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED.

Refund

Boleto does not provide native support for refunds. However, PPRO offers a solution to address this limitation through a manual refund process available to its customers. This process involves collaborative efforts between PPRO and its customers, wherein customer information is shared with PPRO. Subsequently, PPRO's CRM team manages the refund process by initiating Bank Transfers to reimburse the end customer.

The "refundDescriptor" field serves the purpose of incorporating the end-user details, including their name, tax identification number (CPF/CNPJ), and pertinent banking information such as account/agency details or a Pix key.

POST /v1/payment-charges/{{paymentChargeId}}/refunds

{
	"amount": 1000,
	"merchantRefundReference": "5c019979-0751-469e-96e0-b67f1d95c577",
	"refundDescriptor": "Name: João Comprador CPF:12345678909 Bank Name: Banco Santander Agency Number: 1234 Account Number: 123456789"
}

📘
Bank Name, Agency Number and Account Number can be replaced by "Pix key".