Boleto Bancário

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.

MarketsBR
Processing currenciesBRL
Consumer currenciesBRL
Settlement currenciesBRL
Minimum Amount0.02 BRL
Maximum Amount250,000 BRL
Recurring paymentsNo
Separate capturesNo
TimeoutDefault: 3 days
Refund TypesFull - Partial
Refund Validity365 days
ChargebackNo
Sandbox AvailabilityPPRO 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 FieldRequiredDescription
paymentMethodYBOLETO
paymentDescriptorA descriptor for the payment.
amount.valueYThe amount to be paid in the smallest units of the currency used.
amount.currencyYThe currency used for the payment
consumer.nameYThe full name of the consumer
consumer.emailThe consumer's email address
consumer.countryYThe country where the consumer is shopping
consumer.taxIdentificationYThe 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.billingAddressYRequired 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.
webhooksUrlYou 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".