Skip to main content
Version: Latest

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
}
]
}
}
}
{
"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.

FieldRequired by HubDescription
bodyTextYesNonempty descriptive text
referenceIdYesYour nonempty order reference
paymentMethodYespix, boleto, or payment_link
pixNoSupply for PIX; its fields are required when the object is present
boletoNoSupply for boleto; digitableLine required when present
paymentLinkNoSupply for payment link; url required when present
totalAmountCentsYesNonnegative amount; interpreted using offset
offsetNoDefaults to 100; 100 displays minor units as cents
itemsYesItem array; at most 100 entries
currencyNoDefaults to BRL, independently of channel configuration
taxNovalueCents required when present; its own offset defaults to 100
subtotalCentsNoDefaults 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_typeValue shape
CPF11 CPF digits, without punctuation
CNPJ14 CNPJ digits, without punctuation
EMAILRegistered email address
PHONEInternational number with + and country code, such as +5511999999999; no spaces, parentheses or hyphens
EVPRegistered 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)
codecode
merchantNamemerchant_name
keykey
keyTypekey_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.paymentMethodMatching high-level objectProvider payment_settings[] entry
pixpixtype: "pix_dynamic_code", with pix_dynamic_code
boletoboleto.digitableLinetype: "boleto", with boleto.digitable_line
payment_linkpaymentLink.urltype: "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 fieldRequired by HubDescription
referenceIdYesNonempty order reference
statusYesOne of the accepted status values above
paymentNoPayment confirmation when applicable
payment.statusIf payment suppliedcaptured
payment.timestampIf payment suppliedUnix seconds, nonnegative

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