Boleto Bancário Component

Our Boleto Bancário Component renders Boleto Bancário in your payment form and collects the shopper details. When the shopper selects to pay, the Component generates the Boleto and returns it to you.

When making a Boleto Bancário payment, you also need to:

• Present the Boleto (voucher) to the shopper, with options to download the Boleto in PDF format or copy the barcode number. The shopper can then print the downloaded Boleto and pay in cash, or pay the Boleto at an ATM or through internet banking using the barcode.

Before you begin

This page explains how to add Boleto Bancário to your existing Web Components integration. The Web Components integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Components integration guide.

Before starting your Boleto Bancário integration:

1. Make sure that you have set up your back end implementation, and created an instance of AdyenCheckout.
2. Add Boleto Bancário in your Customer Area.
   

Show Boleto Bancário in your payment form

To present the Boleto Bancário Component in your payment form:

1. From your server, make a POST /paymentMethods request specifying:
   • countryCode: BR
   • amount.currency: BRL

2. Pass the full response from the /paymentMethods call as the paymentMethodsResponse object when creating an instance of the AdyenCheckout.

3. Add the Boleto Bancário Component:

   a. Create a DOM element for Boleto Bancário, placing it where you want the form to be rendered:

   <div id="boleto-container"></div>

   b. Create an instance of the Boleto Bancário Component, and mount it.
   You can also include optional configuration:

   • If you already have the required shopper details, you can turn off the form sections where these details are collected.
   • You can pre-fill some of the fields. To collect the missing details, you turn on the corresponding form sections.

   Configuration object	Description	Default
   personalDetailsRequired	Set this to false if you have already collected the shopper's first name, last name, and CPF/CNPJ (socialSecurityNumber). The CPF/CNPJ is a unique identifier similar to a social security number. The shopper can provide their Cadastro de Pessoas Físicas (CPF) number or their Cadastro Nacional da Pessoa Jurídica (CNPJ) number.	true
   billingAddressRequired	Set this to false if you have already collected the shopper's street, house number or name, city, postal code, and state or province.	true
   showEmailAddress	Set this to false if you have already collected the shopper's email address.	true
   data	Object to pre-fill shopper details on the form: socialSecurityNumber, shopperName, billingAddress, and shopperEmail as shown in the example below.	Empty

   https://docs.adyen.com/payment-methods/boleto-bancario/web-component#example-configuration

   Example configuration

   const boletoInput = checkout
       .create('boletobancario', {
           personalDetailsRequired: true, // turn personalDetails section on/off
           billingAddressRequired: true, // turn billingAddress section on/off
           showEmailAddress: true, // allow shopper to specify their email address
   
           // Optionally prefill some fields, here all fields are filled:
           data: {
               socialSecurityNumber: '56861752509',
               firstName: 'José',
               lastName: 'Silva',
               billingAddress: {
                   street: 'Rua Funcionarios',
                   houseNumberOrName: '952',
                   city: 'São Paulo',
                   postalCode: '04386040',
                   stateOrProvince: 'SP',
                   country: 'BR'
               },
               shopperEmail: 'joses@test.com'
           }
   }).mount('#boleto-container');

Make a payment

When the shopper selects to pay, the Component calls the onChange event, which contains a state.data.

1. If state.isValid is true, collect the state.data and pass this to your server.

2. From your server, make a /payments request, specifying:

   Parameter name	Required	Description
   paymentMethod		The state.data.paymentMethod from the onChange event from your front end.
   shopperName		The state.data.shopperName from the onChange event from your front end.
   billingAddress		The state.data.billingAddres from the onChange event from your front end.
   socialSecurityNumber		The state.data.socialSecurityNumber from the onChange event from your front end.
   deliveryDate		The due date of the payment, using ISO 8601 format in UTC. If this is in a weekend or national holiday, the shopper can pay the Boleto the next working day. By default, the shopper has five days to complete the payment.
   shopperStatement		Free-text field with payment instructions. If you include this, make sure to state that you do not accept payments for a higher or lower amount than the original amount, or payments after the due date.

   If you leave the shopperStatement empty, it is populated with the following default Portuguese text:

   Não aceitar pagamento via cheque e/ou após a data do vencimento.	Do not accept payment by cheque and/or after the due date.
   Seu pedido será enviado somente após a confirmação do pagamento deste boleto, desde que não tenha divergência de valores entre o valor cobrado e o valor pago.	Your order will only be processed once the payment of this Boleto has been confirmed and as long as there is no difference between the payable and paid amounts.
   A falta de pagamento deste boleto não implica em qualquer multa ou juros e o pedido será automaticamente cancelado.	Failure to pay this boleto will not incur any penalty or interest and your order will be automatically cancelled.
   Não deposite nem faça transferência.	Do not pay by deposit or bank transfer.

   https://docs.adyen.com/payment-methods/boleto-bancario/web-component#-payments-request

   /payments request

   curl https://checkout-test.adyen.com/v67/payments \
   -H "x-API-key: YOUR_X-API-KEY" \
   -H "content-type: application/json" \
   -d '{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "reference":"YOUR_ORDER_NUMBER",
   "amount":{
     "currency":"BRL",
     "value":1000
   },
   "{hint:state.data.paymentMethod from onChange or onSubmit}paymentMethod{/hint}":{
     "type":"boletobancario_santander"
   },
   "{hint:state.data.paymentMethod from onChange or onSubmit}shopperName{/hint}":{
     "firstName":"José",
     "lastName":"Silva"
   },
   "{hint:state.data.billingAddress from onChange or onSubmit}billingAddress{/hint}":{
     "city":"São Paulo",
     "country":"BR",
     "houseNumberOrName":"952",
     "postalCode":"04386040",
     "stateOrProvince":"SP",
     "street":"Rua Funcionarios"
   },
   "{hint:state.data.socialSecurityNumber from onChange or onSubmit}socialSecurityNumber{/hint}":"56861752509",
   "deliveryDate":"2021-11-07T23:00:00.000Z",
   "shopperStatement":"Aceitar o pagamento até 15 dias após o vencimento.\nNão cobrar juros. Não aceitar o pagamento com cheque"
   }'

   The /payments response with action.type voucher contains:

   • pspReference: Our unique reference for the payment.
   • resultCode: PresentToShopper

   • action: Object containing information about the voucher :

     • downloadUrl: Link to the downloadable Boleto in PDF format.
     • expiresAt: The date and time when the due date expires.
     • paymentMethodType: Indicates the issuing bank.
     • reference: The barcode number for the payment.

     • totalAmount: The currency and value of the amount due.

   https://docs.adyen.com/payment-methods/boleto-bancario/web-component#-payments-response

   /payments response

   {
       "pspReference": "881571921030827A",
       "resultCode": "PresentToShopper",
       "action": {
           "downloadUrl": "https://test.adyen.com/hpp/generationBoleto.shtml?data=BQABA...",
           "expiresAt": "2019-10-30T00:00:00",
           "initialAmount": {
               "currency": "BRL",
               "value": 1000
           },
           "paymentMethodType": "boletobancario_santander",
           "reference": "03399.33335 33887.192103 30827.201028 9 80580000001000",
           "totalAmount": {
               "currency": "BRL",
               "value": 1000
           },
           "type": "voucher"
       },
       ...
       }
   }
3. Pass the action object to your front end.

Present the voucher

Call createFromAction and pass the action object from the previous step. This will return a new Component that you need to mount:

// optionally unmount the input section
boletoInput.unmount();
checkout.createFromAction(action).mount('#my-container');

The Component presents the voucher to the shopper.

The shopper can either copy the barcode number or download the voucher file. They can then print the downloaded Boleto and pay in cash, or pay the Boleto at an ATM or through internet banking using the barcode number.

Present the payment result

Use the resultCode that you received in the /payments response to inform your shopper of the payment status. You receive payment updates and results through a notification webhook.

The resultCode value you can receive for Boleto Bancário is:

Test and go live

Boleto is an offline payment method. To be able to test this, make sure you have the following user roles in your test Customer Area:

• Merchant view offers: This allows you to see Boleto offers that are in the "Pending" state.
• Promote offers to sale (test): This allows you to promote a Boleto offer from "Pending" to "Authorised." In this way you can test what happens when we process the payment. This permission is only available in TEST.

Check the status of Boleto test payments in your Customer Area:

• Boletos that are pending or that have expired, are under Transactions > Offers.
• Boletos that have been paid (including test offers that you manually promoted to sale), are under Transactions > Payments.

Test the reconciliation process by promoting test payments from offer to sale in your test Customer Area.

Before you can accept live Boleto payments, you need to submit a request for Boleto Bancário in your live Customer Area.

See also