Skip to content

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.

  • An active WhatsApp connection and the catalog_management permission granted to the Meta app (without it, 403 commerce_permission_missing).
  • A key with commerce for catalogs, products, settings and manual payment, send for the messages and read to read. In the panel, Sales.
  • Amounts are always in cents (amount_minor, integer). R$ 12.90 = 1290.
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.

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.

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}.

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: 100 on every amount and action.name: "review_and_pay";
  • subtotal = sum of quantity × (sale_amount ?? amount) and total = subtotal + tax + shipping − discount; a mismatch → 422 order_totals_mismatch;
  • reference_id unique on the connection, 1 to 35 characters (letters, digits, _, ., -); repeated → 409 order_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 (https uri) and boleto (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.

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:

Janela do terminal
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.

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 → completed
cart_received | pending | processing → canceled

A transition off this path → 409 order_invalid_transition.

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 } })