# Receive WhatsApp Payments via Payments Gateway
{% hint style="danger" %}
The Payments API feature is available only for Indian businesses using the 360dialog WhatsApp Business API with phone numbers only from India. Review [WhatsApp Business Compliance for India](https://www.facebook.com/help/1104628230079278).
{% endhint %}
{% hint style="success" %}
This feature is now available to all Indian businesses. If the account is in [high or medium tiers](https://docs.360dialog.com/partner/messaging/messaging-limits-and-quality-rating), admins or finance editors users will have direct access to the [Payment Gateway](https://business.facebook.com/billing_hub/payment_settings) page and can manage [payment settings in Meta Business Manager](https://www.facebook.com/business/help/915454841921082?id=180505742745347). If you have any trouble using this feature, please reach out to our Support Team.
{% endhint %}
Currently, customers browse business catalogs, add products to cart, and send orders with Meta's set of commerce messaging solutions, which includes [Single Product Message, Multi Product Message, and Product Detail Page](https://docs.360dialog.com/partner/messaging/commerce-and-payments/products-and-catalogs). With the Payments API, businesses can send customers a *bill*, so the customer can complete their order by paying the business without having to leave WhatsApp.
### How it Works
First, the business composes and sends an `order_details` message. An `order_details` message is a new type of `interactive` message, which always contains the same 4 main components: **header**, **body**, **footer**, and **action**. Inside the `action` component, the business includes all the information needed for the customer to complete their payment.
Each `order_details` message contains a unique `reference_id` provided by the business, and that unique ID is used throughout the flow to track the order.
Once the message is sent, the business waits for a payment status update via webhooks. Businesses get notified when the payment status changes, but they must not solely rely on these webhook notifications due to security reasons. WhatsApp also provides a payment lookup API that can be used to retrieve the payment statuses directly anytime.
{% hint style="warning" %}
Please note that neither 360dialog nor WhatsApp supports payment reconciliations.
You must reconcile the payment with the business payment service provider using the respective order `reference_id.`
{% endhint %}
### Purchase Flow in App
In the WhatsApp Messenger App, the purchase flow has the following steps:
1. Customers send an order with selected products to the business either through simple text messages or using other interactive messages such as [Single Product Message, Multi Product Message, and Product Detail](https://docs.360dialog.com/partner/messaging/commerce-and-payments/products-and-catalogs).
2. Once the business receives the order, they send an `order_details` message to the user. When the user taps on **Review and Pay**, they will see details about the order and total amount to be paid.
3. When the user taps the **Continue** button, they are able to choose to pay natively on WhatsApp or any other UPI app.
Checkout with WhatsApp Pay
Checkout on other UPI Apps
4. Once the payment has been confirmed by your payment gateway (PG) or payment service provider, the business can start processing the order.
5. Businesses can then send an `order_status` message to the consumer informing them about the status of the order. Each message will result in a message bubble (as shown above) that refers to the original order details message and also updates the status displayed on the order details page.
### Link Your Payment Account
To receive payments on WhatsApp, businesses must add a *payment configuration* to the corresponding WhatsApp Business Account. A payment configuration allows you to link a payment gateway account to WhatsApp. Each payment configuration is associated with a *unique name*. As part of the `order_details` message, you can specify the payment configuration to use for a specific checkout. WhatsApp will then generate a checkout flow using the associated payment gateway account.
#### If the WABA is a Shared WABA (created through Embedded Signup)
Businesses can use the 'Direct pay methods' page and under 'India' in [WhatsApp Business Manager](https://business.facebook.com/wa/manage/home).
Once the user enters the details, Meta redirects them to the payment gateway website to enter their credentials and link their account with WhatsApp as shown below.
#### If the WABA is an OBO (On-Behalf-of) WABA (created through Classic Signup)
In case of the OBO WhatsApp Business Accounts, 360dialog can enter the payment configuration details and generate a link URL. This link URL will be shared, which will allow you to log into the payment gateway account and connect it with WhatsApp.
For this, please reach out to our support team.
After linking the payment account, you must integrate with the Payments APIs below. This will allow you to send an `order_details` message to customers with the payment configuration to receive payments.
## Get Started
The steps outlined below assume that the business already knows what the user is interested in through earlier conversations. The Payments API is a standalone API and hence can work with various messages such as [List Messages, Reply Buttons, Single or Multi-Product Messages.](https://docs.360dialog.com/partner/messaging/sending-and-receiving-messages/text-messages/interactive-messages)
### Integration Steps
#### Sequence Diagram
The following sequence diagram demonstrates the typical integration flow for Payments API. The steps highlighted in green are the key integration steps.
### **Step 1: Send Order Details Interactive Message**
To send an `order_details` message, businesses must assemble an interactive object of type `order_details` with the following components:
| Object | Description |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
type
object
|
Required.
Must be "order\_details".
|
|
header
object
|
Optional.
Header content displayed on top of a message. If a header is not provided, the API uses an image of the first available product as the header
|
|
body
object
|
Required.
An object with the body of the message. The object contains the following field:
text string
Required if body is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters
|
|
footer
object
|
Optional.
An object with the footer of the message. The object contains the following fields:
text string
Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters
|
|
action
object
|
Required.
An action object you want the user to perform after reading the message. This action object contains the following fields:
Unique identifier for the order or invoice provided by the business. This cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters.
The reference\_id must be unique for each order\_details message for a given business. If there is a need to send multiple order\_details messages for the same order, it is recommended to include a sequence number in the reference\_id (for example, "BM345A-12") to ensure reference\_id uniqueness.
|
|
type
object
|
Required.
The type of goods being paid for in this order. Current supported options are digital-goods and physical-goods
|
|
beneficiaries
array
|
Required for shipped physical-goods.
An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. It contains the following fields:
Beneficiary information isn't shown to users but is needed for legal and compliance reasons.
name string
Required. Name of the individual or business receiving the physical goods. Cannot exceed 200 characters
address\_line1 string
Required. Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters
An object that describes payment account information:
type string
Required. Unique identifier for an item in the order. Mustset this to "razorpay", if you have linked your RZP payment gateway to accept payments
configuration\_name string
Required. The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters. This value must match with a payment configuration set up on the WhatsApp Business Manager.
When configuration\_name is invalid, the customer will be unable to pay for their order. We strongly advise businesses to conduct extensive testing of this setup during the integration phase.
razorpay/payu object
Optional. For merchants/partners that want to use notes, receipt(for Razorpay) and UDF fields(for PayU), they can now pass these values in Order Details message and we would use these to create transaction/order at respective PGs.
|
#### **RazorPay Notes and PayU UDF fields**
We now have support for partners and merchants to pass `notes`, `receipt` and `udf` fileds in Order Details message and receive this data back in payment signals. Here we will take a look at merchants can pass notes, receipt fields for Razorpay and UDF for PayU PGs.
| Object | Description |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
notes
object
|
Optional.
Only supported for Razorpay payment gateway
The object can be key value pairs with maximum 15 keys and each value limits to 256 characters.
|
|
receipt
String
|
Optional.
Only supported for Razorpay payment gateway
Receipt number that corresponds to this order, set for your internal reference. Maximum length of 40 characters supported with minimum length greater than 0 characters.
|
|
udf1-4
String
|
Optional.
Only supported for PayU payment gateway
User-defined fields (udf) are used to store any information corresponding to a particular order. Each UDF field has a maximum character limit of 255
Only supported value in the order\_details message is pending.
In an order\_status message, status can be: pending, captured, or failed.
|
|
items
object
|
Required.
An object with the list of items for this order, containing the following fields:
retailer\_id string
Required. Unique identifier for an item in the order.
name string
Required. The item’s name to be displayed to the user. Cannot exceed 60 characters
amount amount object with value and offset -- refer total amount field above
Required. The price per item
sale\_amount amount object
Optional. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount
quantity integer
Required. The number of items in this order, this field cannot be decimal has to be integer.
country\_of\_origin string
Required if catalog\_id is not present. The country of origin of the product
importer\_name string
Required if catalog\_id is not present. Name of the importer company
importer\_adress string
Required if catalog\_id is not present. Address of importer company
|
|
subtotal
object
|
Required.
The value must be equal to sum of order.amount.value \* order.amount.quantity. Refer to total\_amount description for explanation of offset and value fields
The following fields are part of the subtotal object:
offset integer
Required. Must be 100 for INR
value integer
Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234
|
|
tax
object
|
Required.
The tax information for this order which contains the following fields:
offset integer
Required. Must be 100 for INR
value integer
Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234
description string
Optional. Max character limit is 60 characters
|
|
shipping
object
|
Optional.
The shipping cost of the order. The object contains the following fields:
offset integer
Required. Must be 100 for INR
value integer
Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234
description string
Optional. Max character limit is 60 characters
|
|
discount
object
|
Optional.
The discount for the order. The object contains the following fields:
offset integer
Required. Must be 100 for INR
value integer
Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234
description string
Optional. Max character limit is 60 characters
discount\_program\_name string
Optional. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters
|
|
catalog\_id
object
|
Optional.
Unique identifier of the Facebook catalog being used by the business.
If you do not provide this field, you must provide the following fields inside the items object: country\_of\_origin, importer\_name, and importer\_address
|
|
expiration
object
|
Optional.
Expiration for that order. Business must define the following fields inside this object:
timestamp string – UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds
description string – Text explanation for expiration. Max character limit is 120 characters
|
The `parameters` value is a stringified JSON object.
By the end, the interactive object should look something like this for a catalog-based integration:
```json
{
"interactive": {
"type": "order_details",
"header": {
"type": "image",
"image": {
"link": "http(s)://the-url",
"provider": {
"name": "provider-name"
}
}
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "reference-id-value",
"type": "digital-goods",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "razorpay",
"configuration_name": "payment-config-id",
"razorpay": {
"receipt": "receipt-value",
"notes": {
"key1": "value1"
}
}
}
}
],
"currency": "INR",
"total_amount": {
"value": 21000,
"offset": 100
},
"order": {
"status": "pending",
"catalog_id": "the-catalog_id",
"expiration": {
"timestamp": "utc_timestamp_in_seconds",
"description": "cancellation-explanation"
},
"items": [
{
"retailer_id": "1234567",
"name": "Product name, for example bread",
"amount": {
"value": 10000,
"offset": 100
},
"quantity": 1,
"sale_amount": {
"value": 100,
"offset": 100
}
}
],
"subtotal": {
"value": 20000,
"offset": 100
},
"tax": {
"value": 1000,
"offset": 100,
"description": "optional_text"
},
"shipping": {
"value": 1000,
"offset": 100,
"description": "optional_text"
},
"discount": {
"value": 1000,
"offset": 100,
"description": "optional_text",
"discount_program_name": "optional_text"
}
}
}
}
}
}
```
The `parameters` value is a stringified JSON object.
For a non-catalog based integration i.e. when catalog-id is not present, an example payload looks as follows:
```json
{
"interactive": {
"type": "order_details",
"header": {
"type": "image",
"image": {
"id": "your-media-id"
}
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "reference-id-value",
"type": "digital-goods",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "razorpay",
"configuration_name": "payment-config-id"
}
}
],
"currency": "INR",
"total_amount": {
"value": 21000,
"offset": 100
},
"order": {
"status": "pending",
"expiration": {
"timestamp": "utc_timestamp_in_seconds",
"description": "cancellation-explanation"
},
"items": [
{
"retailer_id": "1234567",
"name": "Product name, for example bread",
"amount": {
"value": 10000,
"offset": 100
},
"quantity": 1,
"sale_amount": {
"value": 100,
"offset": 100
},
"country_of_origin": "country-of-origin",
"importer_name": "name-of-importer-business",
"importer_address": {
"address_line1": "B8/733 nand nagri",
"address_line2": "police station",
"city": "East Delhi",
"zone_code": "DL",
"postal_code": "110093",
"country_code": "IN"
}
},
{
"retailer_id": "14325",
"name": "Product name, for example bread",
"amount": {
"value": 10000,
"offset": 100
},
"quantity": 1,
"sale_amount": {
"value": 100,
"offset": 100
},
"country_of_origin": "country-of-origin",
"importer_name": "name-of-importer-business",
"importer_address": {
"address_line1": "B8/733 nand nagri",
"address_line2": "police station",
"city": "East Delhi",
"zone_code": "DL",
"postal_code": "110093",
"country_code": "IN"
}
}
],
"subtotal": {
"value": 20000,
"offset": 100
},
"tax": {
"value": 1000,
"offset": 100,
"description": "optional_text"
},
"shipping": {
"value": 1000,
"offset": 100,
"description": "optional_text"
},
"discount": {
"value": 1000,
"offset": 100,
"description": "optional_text",
"discount_program_name": "optional_text"
}
}
}
}
}
}
```
#### Add Common Message Parameters
Once the interactive object is complete, append the other parameters that make a message: `recipient_type`, `to`, and `type`. Remember to set the `type` to `interactive`.
```json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
// interactive object here
}
}
```
These [are parameters common to Cloud API message ](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#messages)types
#### Make a POST Call to /messages
Make a POST call to the [endpoint](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/messages#post-messages) with the JSON object you have assembled. If your message is sent successfully, you get the following response:
```json
{
"messaging_product": "whatsapp",
"contacts": [ {
"input": "[PHONE_NUMBER_ID]",
"wa_id": "[PHONE-NUMBER_ID]"
} ],
"messages": [ {
"id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
} ]
}
```
For all errors that can be returned and guidance on how to handle them, see [WhatsApp Cloud API, Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
**Product Experience**
The customer receives an `order_details` message similar to the one below (left). When they click on "**Review and Pay**", it opens up the order details screen as shown below (middle).
Customer can then pay for their order using "**Continue**" button that opens up a bottom sheet with the payment options (right).
### Step 2: Receive Webhook about Transaction Status
Businesses receive updates via [WhatsApp webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks) when the status of the user-initiated transaction changes in a status of type "payment". It contains the following fields:
| Object | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
id
string
|
Required.
Webhook ID for the notification.
|
|
from
string
|
Required.
WhatsApp ID of the customer.
|
|
type
string
|
Required.
For payment status update webhooks, type is "payment".
|
|
status
string
|
Required.
Latest status of the payment. Can be one of captured, failed or pending.
|
|
payment
object
|
Required.
Contains the following field:
reference\_id string
Unique reference ID for the order sent in order\_details message.
amount object
Has value and offset fileds corresponding to totao amount that user has paid.
currency string
currency is always INR.
notes object Optional.
Only sent for razorpay payment gateway when the value is sent in order details message. This contains key-value pair as passed in the Order Details message.
receipt string Optional.
Only sent for razorpay payment gateway when the value is sent in order details message.
udf1-4 string Optional.
Only sent for payu payment gateway when the value is sent in order details message. Each of the keys udf1-4 has string values in them.
|
|
timestamp
string
|
Required.
Timestamp for the webhook.
|
Here is an example status webhook of type `payment`:
```json
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "[PHONE_NUMBER]",
"phone_number_id": "[PHONE_NUMBER_ID]"
},
"contacts": [{...}],
"errors": [{...}],
"messages": [{...}],
"statuses": [{
"id": "gBGGFlB5YjhvAgnhuF1qIUvCo7A",
"recipient_id": "[PHONE_NUMBER]",
"type": "payment",
"status": "[TRANSACTION_STATUS]",
"payment": {
"reference_id": "[REFERENCE_ID]",
"amount": {
"value": 21000,
"offset": 100
},
"currency": "INR",
"receipt": "receipt-value",
"notes": {
"key1": "value1",
"key2": "value2"
},
"udf1": "udf1-value",
"udf2": "udf2-value",
"udf3": "udf3-value",
"udf4": "udf4-value",
},
"timestamp": "notification_timestamp"
}]
},
"field": "messages"
}]
}]
}
```
### Step 3. Confirm Payment
After receiving the payment status change notification, or at any time, the business can look up the status of the payment or transaction. To do that, businesses must use this [endpoint ](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/payments#get-payments)with the reference ID.
Businesses should expect a response in the same HTTP session (not in a webhook notification). `payment_configuration` and `reference_id` must be the same as that provided in the initial `order_details` message.
A response can return the following values:
| Field | Description |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reference_id` | The ID provided by the partner in the `order_details` message |
| `status` | The payment status. See the[ payment status ](#payment-status)table for possible values. Note that this is not the same as transaction status. |
| `currency` | The currency for this payment. Currently the only supported value is `INR`. |
| `total_amount` |
The total amount for this payment. This object contains the following fields:
offset integer
Required. Must be 100 for INR.
value integer
Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
|
| `transactions` |
Required.
The list of transactions for this payment. Each transaction object contains the following fields:
id string
Required. The alpha-numeric ID of the payment gateway transaction.
type string
Required. The payment type for this transactions. Only, razorpay or payu are supported.
status string
Required. The status of the transaction. Can be one of pending or success.
At most one transaction can have a success status.
created\_timestamp integer
Required. Time when transaction was created in epoch seconds.
updated\_timestamp integer
Required. Time when transaction was last updated in epoch seconds.
refunds array
Optional. The list of refunds for this order. Each refund object contains the following fields:
id string Required. The alpha-numeric ID of the refund.
amount object Required. The total amount of the refund.
speed\_processed string Required. Speed by which refund was processed. Can be one of instant or normal.
status string Required. The status of the refund. Can be one of pending, success or failed.
created\_timestamp integer Required. Time when refund was created in epoch seconds.
updated\_timestamp integer Required. Time when refund was last updated in epoch seconds.
|
|
receipt
string
|
Optional.
Supported for only Razorpay PG, this contains the receipt-value sent as part of Order Details message.
|
|
notes
object
|
Optional.
Supported for only Razorpay PG, this contains the key-value pairs sent as part of Order Details message.
|
|
udf1-4
string
|
Optional.
Supported for only PayU PG, this contains string values sent as part of Order Details message.
|
#### **Payment Status**
| Status | Description |
| ---------- | ----------------------------------------------------------------------------------- |
| `new` | The partner sent an `order_details` message but the user didn’t start a payment yet |
| `pending` | The user started the payment process and the payment object was created |
| `captured` | The payment was captured |
| `canceled` | The payment was canceled by the user and no retry is possible |
| `failed` | The payment attempt failed but the user can retry |
A successful response looks like this:
```json
{
"payments": [{
"reference_id": "reference-id-value",
"status": "status-of-payment",
"currency": "INR",
"total_amount": {
"value": 21000,
"offset": 100
},
"transactions": [
{
"id": "[PG-TXN-ID]",
"type": "razorpay/payu",
"status": "success",
"created_timestamp": "CREATED_TIMESTAMP",
"updated_timestamp": "UPDATED_TIMESATMP",
"refunds": [
{
"id": "[REFUND-ID]",
"amount": {
"value": 100,
"offset": 100
},
"speed_processed": "instant/normal",
"status": "success",
"created_timestamp": "CREATED_TIMESTAMP",
"updated_timestamp": "UPDATED_TIMESATMP",
}
],
}
],
"receipt": "receipt-value",
"notes": {
"key1": "value1",
"key2": "value2"
},
"udf1": "udf1-value",
"udf2": "udf2-value",
"udf3": "udf3-value",
"udf4": "udf4-value"
}]
}
```
In the case of any errors, this is the response:
```json
{
"errors": [{
"code": "",
"title": "",
"details": "<details description of error>"
}]
}
```
For all errors that can be returned and guidance on how to handle them, see [Errors while Messaging](https://docs.360dialog.com/partner/messaging/commerce-and-payments/payments-india-only/broken-reference)
### Step 4. Update Order Status
{% hint style="info" %}
Businesses *must* send updates to their order using the `order_status` message instead of text messages since the latest status of an order displayed on the order-details-page is only based on `order_status` messages.
{% endhint %}
To notify the customer with updates to an order, you can send an `interactive` message of type `order_status` as shown below:
```json
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "interactive",
"interactive": {
"type": "order_status",
"body": {
"text": "your-text-body-content"
},
"action": {
"name": "review_order",
"parameters": {
"reference_id": "reference-id-value",
"order": {
"status": "processing | partially_shipped | shipped | completed | canceled",
"description": "optional-text"
}
}
}
}
}
```
The following table describes the fields in the `order_status` interactive message:
| Object | Description |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><code>type</code></p><p>string</p> | **Required.** Must be "order\_status" |
| <p><code>body</code></p><p>object</p> | <p><strong>Required.</strong></p><p>An object with the body of the message. The object contains the following field:</p><p><code>text</code> string</p><ul><li><strong>Required</strong> if <code>body</code> is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters</li></ul> |
| <p><code>footer</code></p><p>object</p> | <p><strong>Optional.</strong></p><p>An object with the footer of the message. The object contains the following field:</p><p><code>text</code> string</p><ul><li><strong>Required</strong> if <code>footer</code> is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters</li></ul> |
| <p><code>action</code></p><p>object</p> | <p><strong>Required.</strong></p><p>An action object you want the user to perform after reading the message. This action object contains the following fields:</p><p><code>name</code> string</p><ul><li><strong>Required</strong>. Must be "review\_order".</li></ul><p><code>parameters</code> object</p><ul><li>See <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/pg#paramobject-orderstatus">Parameters Object</a> for information</li></ul> |
The `parameters` object contains the following fields:
| Value | Description |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><code>reference\_id</code></p><p>string</p> | <p><strong>Required.</strong></p><p>The ID sent by the business in the <code>order\_details</code> message</p> |
| <p><code>order</code></p><p>object</p> | <p><strong>Required.</strong> This object contains the following fields:</p><p><code>status</code> string \* <strong>Required.</strong> The new order <code>status</code>. Must be one of <code>processing</code>, <code>partially\_shipped</code>, <code>shipped</code>, <code>completed</code>, <code>canceled</code>.</p><p><code>description</code> string \* <strong>Optional.</strong> Text for sharing status related information in <code>order\_details</code>. Could be useful while sending cancellation. Max character limit is 120 characters.</p> |
`order_status` message introduces two new errors that are summarized below.
| Error Code | Description |
| ---------------------------------- | --------------------------------------------------------------- |
| `2046` - Invalid status transition | The order status transition is not allowed. |
| `2047` - Cannot cancel order | Cannot cancel the order since the user has already paid for it. |
**Product Experience**
Customers receive each `order_status` update as a separate message in their chat thread, that references their original `order_details` message as shown below (left). The order details page always displays the latest valid status communicated to the customer using the `order_status` message as shown below (right).
<div><figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2F2le4gBt7maeKpGWfTiJD%2Fimage15.png?alt=media&token=7d680493-875f-46b5-9e2f-fe31f419482b" alt="" width="180"><figcaption></figcaption></figure> <figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2FjSe38NMXDnjHWkHBTWeq%2Fimage16.png?alt=media&token=ca41b746-b8ee-4a45-9807-ef5dacc14a5e" alt="" width="180"><figcaption></figcaption></figure></div>
**Supported Order Status and Transitions**
Currently we support the following order status values:
| Value | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending` | User has not successfully paid yet |
| `processing` | User payment authorized, merchant/partner is fulfilling the order, performing service, etc. |
| `partially-shipped` | A portion of the products in the order have been shipped by the merchant |
| `shipped` | All the products in the order have been shipped by the merchant |
| `completed` | The order is completed and no further action is expected from the user or the partner/merchant |
| `canceled` | The business would like to cancel the `order_details` message for the order/invoice. The status update will fail if there is already a `successful` or `pending` payment for this `order_details` message |
Order status transitions are restricted for consistency of consumer experience. Allowed status transitions are summarized below:
* Initial status of an order is always `pending`, which is sent in `order_details` message.
* `canceled` and `completed` are terminal status and cannot be updated to any other status.
* `pending` can transition to any of the other statuses including `processing`, `shipped`, `partially-shipped`.
* `processing`, `shipped` and `partially-shipped` are equivalent statuses and can transition between one another or to one of the terminal statuses.
<figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2FQWBTQsut3TI2c6pL4Bkh%2F342705763_209326185156211_2343519052426902684_n.png?alt=media&token=23614651-a7a3-4d22-90bb-17fdec0a3379" alt="" width="375"><figcaption></figcaption></figure>
Upon sending an `order_status` message with an invalid transition, you will receive an error webhook with the error code `2046` and message "*New order status was not correctly transitioned.*"
**Canceling an Order**
An order can be `canceled` by sending an `order_status` message with the status `canceled`.
The customer cannot pay for an order that is canceled. The customer receives an `order_status` message (left) and order details page is updated to show that the order is canceled and the "Secure Checkout" button removed (right). The *optional* text shown below "Order canceled" on the order details page can be specified using the `description` field in the `order_status` message.
An order can be canceled only if the user has not already paid for the order. If the user has paid and you send an `order_status` message with `canceled` status, you will receive an error webhook with error code `2047` and message "*Could not change order status to 'canceled'*".
### Step 5: Reconcile Payments
Please note that neither 360dialog nor WhatsApp supports payment reconciliations. Businesses should use their payment gateway account to reconcile the payments using the `reference_id` provided in the `order_details` messages and the `id` of the transactions returned as part of the payment lookup query.
## Security Considerations for Payments API
{% hint style="info" %}
Review our [WABA Security](https://docs.360dialog.com/partner/onboarding/integration-best-practices/architecture-and-security) documentation.
{% endhint %}
* Businesses should not rely solely on the status of the transaction provided in the webhook and must use payment lookup API to retrieve the statuses directly from WhatsApp.
* To ensure secure financial processing, payment configurations such as the business’ VPA shared by all WhatsApp phone numbers **must belong to the same Business Manager account**. If you wish to separate payments for different phone numbers, then additional [Business Manager Accounts must be created. ](https://docs.360dialog.com/partner/messaging/commerce-and-payments/payments-india-only/broken-reference)
* Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks.
<br>
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.360dialog.com/partner/messaging/commerce-and-payments/payments-india-only/receive-whatsapp-payments-via-payments-gateway.md?ask=<question>
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
