> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soneka.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Pay

> Collect payments natively inside a WhatsApp chat using Meta's order_details message.

**WhatsApp Pay** (available from Soneka v1.2) lets you request a payment inside the chat itself. The contact taps **Review and pay**, completes checkout in the WhatsApp native payment sheet, and Soneka records the result on the conversation — no external link, no browser hop.

<Warning>
  **Cloud API only, region-locked.** WhatsApp Pay uses Meta's native `order_details` message type, which requires the **WhatsApp Cloud API** engine and is only available in the countries where Meta has enabled in-chat payments. Workspaces on the Unofficial API or Twilio can't use this feature. Check Meta's current availability before enabling it for a client.
</Warning>

## How it works

<Steps>
  <Step title="Agent or flow builds an order">
    Line items, quantities, prices, taxes, and shipping are assembled either from the Team Inbox or by a flow (for example, after a Catalog interaction).
  </Step>

  <Step title="Soneka sends an order_details message">
    The contact sees a rich card with the itemized total and a **Review and pay** button.
  </Step>

  <Step title="Contact pays inside WhatsApp">
    Payment is captured by the payment provider Meta has configured for their region (UPI in India, credit card in Singapore, etc.).
  </Step>

  <Step title="Webhook updates the order">
    Meta calls back with `pending`, `processing`, `success`, or `failed`. Soneka stores the status, notifies the agent, and can branch a flow on the outcome.
  </Step>
</Steps>

## Before you start

WhatsApp Pay needs a few things on the **Meta** side that Soneka can't set up for you:

1. A **WhatsApp Business Account** connected via the Cloud API engine.
2. A **payment configuration** in Meta Business Manager → **WhatsApp Manager → Payments**, with a payment provider approved for your region.
3. The **Payments Read/Write** permission on the system user token Soneka uses.
4. A **catalog** attached to the WhatsApp Business Account (recommended — makes it easy to build line items).

Once that's in place, open **Settings → Payments → WhatsApp Pay** in Soneka and paste the Meta payment configuration name.

## Sending a payment request

### From the Team Inbox

1. Open the conversation.
2. Click the **⊕** menu next to the message box → **Request payment**.
3. Add line items manually or pick from the catalog.
4. Set tax, shipping, and expiry (up to 24 hours).
5. Send.

### From a flow

Drag in the **Request Payment** node in the Flow Builder. Map the items from previous steps (a Catalog reply, form answers, or attributes) and connect the outcome branches:

```text theme={null}
[Catalog reply] → [Request Payment]
                    ├─ success   → [Message: "Thanks! Order confirmed."] → [Fulfilment webhook]
                    ├─ failed    → [Message: "Payment didn't go through. Try again?"]
                    └─ expired   → [Assign to Sales]
```

## Order statuses

| Status         | Meaning                                              |
| -------------- | ---------------------------------------------------- |
| **pending**    | Order sent, contact hasn't paid yet.                 |
| **processing** | Contact submitted payment; provider is confirming.   |
| **success**    | Payment captured. Fulfilment can start.              |
| **failed**     | Provider rejected the payment.                       |
| **expired**    | The order's validity window elapsed with no payment. |

All status transitions are written to the conversation timeline and to the Message History log.

## Refunds

Refunds are processed by your payment provider through Meta's WhatsApp Manager. Soneka records refund events on the original order so agents can see the full history, but the refund itself is initiated on the provider dashboard.

## Troubleshooting

<Warning>
  **"Payment configuration not found"** — the name you entered in Soneka doesn't match the one in WhatsApp Manager → Payments. It's case-sensitive.
</Warning>

<Warning>
  **"order\_details is not supported for this recipient"** — the contact's WhatsApp app or country isn't enabled for in-chat payments. Fall back to a hosted checkout link.
</Warning>

## Related

* [Catalog & Storefront](/features/catalog-storefront) — build the products you sell in-chat.
* [Flow Builder](/features/flow-builder) — automate order collection and post-payment fulfilment.
* [Team Inbox](/features/team-inbox) — send one-off payment requests from a live chat.