Send Conversational WhatsApp Pix Payment Template Message

The Conversational API sends a WhatsApp Pix payment template message from a bot or conversational flow. The message carries a payment button that copies a Pix BR Code to the recipient's clipboard. Your payment service provider (PSP) generates the code for each recipient at the moment you send, so the template never stores a code.

Before you send, create a template with a payment button, wait for Meta approval, and make sure Pix Payment is enabled on your account. For details, see WhatsApp Pix Payment Request.

Endpoint and Headers

Send the request to the following endpoint. The base URL is https://whatsapp.useinsider.com. Use this endpoint for conversational or bot sends.

POST https://whatsapp.useinsider.com/v1/conversational/send

Headers

Body Parameters

The body holds one object per recipient. Each object carries the recipient, the template, and the Pix BR Code for that recipient.

Sample Requests

The components array must mirror your approved template's buttons in the same index order. A mismatch is the most common reason a send is rejected.

Payment Button Only

The following example sends a template with a single payment button to one recipient:

curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'x-ins-auth-key: INS.<YOUR_TRANSACTIONAL_API_KEY>' \
--header 'x-ins-namespace: <YOUR_NAMESPACE>' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {
      "phoneNumber": "<RECIPIENT_PHONE_E164>",
      "message": {
        "type": "template",
        "template": {
          "name": "<YOUR_APPROVED_TEMPLATE_NAME>",
          "language": {
            "code": "<TEMPLATE_LANGUAGE_CODE>",
            "policy": "deterministic"
          },
          "components": [
            {
              "type": "button",
              "sub_type": "payment_request",
              "index": "0",
              "parameters": [
                {
                  "type": "action",
                  "action": {
                    "payment_request": {
                      "payment_setting": {
                        "type": "pix_dynamic_code",
                        "pix_dynamic_code": {
                          "code": "<PIX_DYNAMIC_CODE>"
                        }
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}'

Replace the placeholders with your own values:

To send only the payment button, keep a single component block at index "0":

"components": [
  { "type": "button", "sub_type": "payment_request", "index": "0", "parameters": [ ... ] }
]

Payment Button and Quick Reply

Add the quick reply at its own index:

"components": [
  { "type": "button", "sub_type": "payment_request", "index": "0",
    "parameters": [ ... ] },
  { "type": "button", "sub_type": "quick_reply", "index": "1",
    "parameters": [ { "type": "payload", "payload": "1" } ] }
]

Body Variables

If your body contains variables such as {{1}} and {{2}}, add a body component before the buttons:

{ "type": "body", "parameters": [ { "type": "text", "text": "Marina" } ] }

Multiple Recipients

Add one object per recipient to messages, each with its own Pix code:

"messages": [
  { "phoneNumber": "+5511999999999",
    "message": { ... "code": "<CODE_FOR_THIS_RECIPIENT>" ... } },
  { "phoneNumber": "+5521988888888",
    "message": { ... "code": "<CODE_FOR_THAT_RECIPIENT>" ... } }
]

Sample Responses

Each message in the request returns one key, in the order you sent them. Use the key to identify that message in delivery reporting.

200 OK

{ "keys": ["whatsapp-..."] }

400 Bad Request

A request with an invalid Pix payment setup returns 400. The following table lists the errors and their fixes:

Request Shape Rules

Two more rules apply to the request shape:

• payment_setting is singular. WhatsApp's separate Orders API uses a plural payment_settings array, and that shape does not work here.

• payment_setting is valid only under a payment_request button. If you place it on a quick reply or a URL button, Insider One rejects the request.

Messages to Non-Brazilian Numbers

A request to a non-Brazilian number returns 200, but the message never arrives. Insider One does not send Pix messages to numbers outside Brazil, because Meta rejects them. These messages appear in your delivery reporting as undelivered, not as an API error.

Limitations

• A template can include one payment button and up to three buttons in total.

• You can combine the payment button with Quick Reply, Visit Website, and Call Phone Number buttons within the three-button total. Meta allows the Share Contact Info button only on its own, so you cannot combine it with a payment button.

• Carousel templates and carousel cards do not support the payment button.

• Payment templates are available in the Marketing and Utility categories.

• Pix messages go only to Brazilian phone numbers (country code +55).

• Each recipient needs their own Pix code. A valid BR Code has no length or character limit, and it can exceed 500 characters.

• Pix payment templates are available through the API only. They do not appear in the template picker of segment campaigns or in Architect.