Payment Request & Order Status

Send WhatsApp payment details and order updates through POST /v1/communication/whatsapp/message, with x-api-key and Content-Type: application/json. These features require a compatible WhatsApp connection; the current implementation does not provide these transformations on every connection. Confirm compatibility in the dashboard or with Hub support before relying on them. They are unavailable on Instagram, Messenger, Telegram, SMS and Web Chatt, and are not sandbox examples.

Payment requests and order updates without a template require an active 24-hour customer-service window. Outside it, use an approved compatible ORDER_STATUS template for order updates. A closed window can return WHATSAPP_CUSTOMER_WINDOW_CLOSED. Hub acceptance is separate from provider delivery; inspect the send result and later status webhooks.

The examples below are complete request bodies. Replace channel IDs, recipient numbers and payment details with your real values. Hub sends payment instructions; it does not issue a PIX charge, generate a boleto or capture payment for your business.

Payment Request

PIX

Obtain a complete valid copy-and-paste PIX code from your payment provider. PIX_COPY_AND_PASTE_CODE_FROM_YOUR_PAYMENT_PROVIDER is a placeholder, not a payable code.

{
  "from": "9e85226d-a104-4c85-a21a-5c3cbf7daa8f",
  "to": "5511993986082",
  "content": {
    "paymentRequest": {
      "bodyText": "Payment via PIX",
      "referenceId": "order-987654344",
      "paymentMethod": "pix",
      "pix": {
        "code": "PIX_COPY_AND_PASTE_CODE_FROM_YOUR_PAYMENT_PROVIDER",
        "merchantName": "Example Store",
        "key": "39580525000189",
        "keyType": "CNPJ"
      },
      "totalAmountCents": 50000,
      "offset": 100,
      "items": [
        {
          "retailerId": "prod-001",
          "name": "Product A",
          "amountCents": 50000,
          "quantity": 1
        }
      ]
    }
  }
}

Boleto

Replace the sample digits with the valid digitable line of your issued boleto.

{
  "from": "9e85226d-a104-4c85-a21a-5c3cbf7daa8f",
  "to": "5511993986082",
  "content": {
    "paymentRequest": {
      "bodyText": "Payment via boleto",
      "referenceId": "order-boleto-76126787",
      "paymentMethod": "boleto",
      "boleto": {
        "digitableLine": "846600000000440000641009013645834345925078459722"
      },
      "totalAmountCents": 10000,
      "items": [
        {
          "retailerId": "prod-002",
          "name": "Product B",
          "amountCents": 10000,
          "quantity": 1
        }
      ]
    }
  }
}

Payment link

{
  "from": "9e85226d-a104-4c85-a21a-5c3cbf7daa8f",
  "to": "5511993986082",
  "content": {
    "paymentRequest": {
      "bodyText": "Open 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,
      "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"
      }
    }
  }
}

Payment Request fields

“Required” below describes Hub request validation. Provider requirements can be stricter.

Field	Required by Hub	Description
bodyText	Yes	Nonempty descriptive text
referenceId	Yes	Your nonempty order reference
paymentMethod	Yes	pix, boleto, or payment_link
pix	No	Supply for PIX; its fields are required when the object is present
boleto	No	Supply for boleto; digitableLine required when present
paymentLink	No	Supply for payment link; url required when present
totalAmountCents	Yes	Nonnegative amount; interpreted using offset
offset	No	Defaults to 100; 100 displays minor units as cents
items	Yes	Item array; at most 100 entries
currency	No	Defaults to BRL, independently of channel configuration
tax	No	valueCents required when present; its own offset defaults to 100
subtotalCents	No	Defaults to the sum of amountCents × quantity for all items

Each item requires nonempty retailerId and name, nonnegative amountCents, and quantity of at least 1. Send at least one item and the payment-details object matching your method. Hub does not currently enforce conditional presence of that object or a minimum array length; absence can still fail at the provider. Do not treat a validation success as confirmation of valid payment data.

Use a positive offset; although Hub's current validator accepts zero, zero is not a usable display divisor. With offset: 100, totalAmountCents: 8990 displays BRL 89.90. Use consistent offsets and amounts. Omitting subtotal does not calculate or reconcile the total, taxes or discounts; provide coherent values yourself.

PIX keyType	Value shape
CPF	CPF digits
CNPJ	CNPJ digits
EMAIL	Email address
PHONE	International number such as +5511999999999
EVP	Random PIX key UUID

Order Status

Accepted status values are pending, processing, partially_shipped, shipped, completed, and canceled. Hub sends the requested state; this operation does not enforce an order lifecycle or reconcile a payment.

Within the active window

{
  "from": "9e85226d-a104-4c85-a21a-5c3cbf7daa8f",
  "to": "5511993986082",
  "content": {
    "orderStatus": {
      "referenceId": "order-987654344",
      "status": "shipped"
    }
  }
}

The free-form order-status message currently uses the fixed text “Order status update”. orderStatus.bodyText is not a supported field and is discarded. For custom tracking information, send a separate text message within the window or use a suitable approved template.

Completed status with payment confirmation

{
  "from": "9e85226d-a104-4c85-a21a-5c3cbf7daa8f",
  "to": "5511993986082",
  "content": {
    "orderStatus": {
      "referenceId": "order-987654344",
      "status": "completed",
      "payment": {
        "status": "captured",
        "timestamp": 1791298800
      }
    }
  }
}

Supply payment confirmation when it applies to your order/provider flow. Hub does not require payment specifically for completed. If supplied, it requires status: "captured" and a nonnegative Unix timestamp in seconds.

Outside the window with an ORDER_STATUS template

{
  "from": "9e85226d-a104-4c85-a21a-5c3cbf7daa8f",
  "to": "5511993986082",
  "content": {
    "template": {
      "id": "b50baa16-555b-4cfc-8fa8-29392a6e43d1"
    },
    "orderStatus": {
      "referenceId": "order-987654344",
      "status": "shipped"
    }
  }
}

The selected template must be of the ORDER_STATUS type. Hub constructs its order-status component automatically; do not send custom components in this combination. Its approved template controls the message text. The feature still requires a compatible connection.

Order Status field	Required by Hub	Description
referenceId	Yes	Nonempty order reference
status	Yes	One of the accepted status values above
payment	No	Payment confirmation when applicable
payment.status	If payment supplied	captured
payment.timestamp	If payment supplied	Unix seconds, nonnegative

See WhatsApp Templates for discovery, variables and template sending, and Event Types and Payload for subsequent delivery status.