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.

MarketsBR
Processing currenciesBRL
Consumer currenciesBRL
Settlement currenciesBRL
Minimum Amount0.02 BRL
Maximum Amount250,000 BRL
Recurring Payment supportNo
Separate Capture supportNo
TimeoutDefault: 5 days
Refund Types- Full
- 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
paymentDescriptorYA 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.emailYThe 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 Payment Descriptor",
    "amount": {
        "value": 1000,
        "currency": "BRL"
    },
    "consumer": {
        "name": "Connor Summer",
        "email": "[email protected]",
        "country": "BR",
        "taxIdentification": "73577725869",
        "billingAddress": {
            "street": "Bela Vista 41",
            "postalCode": "41460031",
            "city": "Sao Paulo",
            "region": "SP"
        }
    },
    "webhooksUrl": "https://webhooks-endpoint",
    "authenticationSettings": [
        {
            "type": "SCAN_CODE",
            "settings": {
                "scanBy": "2022-11-03T11:23:47.123Z"
            }
        }
    ]
}

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.