WhatsApp Order Details & Order Status
Order Details is available for Brazilian payment accounts only, and all amounts are in BRL.
Overview
WhatsApp Order Details lets a business send a customer a payment request, an itemized order with a total amount and one or more Brazilian payment options, directly inside a WhatsApp conversation. The customer can pay without leaving WhatsApp (for example, copying a dynamic Pix code into their bank app or opening a payment link), and the business then updates the order’s progress with an Order Status message.
In UChat the feature is delivered through two flow steps:
WhatsApp Order Details — sends the order/invoice message together with the payment option(s).
WhatsApp Order Status — sends a follow-up message that updates the order status and payment status (e.g. processing, shipped, paid).
The two steps as they appear in the flow builder, each with an “If send WhatsApp failed” branch.
Both are WhatsApp message-template features, so the underlying template must be created in UChat and approved by Meta before it can be used to send messages.
How it works
The customer chats with the business and chooses what to buy.
The business sends a WhatsApp Order Details message containing the itemized order, the total in BRL, and the payment option(s).
The customer pays — for Pix they copy the Pix code and pay in their bank app; for a payment link the checkout opens in their browser; for boleto they copy the boleto code.
The business sends a WhatsApp Order Status message to update the order (e.g. to “processing”) and the payment status.
Each order carries a unique reference ID (shown to the customer as “Nº da cobrança”). WhatsApp does not reconcile payments for you — your payment service provider (PSP) confirms the payment, and you match it back to the order using this reference ID.
Requirements
Before you can use Order Details you need:
A Brazilian WhatsApp Business number connected to your UChat workspace.
An approved Order Details message template (see “Creating the Order Details template”). Meta does not allow payment options to be attached at template-creation time — they are added only when the message is sent.
For testing, a second Brazilian number to receive the messages. Messages cannot be delivered to landline numbers (see “Known limitations”).
Creating the Order Details template
Order Details messages are sent from an approved template. To create one in UChat:
Open the WhatsApp channel’s template manager and click Add New Template.
Fill in the template fields:
Name (required, up to 200 characters) — must be entered in English, lowercase with underscores, e.g. test_order_details.
Category / Type (required) — choose UTILITY or MARKETING.
Language (required) — the language of the body/footer text must match this selection (e.g. Portuguese (BR)).
Under Interactive component, select Order details. A “Brazil only” tag appears, confirming the template is for Brazilian payments in BRL. (The other options — Buttons, Call permission request — are different template types.)
Choose a Header type — None, Text, Image, or Document. Choose Document to attach a PDF (e.g. an invoice or boleto) in the header.
Write the Body (required, up to 1,000 characters). Use the variable token (</>) to insert placeholders such as the customer’s name, amount, and due date.
Optionally add a Footer (up to 60 characters).
Click Send to review. The template is submitted to Meta, categorized, and reviewed. Once approved, its status becomes Active and it can be used to send messages.
Creating an Order Details template in UChat (Category: Marketing or Utility, Language: Portuguese (BR), Interactive component: Order details).
Header rule The header type cannot be changed after the template is created. Meta only allows later edits to templates that were created with an image or document header — so if you may ever need to update the template, create it with an image or document header from the start. |
Note The preview shown while building the template (a single “Review and pay” button) is not an exact representation of the final message. Payment methods and their buttons are not part of the template; they are added when the message is sent, and their button labels are set by Meta. |
Sending the message: the WhatsApp Order Details step
Add a WhatsApp Order Details step to your flow and select the approved template. When configuring the step you set:
Payment method — the Brazilian payment method to offer (Dynamic Pix code, Boleto, Payment Link, or card). See “Payment methods” below.
Item Type — e.g. Digital goods.
Item Name — the line item shown on the order card, e.g. Invoice payment.
Total Amount — the amount in BRL (e.g. 500.00).
Reference ID — the unique charge/order identifier (shown to the customer as “Nº da cobrança”).
Body variables — values for the placeholders defined in the template (e.g. name, amount, due date). If the header is a document, you also provide the PDF URL and a file name.
Each value can be set as a default on the template or supplied as a runtime value when the message is sent (for example, from a user field or the output of a previous step).
If the message can’t be sent, the step’s “If send WhatsApp failed” branch routes the contact to the next step you choose (see “Error handling & troubleshooting”).
Updating the order: the WhatsApp Order Status step
Add a WhatsApp Order Status step to send a progress update for an existing order. You configure:
Body (up to 1,024 characters) — the message text; you can include the order and payment status through variables.
Footer (up to 60 characters) — optional.
Order Status and Payment Status — the structured status values that drive the order state in WhatsApp. Allowed values are listed below.
Order Status (order_status) | Payment Status (payment_status) |
pending processing partially_shipped shipped completed canceled | pending captured failed |
Payment methods
Order Details supports the Brazilian payment methods below. The button labels are generated and localized by Meta and cannot be customized:
Dynamic Pix code — button “Copiar código Pix”. You provide the Pix code, merchant_name, key, and key_type (e.g. CNPJ); Meta renders the copy button automatically.
Boleto — button “Copiar código do boleto”.
Payment Link — button “Abrir link de pagamento”.
Card (Visa / Mastercard) — shown in the “Pagar com” row.
When more than one payment option is configured, the customer sees the main option(s) as direct buttons and the remaining ones grouped under a “Mais formas de pagar” (“More ways to pay”) button. The exact buttons rendered depend on the payment method and are controlled by Meta.
What the customer sees
The Order Details message appears as a card with the total amount, a “Pagar com” row of available payment-method icons, the body text, and the payment buttons. A separate Order Status message shows the current order and payment status.
Example: a R$ 100,00 Order Details message (Pix, Boleto, Visa and Mastercard) with “Copiar código Pix”, “Abrir link de pagamento” and “Mais formas de pagar” buttons, followed by an Order Status update.
Known limitations & issues
Header type is permanent. You cannot change a template’s header type after creation, and Meta only allows edits to templates created with an image or document header.
Button labels are fixed by Meta. Payment button text (e.g. “Copiar código Pix”) cannot be customized; it is generated and localized by Meta to the template’s language. Custom button text fails Meta API validation.
PDF header only in templates. A PDF/document header is supported in Order Details templates, not in interactive Order Details messages.
PDF download on mobile. During testing, a PDF attached in the header could not be downloaded on the WhatsApp Android app, but downloaded correctly on the WhatsApp Desktop app and WhatsApp Web. This appeared to be a Meta-side issue — verify on your account.
No delivery to landline numbers. Messages are not delivered to landline numbers; sending to a standard WhatsApp Business number works. Undeliverable sends return Meta error 131026 (“Message undeliverable”).
Payment methods aren’t set at creation. Payment options can only be attached when the message is sent, so the in-builder preview differs from the final message.
Error handling & troubleshooting
“If send WhatsApp failed” branch. Both steps expose this branch; connect it to a fallback step (e.g. notify an agent, retry, or send an alternative message) so contacts aren’t stranded when a send fails.
Error 131026 — “Message undeliverable”. Commonly seen when sending to a landline or a number that can’t receive the message. Confirm the recipient is a WhatsApp-enabled, non-landline number.
Duplicated incoming messages. If messages duplicate after connecting the number, go to Facebook → Settings & Privacy → Business Integrations and remove the duplicate “uchat” integration (leave the chatbot app integration in place).
Occasional “send failed” during template testing. While validating a brand-new template you may see occasional “send failed” notices; these can occur before a template is fully active.
Technical reference (API)
Most users configure everything through the UChat steps above and won’t need the API directly. The underlying Meta and UChat structures are summarized here for advanced use.
Template structure (Meta)
category: UTILITY or MARKETING.
display_format: ORDER_DETAILS.
Header format: TEXT, IMAGE, or DOCUMENT.
Components: HEADER, BODY, FOOTER, and a BUTTONS block containing a single button of type ORDER_DETAILS.
Amounts
Monetary values use a value + offset pair; the actual amount is value ÷ offset. For example { "value": 55700, "offset": 100 } = R$ 557.00.
Sample send payload (dynamic Pix, text header)
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<RECIPIENT_PHONE_NUMBER>", "type": "template", "template": { "name": "<TEMPLATE_NAME>", "language": { "policy": "deterministic", "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "<CUSTOMER_NAME>" }, { "type": "text", "text": "<REFERENCE_ID>" } ] }, { "type": "button", "sub_type": "order_details", "index": 0, "parameters": [ { "type": "action", "action": { "order_details": { "reference_id": "<REFERENCE_ID>", "type": "digital-goods", "payment_type": "br", "payment_settings": [ { "type": "pix_dynamic_code", "pix_dynamic_code": { "code": "<DYNAMIC_PIX_COPY_PASTE_CODE>", "merchant_name": "<MERCHANT_NAME>", "key": "<PIX_KEY>", "key_type": "CNPJ" } } ], "currency": "BRL", "total_amount": { "value": 55700, "offset": 100 }, "order": { "status": "pending", "items": [ { "retailer_id": "<ITEM_ID>", "name": "<ITEM_NAME>", "amount": { "value": 55700, "offset": 100 }, "quantity": 1 } ], "subtotal": { "value": 55700, "offset": 100 }, "tax": { "value": 0, "offset": 100 } } } } } ] } ] } } |
UChat send endpoint
Build the template name, language and parameters, then send the approved template to a subscriber:
POST /api/subscriber/send-whatsapp-template-by-user-id |
Reference