Boleto

Updated: Jun 30, 2026

Copy for LLM

The Payments API enables businesses to collect payments in Brazil via WhatsApp using Boleto.

When using this integration, WhatsApp only facilitates the communication between merchants and buyers. Merchants are responsible for integrating with a PSP from which they can generate Boleto codes, and confirm their payment.

Before you start

Familiarize yourself with the Orders API. Orders are the entrypoint for collecting payments in WhatsApp.

You need an existing integration with a PSP to generate Boleto codes and do automatic reconciliation when a payment is made.

You must update the order status as soon as a payment is made.

Integration steps

The following sequence diagram shows the typical integration with Boleto.

Sequence diagram of Boleto payment flow between PSP or Bank, Merchant, WhatsApp, Buyer, and Buyer's Bank

1. Send an order details message

Follow the full integration guide in the Orders API page.

If Boleto payment is available on this order, you will need to provide a boleto object in the payment_settings attribute. You can optionally include an order object with itemized products, fees, and discounts, or send a simplified message with just the total amount and payment settings.

The following images show how the order details message with Boleto appears in WhatsApp, in both full and simplified versions.

Full order details message with Boleto showing itemized products and Copy Boleto code button

Simplified order details message with Boleto showing total amount and Copy Boleto code button

Endpoint

POST /{PHONE_NUMBER_ID}/messages

Payload example

{
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "order_details",
    "body": {
      "text": "Your message content"
    },
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "reference_id": "unique-reference-id",
        "type": "digital-goods",
        "payment_type": "br",
        "payment_settings": [
          {
            "type": "boleto",
            "boleto": {
              "digitable_line": "03399026944140000002628346101018898510000008848"
            }
          }
        ],
        "currency": "BRL",
        "total_amount": {
          "value": 50000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "tax": {
            "value": 0,
            "offset": 100,
            "description": "optional text"
          },
          "items": [
            {
              "retailer_id": "1234567",
              "name": "Cake",
              "amount": {
                "value": 50000,
                "offset": 100
              },
              "quantity": 1
            }
          ],
          "subtotal": {
            "value": 50000,
            "offset": 100
          }
        }
      }
    }
  }
}

Simplified payload example

You can send a simplified order details message without the order object. The simplified message is useful when you don’t need to send itemized product details and only need to collect the total payment amount.

{
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "order_details",
    "body": {
      "text": "Your message content"
    },
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "reference_id": "unique-reference-id",
        "type": "digital-goods",
        "payment_type": "br",
        "payment_settings": [
          {
            "type": "boleto",
            "boleto": {
              "digitable_line": "03399026944140000002628346101018898510000008848"
            }
          }
        ],
        "currency": "BRL",
        "total_amount": {
          "value": 50000,
          "offset": 100
        }
      }
    }
  }
}

Parameters object

Field Name	Optional?	Type	Description
`payment_settings`	Optional	Payment Settings Object	List of payment related configuration objects.

Payment settings

Field Name	Optional?	Type	Description
`type`	Required	String	Must be `boleto`.
`boleto`	Required	Boleto Object	Boleto object used to render the option to buyers during the checkout flow.

Boleto object

Field Name	Optional?	Type	Description
`digitable_line`	Required	String	The Boleto digitable line that WhatsApp copies to the clipboard when the user taps the Boleto CTA button.

2. Send an order status update

Once your PSP confirms the payment, send an order status update. Follow the integration guide in the Orders API page.