This page explains how to add Boleto Bancário to your existing Web Components integration.
The 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 (voucher) and presents the shopper with options to download the Boleto (voucher) or copy the barcode number.Requirements
Select the server-side flow that your integration uses:
Requirement | Description |
---|---|
Integration type | Make sure that you have built a Sessions flow Web Components integration. |
Setup steps | Before you begin, add Boleto Bancário in your Customer Area. |
Import resources for v6
If you are using Web Components v6, import the Component that you need for Boleto Bancário:
import { AdyenCheckout, Boleto } from '@adyen/adyen-web'
API reference
Select which endpoint you are using:
This is the default with Components v5.0.0 or later.
Parameter name | Required | Description |
---|---|---|
shopperName | The shopper's first name and last name. | |
socialSecurityNumber | The shopper's Cadastro de Pessoas Físicas (CPF) number or their Cadastro Nacional da Pessoa Jurídica (CNPJ) number. | |
billingAddress | The postal address of the shopper. Recommended to increase conversion rates. | |
deliverAt Checkout API v68 or later |
The due date of the payment, using ISO 8601 format in UTC. If this is on a weekend or national holiday, the shopper can pay the Boleto the next working day. Do not accept payments after the due date. By default, the shopper has five days to complete the payment. Wait at least five days after the due date to cancel the payment, because the confirmation can take some time to arrive. |
|
shopperEmail | The shopper's email address. This is used for sending the shopper a copy of the payment form. | |
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. |
curl https://checkout-test.adyen.com/v69/sessions \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "amount":{ "value":1000, "currency":"BRL" }, "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy..", "reference":"YOUR_ORDER_NUMBER", "countryCode":"BR", "shopperName":{ "firstName":"José", "lastName":"Silva" }, "billingAddress":{ "city":"São Paulo", "country":"BR", "houseNumberOrName":"952", "postalCode":"04386040", "stateOrProvince":"SP", "street":"Rua Funcionarios" }, "socialSecurityNumber":"56861752509", "deliverAt":"2021-10-07T23:00:00.000Z", "shopperStatement":"Aceitar o pagamento até 15 dias após o vencimento. Não cobrar juros. Não aceitar o pagamento com cheque." }'
Component configuration
Step 1: Create a DOM element
Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered:
<div id="boletobancario-container"></div>
Step 2: Create an instance of the Component
v6.0.0 or later
Create an instance of the Component, passing:
- Your instance of
AdyenCheckout
.
const boletoBancario = new Boleto(checkout).mount('#boletobancario-container');
Optional configuration
You can add the following optional configuration for collecting the shopper details:
- 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, turn on the corresponding form sections.
Parameter name | Description | Default |
---|---|---|
personalDetailsRequired |
Set 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 |
If you want to add optional configuration, include this in a configuration object. The following example shows how to configure the Component to remove the shopper details fields and prefill the form.
const boletoBancarioConfiguration = { personalDetailsRequired: false, //turn personalDetails section on/off billingAddressRequired: false, // turn billingAddress section on/off showEmailAddress: false, // allow shopper to specify their email address // Optionally pre-fill some fields, here all fields are filled: data: { firstName: 'José', lastName: 'Silva', billingAddress: { city: 'São Paulo', country: `BR` houseNumberOrName: '952', postalCode: '04386040', stateOrProvince: 'SP', street: 'Rua Funcionarios', }, socialSecurityNumber: '56861752509', shopperEmail: 'joses@test.com' };
v6.0.0 or later
Create an instance of the Component, passing:
- Your instance of
AdyenCheckout
. - The payment method-specific configuration.
const boletoBancario = new Boleto(checkout, boletoBancarioConfiguration).mount('#boletobancario-container');
Use the create
method of your AdyenCheckout
instance, in this case checkout
, to create an instance of the Component. Add the configuration object if you created one.
const boletoBancarioComponent = checkout.create('boletobancario', boletoBancarioConfiguration).mount('#boletobancario-container');
Set up webhooks
With Boleto, the shopper can pay more or less than the original amount. Set up standard webhooks to make sure that you know the amount that the shopper paid.
Test and go live
Boleto Bancário is an offline payment method.
In the test environment, you can simulate a Boleto payment by promoting the pending payment to a sale.
- Log in to your test Customer Area.
- Go to Transactions > Offers.
- Select the PSP reference of the pending Boleto payment.
- Select the Promote this offer to a sale button.
Check the status of Boleto Bancário 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 Bancário payments, you need to submit a request for Boleto Bancário in your live Customer Area.