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 key types
The type must describe the actual registered key. PHONE is a phone key; EVP is a random-key UUID. A phone number with EVP is not valid. The copy-and-paste code is separate from key: obtain a complete valid code from your payment provider and use matching payment data.
PIX keyType / provider key_type | Value shape |
|---|---|
CPF | 11 CPF digits, without punctuation |
CNPJ | 14 CNPJ digits, without punctuation |
EMAIL | Registered email address |
PHONE | International number with + and country code, such as +5511999999999; no spaces, parentheses or hyphens |
EVP | Registered random PIX key UUID, such as 550e8400-e29b-41d4-a716-446655440000 |
The values above illustrate shape, not keys registered for your business. Hub validates the keyType enum in paymentRequest, but does not prove that a key is registered, validate its matching format, or verify the payment code. The provider can reject it later.
For a phone key, replace the pix object in the complete Payment Request example with this object, using your real registered phone and payment code:
{
"code": "PIX_COPY_AND_PASTE_CODE_FROM_YOUR_PAYMENT_PROVIDER",
"merchantName": "Example Store",
"key": "+5511999999999",
"keyType": "PHONE"
}
Payment Request versus template action fields
These are different input shapes; do not mix their casing:
Payment Request (content.paymentRequest.pix) | Template action (action.order_details.payment_settings[].pix_dynamic_code) |
|---|---|
code | code |
merchantName | merchant_name |
key | key |
keyType | key_type |
The equivalent phone-key object for a template action is:
{
"code": "PIX_COPY_AND_PASTE_CODE_FROM_YOUR_PAYMENT_PROVIDER",
"merchant_name": "Example Store",
"key": "+5511999999999",
"key_type": "PHONE"
}
Use it inside a payment_settings entry with type: "pix_dynamic_code". For CPF, CNPJ, email or random keys, change both the key and its matching discriminator according to the table. Do not leave EVP selected when replacing a random key with a phone number. See the complete order-details template action example.
Other payment methods and template compatibility
The complete Boleto and Payment link examples above use the high-level paymentRequest input. Hub maps those methods to these provider payment-settings objects:
paymentRequest.paymentMethod | Matching high-level object | Provider payment_settings[] entry |
|---|---|---|
pix | pix | type: "pix_dynamic_code", with pix_dynamic_code |
boleto | boleto.digitableLine | type: "boleto", with boleto.digitable_line |
payment_link | paymentLink.url | type: "payment_link", with payment_link.uri |
For a compatible provider action, the non-Pix entries have these shapes:
{
"type": "boleto",
"boleto": { "digitable_line": "VALID_DIGITABLE_LINE_FROM_YOUR_ISSUED_BOLETO" }
}
{
"type": "payment_link",
"payment_link": { "uri": "https://payment.example.com/pay/order-123" }
}
The provider, connection and approved template must support the selected method. Changing a Pix template's payment_settings does not make that template eligible for boleto or payment links. The dashboard's Pix order-details preview does not prove support for every method. The high-level request without a template still requires the active customer-service window described above.
Queued does not mean delivered
enqueued confirms that Hub accepted the outbound job; the provider may reject it afterward. Use the returned messageId to correlate later message-status webhooks. Error 131009 can indicate an invalid parameter, including a phone key declared as EVP or a literal placeholder sent as the key.
Replace every placeholder before sending: channel/recipient/template identifiers, the payment code, merchant name and key. {{PIX_KEY}}, {{PIX_COPY_PASTE_CODE}} and {{MERCHANT_NAME}} in examples are instructions to the integrator, not variables Hub substitutes automatically.
A failed job can have its reserved/charged Hub messaging amount released or refunded. That is not a refund of the customer's Pix payment; Hub does not capture or refund the payment itself.
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. If the approved template body has variables, include template.components with type: "body" and its positional text parameters; Hub preserves those values alongside the structured status. Header and button components are not used in this combination. Its approved template controls the message text. The feature still requires a compatible connection.
For example, an approved body Hello {{name}}, your order has been updated. uses:
{
"template": {
"id": "b50baa16-555b-4c85-a21a-5c3cbf7daa8f",
"components": [
{ "type": "body", "parameters": [{ "type": "text", "variable": "1", "text": "Ana" }] }
]
},
"orderStatus": { "referenceId": "order-123", "status": "shipped" }
}
Hub requires variable and text on every text parameter, including positional templates. Use variable: "1" for the first positional value; Hub removes that helper field before submitting to the provider.
This object is the message's content. The system status line is generated from the order status; do not prepend Status: {{Order Status}} to a body parameter.
| 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.