# 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

- An active WhatsApp connection and the `catalog_management` permission granted to the Meta app (without it, `403` [`commerce_permission_missing`](/en/errors#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`.

## 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 |

```json
{
  "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

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`](/en/errors#catalog_not_linked). Templates with a catalog or several products use Meta's format, like any other [template](/en/start/concepts/).

## 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

Send an `order_details` with `payment_type: "br"`:

```json
{
  "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`](/en/errors#order_totals_mismatch);
- `reference_id` unique on the connection, 1 to 35 characters (letters, digits, `_`, `.`, `-`); repeated → `409` [`order_reference_taken`](/en/errors#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`.

## 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:

```bash
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

Send `order_status` (`action.name: "review_order"`) to update the contact: `processing`, `partially_shipped`, `shipped`, `completed` or `canceled`.

```text
cart_received → pending → processing → partially_shipped → shipped → completed
cart_received | pending | processing → canceled
```

A transition off this path → `409` [`order_invalid_transition`](/en/errors#order_invalid_transition).

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