Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Boleto Bancário Drop-in integration

Add Boleto Bancário to an existing Drop-in integration.

Our Web Drop-in renders Boleto Bancário in your payment form, collects the shopper details, and presents the shopper with options to download the Boleto (voucher) 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 number.

Before you begin

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

Before starting your Boleto Bancário integration:

  1. Make sure that you have set up your back end implementation, and added Drop-in to your payments form.
  2. Add Boleto Bancário in your test Customer Area.

Show Boleto Bancário in your payment form

Drop-in uses the countryCode and the amount.currency from your /paymentMethods request to show the available payment methods to your shopper.

To show Boleto Bancário in your payment form, specify in your /paymentMethods request:

Optional Drop-in configuration

When creating an instance of Drop-in, you can also include 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, you turn on the corresponding form sections.
Configuration object Description
personalDetailsRequired Set this to true to collect 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.

billingAddressRequired Set this to true to collect the shopper's street, house number or name, city, postal code, and state or province.
showEmailAddress Set this to true to allow the shopper to add or edit their email address when they select the check box to receive a copy of the form.
data Object to pre-fill shopper details on the form: socialSecurityNumber, shopperName, billingAddress, and shopperEmail as shown in the example below.

const dropin = checkout
    .create('dropin', {
        paymentMethodsConfiguration: {
            boletobancario: { // Optional configuration for Boleto
            personalDetailsRequired: true, //turn personalDetails section on/off
            billingAddressRequired: true, // turn billingAddress section on/off
            showEmailAddress: true, // allow shopper to specify their email address

            // Optionally pre-fill some fields, here all fields are filled:
            data: {
                socialSecurityNumber: '56861752509',
                shopperName: {
                    firstName: 'José',
                    lastName: 'Silva'
                },
                billingAddress: {
                    street: 'Rua Funcionarios',
                    houseNumberOrName: '952',
                    city: 'São Paulo',
                    postalCode: '04386040',
                    stateOrProvince: 'SP',
                    country: `BR`
                },
                shopperEmail: 'joses@adyen.nl'
            },
        },
    }
    ...
})
.mount('#dropin');

Make a payment

When the shopper selects to pay, Drop-in calls the onSubmit event, which contains a state.data.

  1. Pass the state.data to your server.

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

    • paymentMethod.type: The state.data.paymentMethod from the onSubmit event from your front end.
    • shopperName: The state.data.shopperName from the onSubmit event.
    • billingAddress: The state.data.billingAddres from the onSubmit event.
    • socialSecurityNumber: The state.data.socialSecurityNumber from the onSubmit event.
    • deliveryDate: The due date of the payment, in UTZ format. If this is in a weekend or national holiday, the shopper can pay the Boleto the next working day.
    • shopperStatement: Free-text field with payment instructions.

      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 it 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/v50/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
  },
  "paymentMethod":{
    "type":"boletobancario"
  },
  "shopperName":{
    "firstName":"José",
    "lastName":"Silva"
  },
  "billingAddress":{
    "city":"São Paulo",
    "country":"BR",
    "houseNumberOrName":"952",
    "postalCode":"04386040",
    "stateOrProvince":"SP",
    "street":"Rua Funcionarios"
  },
  "socialSecurityNumber":"56861752509",
  "deliveryDate":"2019-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.

{
    "additionalData": {
        "merchantReference": "Boleto test"
    },
    "pspReference": "881571921030827A",
    "resultCode": "PresentToShopper",
    "action": {
        "downloadUrl": "https://test.adyen.com/hpp/generationBoleto.shtml?data=BQABAQBB0vEoZpSKNnPAIVgxKpE2cUUz%2B3DOieJSxZ7Lfb2QUZRUuxqDng0gKXXc31JlxEeqnQG8Jic8ilFc4gHHvr6govsYljqI8E0uHZL0RcgRBJEMRDuwaZpmKH9DyKSU8Y6%2BKNfYV9WhiffEzabR63prjkyetATRCfVLpKQDSPX8MzJsiRpPbJw28GcjZRd4gy3vs3IZcHKu621r%2FKeggGLrO9HJJWTQufeJKn%2Bu1tt1l7VWkSkD9VVbUKZwoMXTbM7q3e0lIcBNZz%2BNGPn%2BZIfRH6r9G4spp2UgIJzQDPkLA%2FscRtEe3YscOXSupVVvqFWmrzS0VCi4eHb3C%2FN9QfEKED5ihB8KuWlvGjrECloQg6UAAAAYf6Nis559XV4dUlUgmKAAAcF8bWZAa%2FzLoQWmkblFa5p7ih%2F%2F%2FNTTcfA68aeCdJ8AVACSpsmOMSpfYpF1CfBmUwpAeaLBn6CI%2B4HTrvUl%2FYesEIOil3irbbPPKBvjaF12S2RwS9iPajgxsBEp1LpolRsocatyW49bN5I1Z9MxO4Dv2pzd0yzhi6fgz%2B7j9JZLd2wmy7gZQ1AzU%2FV0oTXT71Q%2F%2BmO6K8ibcjM7FUPcYpTY6PyxgA2%2F2ORYT4ebqkEFi6hWA5XhrJSfymtEah5824DczR0cFUiMXsnZjdkBIjnufdTtxsLKIwpMtvSIVcfnSGZbI1XMgQ%3D%3D",
        "expiresAt": "2019-10-30T00:00:00",
        "initialAmount": {
            "currency": "BRL",
            "value": 1000
        },
        "paymentMethodType": "boletobancario",
        "reference": "03399.33335 33887.192103 30827.201028 9 80580000001000",
        "totalAmount": {
            "currency": "BRL",
            "value": 1000
        },
        "type": "voucher"
    },
    "outputDetails": {
        "boletobancario.data": "BQABAQBB0vEoZpSKNnPAIVgxKpE2cUUz+3DOieJSxZ7Lfb2QUZRUuxqDng0gKXXc31JlxEeqnQG8Jic8ilFc4gHHvr6govsYljqI8E0uHZL0RcgRBJEMRDuwaZpmKH9DyKSU8Y6+KNfYV9WhiffEzabR63prjkyetATRCfVLpKQDSPX8MzJsiRpPbJw28GcjZRd4gy3vs3IZcHKu621r/KeggGLrO9HJJWTQufeJKn+u1tt1l7VWkSkD9VVbUKZwoMXTbM7q3e0lIcBNZz+NGPn+ZIfRH6r9G4spp2UgIJzQDPkLA/scRtEe3YscOXSupVVvqFWmrzS0VCi4eHb3C/N9QfEKED5ihB8KuWlvGjrECloQg6UAAAAYf6Nis559XV4dUlUgmKAAAcF8bWZAa/zLoQWmkblFa5p7ih///NTTcfA68aeCdJ8AVACSpsmOMSpfYpF1CfBmUwpAeaLBn6CI+4HTrvUl/YesEIOil3irbbPPKBvjaF12S2RwS9iPajgxsBEp1LpolRsocatyW49bN5I1Z9MxO4Dv2pzd0yzhi6fgz+7j9JZLd2wmy7gZQ1AzU/V0oTXT71Q/+mO6K8ibcjM7FUPcYpTY6PyxgA2/2ORYT4ebqkEFi6hWA5XhrJSfymtEah5824DczR0cFUiMXsnZjdkBIjnufdTtxsLKIwpMtvSIVcfnSGZbI1XMgQ==",
        "boletobancario.dueDate": "2019-10-30",
        "boletobancario.barCodeReference": "03399.33335 33887.192103 30827.201028 9 80580000001000",
        "boletobancario.url": "https://test.adyen.com/hpp/generationBoleto.shtml?data=BQABAQBB0vEoZpSKNnPAIVgxKpE2cUUz%2B3DOieJSxZ7Lfb2QUZRUuxqDng0gKXXc31JlxEeqnQG8Jic8ilFc4gHHvr6govsYljqI8E0uHZL0RcgRBJEMRDuwaZpmKH9DyKSU8Y6%2BKNfYV9WhiffEzabR63prjkyetATRCfVLpKQDSPX8MzJsiRpPbJw28GcjZRd4gy3vs3IZcHKu621r%2FKeggGLrO9HJJWTQufeJKn%2Bu1tt1l7VWkSkD9VVbUKZwoMXTbM7q3e0lIcBNZz%2BNGPn%2BZIfRH6r9G4spp2UgIJzQDPkLA%2FscRtEe3YscOXSupVVvqFWmrzS0VCi4eHb3C%2FN9QfEKED5ihB8KuWlvGjrECloQg6UAAAAYf6Nis559XV4dUlUgmKAAAcF8bWZAa%2FzLoQWmkblFa5p7ih%2F%2F%2FNTTcfA68aeCdJ8AVACSpsmOMSpfYpF1CfBmUwpAeaLBn6CI%2B4HTrvUl%2FYesEIOil3irbbPPKBvjaF12S2RwS9iPajgxsBEp1LpolRsocatyW49bN5I1Z9MxO4Dv2pzd0yzhi6fgz%2B7j9JZLd2wmy7gZQ1AzU%2FV0oTXT71Q%2F%2BmO6K8ibcjM7FUPcYpTY6PyxgA2%2F2ORYT4ebqkEFi6hWA5XhrJSfymtEah5824DczR0cFUiMXsnZjdkBIjnufdTtxsLKIwpMtvSIVcfnSGZbI1XMgQ%3D%3D",
        "boletobancario.expirationDate": "2019-11-14",
        "requestAmount": "1000",
        "requestCurrency": "BRL",
        "payCode": "03399.33335 33887.192103 30827.201028 9 80580000001000",
        "payLimitDateTime": "2019-10-30T00:00:00"
    }
}

Present the voucher

Web Drop-in presents the voucher to your shopper.

Present the payment result

Use the resultCode that you received in the /payments response to present the payment result to your shopper.

The resultCode values you can receive for Boleto Bancário are:

resultCode Description Action to take
PresentToShopper The response contains additional information that you need to present to the shopper, so that they can use it to complete the payment. Present the voucher to the shopper and inform them that you are waiting for their payment.
You can optionally set up PENDING notifications for Boleto Bancário.
You will receive the final result of the payment in an AUTHORISATION notification.
Cancelled The shopper cancelled the payment. Ask the shopper whether they want to continue with the order, or request that they select a different payment method.

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 TransactionsOffers.
  • 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