Guides
Selling on WhatsApp
Catalog, products, cart and payment with Pix, payment link or boleto: how to build, send and reconcile an order.
WhatsApp sells in three steps: the contact browses the catalog, builds a cart and you send the charge (order_details) with Pix, a payment link or boleto. Messajo stores each order, computes the totals and reports by event.
Before you start
Section titled “Before you start”- An active WhatsApp connection and the
catalog_managementpermission granted to the Meta app (without it,403commerce_permission_missing). - A key with
commercefor catalogs, products, settings and manual payment,sendfor the messages andreadto read. In the panel, Sales. - Amounts are always in cents (
amount_minor, integer).R$ 12.90=1290.
Catalog and products
Section titled “Catalog and products”| Call | What it does |
|---|---|
POST /v1/catalogs |
creates a catalog in the portfolio and links it to the messaging account ({ connection_id, name }) |
POST /v1/catalogs/link · POST /v1/catalogs/{id}/unlink |
links an existing catalog (catalog_external_id) or unlinks it |
POST /v1/catalogs/{id}/sync |
reloads the products from Meta (also runs daily) |
GET · PUT /v1/connections/{id}/commerce-settings |
is_cart_enabled (cart) and is_catalog_visible (shop icon) |
GET · POST /v1/catalogs/{id}/products |
lists and creates products |
GET · PATCH · DELETE /v1/products/{id} |
reads, updates and deletes |
{ "retailer_id": "carrot-cake", "name": "Carrot cake", "amount_minor": 4500, "sale_amount_minor": 3900, "currency": "BRL", "availability": "in stock", "image_url": "https://shop.yourcompany.com/img/cake.jpg"}retailer_id is your product code: it goes in the messages and comes back in the cart.
Showing products
Section titled “Showing products”Through POST /v1/messages, with type: "interactive":
interactive.type |
What it shows |
|---|---|
product |
one product (action.catalog_id + product_retailer_id) |
product_list |
up to 30 products in up to 10 sections, with a text header |
catalog_message |
the whole catalog, with a cover product (thumbnail_product_retailer_id) |
A catalog not linked to the account → 409 catalog_not_linked. Templates with a catalog or several products use Meta’s format, like any other template.
Receiving the cart
Section titled “Receiving the cart”The contact sends the cart and message.received (order content) and order.received arrive, with the order in cart_received, the items and the totals computed from the cart prices. Read it later with GET /v1/orders or GET /v1/orders/{id}.
Charging with Pix
Section titled “Charging with Pix”Send an order_details with payment_type: "br":
{ "connection_id": "conn_...", "to": "5511999990001", "type": "interactive", "interactive": { "type": "order_details", "body": { "text": "Your order" }, "action": { "name": "review_and_pay", "parameters": { "reference_id": "order-1042", "type": "digital-goods", "payment_type": "br", "currency": "BRL", "total_amount": { "value": 3900, "offset": 100 }, "payment_settings": [ { "type": "pix_dynamic_code", "pix_dynamic_code": { "code": "00020101021226…6304ABCD", "merchant_name": "Example Bakery", "key": "39580525000189", "key_type": "CNPJ" } } ], "order": { "status": "pending", "items": [{ "retailer_id": "carrot-cake", "name": "Carrot cake", "amount": { "value": 3900, "offset": 100 }, "quantity": 1 }], "subtotal": { "value": 3900, "offset": 100 } } } } }}Messajo checks before calling Meta:
currency: "BRL",offset: 100on every amount andaction.name: "review_and_pay";subtotal= sum ofquantity × (sale_amount ?? amount)andtotal=subtotal + tax + shipping − discount; a mismatch →422order_totals_mismatch;reference_idunique on the connection, 1 to 35 characters (letters, digits,_,.,-); repeated →409order_reference_taken;- 1 to 3 payment methods, no repeated type:
pix_dynamic_code(the copy-and-paste code from your PSP, name, key and key type),payment_link(httpsuri) andboleto(digitable_line); - up to 100 items.
Pix requirements: the dynamic code comes from your PSP (bank or gateway), with the order amount; the key must belong to the same account. Meta only shows the code to the contact.
After sending, the order is pending with payment_status: pending and order.updated fires. With Meta’s expiration parameter, an expired order becomes payment_status: expired.
Reconciling the payment
Section titled “Reconciling the payment”Off-platform Pix has no payment webhook: Meta does not know whether the contact paid. Reconcile on your PSP by reference_id (use the same id on the PSP charge) and tell Messajo:
curl https://api.messajo.com/v1/orders/ord_.../payment \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "captured", "notify": true }'notify: true sends the contact an order_status processing (with an optional message) and the response has notification_message_id. In the panel, the order has Mark as paid. Payment links and cards with a Meta webhook update by themselves and emit payment.updated.
Order progress
Section titled “Order progress”Send order_status (action.name: "review_order") to update the contact: processing, partially_shipped, shipped, completed or canceled.
cart_received → pending → processing → partially_shipped → shipped → completedcart_received | pending | processing → canceledA transition off this path → 409 order_invalid_transition.
Events
Section titled “Events”| Type | When |
|---|---|
order.received |
a cart arrived |
order.updated |
charge sent, status changed, payment marked or expired |
payment.updated |
Meta reported the payment ({ order: { id, reference_id }, payment: { status, method, transaction } }) |