---
title: "Boleto Bancário for API only"
description: "Add Boleto Bancário to your API-only integration."
url: "https://docs.adyen.com/payment-methods/boleto-bancario/api-only"
source_url: "https://docs.adyen.com/payment-methods/boleto-bancario/api-only.md"
canonical: "https://docs.adyen.com/payment-methods/boleto-bancario/api-only"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Boleto Bancário for API only

Add Boleto Bancário to your API-only integration.

[View source](/payment-methods/boleto-bancario/api-only.md)

You can add Boleto Bancário to your existing integration. The following instructions show only what you must add to your integration specifically for Boleto Bancário.

If an instruction on this page corresponds with a step in the main integration guide, it includes a link to corresponding step of the main integration guide.

## Requirements

| Requirement          | Description                                                                                                                                                                                                                      |   |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| **Integration type** | Make sure that you have an existing [API-only integration](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only).                                                                         |   |
| **Action handling**  | Make sure that your existing integration is set up to [handle the additional action](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#additional-action). `action.type`: **voucher**. |   |
| **Setup steps**      | Before you begin, [add Boleto Bancário in your Customer Area](/payment-methods/add-payment-methods).                                                                                                                             |   |

## How it works

1. The shopper selects Boleto Bancário as the payment method.
2. The shopper enters their details in the [payment form that you build](#build-your-payment-form).
3. When you make the payment request, you [include additional information about the items that the shopper intends to purchase](#additional-parameters-payments).

## Build your payment form

Include Boleto Bancário in the list of available payment methods. Include the following fields to collect information from your shopper in the payment form.

| Fields           | Description                                                                                                                                                                                                                                                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Personal details | First name, last name, and CPF/CNPJ of the shopper. The CPF/CNPJ is a unique identifier similar to a social security number. The shopper can provide their [Cadastro de Pessoas Físicas (CPF)](https://en.wikipedia.org/wiki/CPF_number) number or their [Cadastro Nacional da Pessoa Jurídica (CNPJ)](https://en.wikipedia.org/wiki/CNPJ) number. |
| Billing address  | Shopper street, house number or name, city, postal code, and state or province.                                                                                                                                                                                                                                                                    |
| Shopper email    | The shopper's email address so that you can send them a copy of the form details.                                                                                                                                                                                                                                                                  |

You can [download the logo for Boleto Bancário](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%2Bonly\&version=71#downloading-logos) to use in your form.

## Get Boleto Bancário as an available payment method

When you make the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) to [get available payment methods](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#get-available-payment-methods), specify the following so that Boleto Bancário is included in the response.

| Parameter                                                                                                          | Values  |
| ------------------------------------------------------------------------------------------------------------------ | ------- |
| [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-countryCode)         | **BR**  |
| [amount.currency](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-amount-currency) | **BRL** |

**Example request for available payment methods**

```bash
curl https://checkout-test.adyen.com/v72/paymentMethods \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
-H 'content-type: application/json' \
-X POST
-d '{
   "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
   "countryCode": "BR",
   "amount": {
      "currency": "BRL",
	  "value": 1000
   },
   "shopperLocale": "pt-BR"
}'
```

**Example response with Boleto Bancário available**

```json
{
    "paymentMethods": [
        {
            "name": "Boleto Bancario",
            "type": "boleto"
        }
    ]
}
```

## Add additional parameters to your /payments request

When you [make a payment](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#make-a-payment), add the following additional parameters:

| Parameter                                                                                                              | Required                                                                                    | Description                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| paymentMethod.type                                                                                                     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **boletobancario**                                                                                                                                                                                                                                                 |
| [shopperName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperName)                   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's `firstName` and `lastName`.                                                                                                                                                                                                                          |
| [billingAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-billingAddress)             | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's `city`, `country`, `houseNumberOrName`, `postalCode,stateOrProvince`, and `street`.                                                                                                                                                                  |
| [socialSecurityNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-socialSecurityNumber) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's CPF or CNPJ number.                                                                                                                                                                                                                                  |
| [deliveryDate](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryDate)                 |                                                                                             | The due date of the payment, using [ISO 8601](https://www.w3.org/TR/NOTE-datetime) 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. |
| [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail)                 |                                                                                             | The shopper's email address. This is used for sending the shopper a copy of the payment form.                                                                                                                                                                      |
| [shopperStatement](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-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.                                                                                                                          |

**Example payment request for Boleto Bancário**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H 'x-API-key: ADYEN_API_KEY' \
-H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
-H 'content-type: application/json' \
-X POST
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "otherData": {
      "otherOne": "value"    // rename object and parameter as required, add other parameters as required
      },
  "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy..",
  "merchantAccount":"ADYEN_MERCHANT_ACCOUNT",
  "paramOne":"value1",
  "paramTwo":"value2"
}'
```

The response includes the `action.type`: **voucher**, and the following:

* `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.

**Example response with an additional action**

```json
{
    "pspReference": "881571921030827A",
    "resultCode": "PresentToShopper",
    "action": {
        "downloadUrl": "https://test.adyen.com/hpp/generationBoleto.shtml?data=BQABAQ..",
        "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"
    },
    ...
}
```

## Present the voucher

Use the information in the `action` object in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response to present the voucher to the shopper.

* `action.downloadUrl`: Link to the downloadable Boleto in PDF format.
* `action.expiresAt`: The date and time when the due date expires.
* `action.reference`: The barcode number for the payment.
* `action.totalAmount`: The `currency` and `value` of the amount due.

Make sure that you show an option to download the Boleto, and an option to 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.

## 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 [webhook](/development-resources/webhooks).

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

| resultCode           | Description          | Action to take                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PresentToShopper** | Present the voucher. | After you present the voucher to the shopper, inform the shopper that you are waiting for the payment to be completed. If you set up [PENDING webhooks for Boleto Bancário](/development-resources/webhooks/webhook-types#other-webhooks), you receive a webhook for pending payments. You will receive the final result of the payment in an [AUTHORISATION webhook](/development-resources/webhooks/webhook-types). |

## 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.

1. Log in to your [test Customer Area](https://ca-test.adyen.com/).
2. Go to **Transactions** > **Offers**.
3. Select the **PSP reference** of the pending Boleto payment.
4. Select the **Promote this offer to a sale** button.

Check the status of Boleto Bancário test payments in your [Customer Area](https://ca-test.adyen.com/):

* 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](/payment-methods/add-payment-methods) in your [live Customer Area](https://ca-live.adyen.com/).

## See also

* [API-only integration guide](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only)
