Payment Request & Order Status

Exclusive WhatsApp features that allow you to send charges and order status updates directly in the conversation.

WhatsApp only

Payment Request and Order Status are exclusive to the WhatsApp channel. They are not available on Instagram, Messenger, Telegram, or SMS.

Payment Request

Sends an interactive charge message with payment details. Supports three methods: PIX, Boleto, and Payment link.

PIX

{
  "from": "channel-uuid-wa",
  "to": "5511993986082",
  "content": {
    "paymentRequest": {
      "bodyText": "Payment via PIX",
      "referenceId": "order-987654344",
      "paymentMethod": "pix",
      "pix": {
        "code": "00020101021226...",
        "merchantName": "Example Store",
        "key": "39580525000189",
        "keyType": "CNPJ"
      },
      "totalAmountCents": 50000,
      "offset": 100,
      "items": [
        {
          "retailerId": "prod-001",
          "name": "Product A",
          "amountCents": 50000,
          "quantity": 1
        }
      ]
    }
  }
}

Boleto

{
  "content": {
    "paymentRequest": {
      "bodyText": "Payment via Boleto",
      "referenceId": "order-boleto-76126787",
      "paymentMethod": "boleto",
      "boleto": {
        "digitableLine": "846600000000440000641009013645834345925078459722"
      },
      "totalAmountCents": 10000,
      "offset": 100,
      "items": [
        {
          "retailerId": "prod-001",
          "name": "Product B",
          "amountCents": 10000,
          "quantity": 1
        }
      ]
    }
  }
}

Payment link

{
  "content": {
    "paymentRequest": {
      "bodyText": "Click the link to complete your payment.",
      "referenceId": "order-link-123",
      "paymentMethod": "payment_link",
      "paymentLink": {
        "url": "https://payment.example.com/pay/order-123"
      },
      "currency": "BRL",
      "totalAmountCents": 8990,
      "offset": 100,
      "items": [
        {
          "retailerId": "item1",
          "name": "Online course",
          "amountCents": 7990,
          "quantity": 1
        },
        {
          "retailerId": "item2",
          "name": "Platform fee",
          "amountCents": 1000,
          "quantity": 1
        }
      ],
      "tax": {
        "valueCents": 0,
        "offset": 100,
        "description": "No additional taxes"
      },
      "subtotalCents": 8990
    }
  }
}

Payment Request fields

Field	Required	Description
bodyText	✅	Descriptive text of the charge
referenceId	✅	Order ID in your system (free string)
paymentMethod	✅	pix, boleto, or payment_link
pix	Conditional	Required if paymentMethod is pix
boleto	Conditional	Required if paymentMethod is boleto
paymentLink	Conditional	Required if paymentMethod is payment_link
totalAmountCents	✅	Total amount in cents
offset	✅	Divisor for display (100 = cents, 1 = units)
items	✅	Array of order items (minimum 1)
currency	❌	Currency code (e.g. BRL) — channel default
tax	❌	Tax information
subtotalCents	❌	Subtotal before taxes/discounts

PIX key types

keyType	Format
CPF	12345678901
CNPJ	12345678000195
EMAIL	[email protected]
PHONE	+5511999999999
EVP	Random key (UUID)

---

Order Status

Sends an order status update in the conversation. Works both within the 24h window (without template) and outside it (with ORDER_STATUS template).

Status lifecycle

pending → processing → partially_shipped → shipped → completed
                                        ↘ canceled

Within the 24h window (free text)

{
  "content": {
    "orderStatus": {
      "referenceId": "order-987654344",
      "status": "shipped",
      "bodyText": "Your order has been shipped! Tracking code: BR123456789BR"
    }
  }
}

completed status with payment confirmation

{
  "content": {
    "orderStatus": {
      "referenceId": "order-987654344",
      "status": "completed",
      "bodyText": "Payment confirmed. Thank you for your purchase!",
      "payment": {
        "status": "captured",
        "timestamp": 1766323331
      }
    }
  }
}

Outside the 24h window (with ORDER_STATUS template)

When there is no active session, combine template.id + orderStatus:

{
  "content": {
    "template": {
      "id": "b50baa16-555b-4cfc-8fa8-29392a6e43d1"
    },
    "orderStatus": {
      "referenceId": "order-987654344",
      "status": "shipped",
      "bodyText": "Your order has been shipped! Tracking code: BR123456789BR"
    }
  }
}

warning

The template passed in template.id must be of the ORDER_STATUS type. The platform builds the order_status component automatically — do not pass components manually in this case.

Order Status fields

Field	Required	Description
referenceId	✅	Order ID in your system
status	✅	One of: pending, processing, partially_shipped, shipped, completed, canceled
bodyText	❌	Descriptive status text
payment	Conditional	Required when status is completed
payment.status	✅	Always captured
payment.timestamp	✅	Unix timestamp of the payment capture