# Receive WhatsApp Payments via Stripe

The following sequence diagram demonstrates the typical integration flow for WA Payments API:

<div align="left"><figure><img src="https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2FNGEAXGd4TXBBpuEyDWZb%2Fimage.png?alt=media&#x26;token=0c973e9e-4add-4ea8-9ca7-2304eec85f60" alt="" width="563"><figcaption></figcaption></figure></div>

## Integration Steps

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/docs/messaging/message-types/interactive).

{% stepper %}
{% step %}

#### 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                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p><code>type</code></p><p>object</p>   | <p><strong>Required</strong>.</p><p>Must be "<code>order\_details</code>"</p>                                                                                                                                                                                                                                                                                                                                      |
| <p><code>header</code></p><p>object</p> | <p><strong>Optional</strong>.</p><p>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</p>                                                                                                                                                                                                                              |
| <p><code>body</code></p><p>object</p>   | <p><strong>Required</strong>.</p><p>An object with the body of the message. <br><br>The object contains the following field:<br></p><p><code>text</code> string</p><ul><li><strong>Required</strong> if body 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:<br></p><p><code>text</code> string</p><ul><li><strong>Required</strong> if footer 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:<br></p><p><code>name</code> string</p><ul><li><strong>Required</strong>. Use "<code>review\_and\_pay</code>"</li></ul><p><code>parameters</code> object</p><ul><li>See <a href="#parameters-object">Parameters Object</a> for information</li></ul> |

<details>

<summary><strong>Parameters Object</strong></summary>

<table><thead><tr><th width="196.44268798828125">Object</th><th>Description</th></tr></thead><tbody><tr><td><p><code>reference_id</code></p><p>string</p></td><td><p><strong>Required</strong>.</p><p>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.<br></p><p>The <code>reference_id</code> must be unique for each <code>order_details</code> message for the same business. If the partner would like to send multiple <code>order_details</code> messages for the same order, invoice, etc. it is recommended to include a sequence number in the <code>reference_id</code> (for example, "BM345A-12") to ensure <code>reference_id</code> uniqueness.</p></td></tr><tr><td><p><code>type</code></p><p>string</p></td><td><p><strong>Required</strong>.</p><p>Must be one of “<code>digital-goods</code>” or “<code>physical-goods</code>”</p></td></tr><tr><td><p><code>beneficiaries</code></p><p>array</p><p></p><p>**Beneficiary information isn't shown to users but is needed for legal and compliance reasons.</p></td><td><p></p><p><strong>Required for shipped physical-goods.</strong></p><p>An array of beneficiaries for this order. A beneficiary is an intended recipient for the delivery of physical goods in the order. It contains the following fields:</p><p></p><p><code>name</code> string</p><ul><li><strong>Required.</strong> Name of the individual or business receiving the physical goods. Cannot exceed 200 characters</li></ul><p><code>address_line1</code> string</p><ul><li><strong>Required.</strong> Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters</li></ul><p><code>address_line2</code> string</p><ul><li><strong>Optional.</strong> Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters</li></ul><p><code>city</code> string</p><ul><li><strong>Optional.</strong> Name of the city.</li></ul><p><code>state</code> string</p><ul><li><strong>Optional.</strong> Name of the state.</li></ul><p><code>country</code> string</p><ul><li><strong>Required.</strong> Must be "Singapore".</li></ul><p><code>postal_code</code> string</p><ul><li><strong>Required.</strong> 6-digit postal code of shipping address.</li></ul></td></tr><tr><td><p><code>payment_type</code></p><p>string</p></td><td><p><strong>Required</strong>.</p><p>Must be "<code>p2m-lite:stripe</code>".</p></td></tr><tr><td><p><code>payment_configuration</code><br>string</p><p></p><p>**When <code>payment_configuration</code> is invalid, the customer will be unable to pay for their order. In case you experience any errors, please get in touch with our support team as soon as possible.</p></td><td><p><strong>Required</strong>.</p><p>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 as shown <a href="#link-your-payment-account">here</a>. </p></td></tr><tr><td><p><code>currency</code></p><p>string</p></td><td><p><strong>Required</strong>.</p><p>The currency for this order. Must be <code>SGD</code>.</p></td></tr><tr><td><p><code>total_amount</code></p><p>object</p></td><td><p><strong>Required</strong>.</p><p>The <code>total_amount</code> object contains the following fields:<br></p><p><code>offset</code> string</p><ul><li><strong>Required</strong>. Must be <code>100</code> for <code>SGD</code>.</li></ul><p><code>value</code> string</p><ul><li><strong>Required</strong>. Positive integer representing the amount value multiplied by offset. For example, S$12.34 has value 1234.</li></ul><p><code>total_amount.value</code> must be equal to <code>order.subtotal.value</code> + <code>order.tax.value</code> + <code>order.shipping.value</code> - <code>order.discount.value</code>.<br></p><p>The smallest amount supported by Stripe is 0.50 USD or equivalent.</p></td></tr><tr><td><p><code>order</code></p><p>object</p></td><td><p><strong>Required</strong>.</p><p>See <a href="#order-object">Order Object</a> for more information.</p></td></tr></tbody></table>

</details>

<details>

<summary><strong>Order Object</strong></summary>

<table><thead><tr><th width="172.4427490234375">Object</th><th>Description</th></tr></thead><tbody><tr><td><p><code>status</code></p><p>string</p></td><td><p><strong>Required</strong>.</p><p>Only supported value in the <code>order_details</code> message is <code>pending</code>.</p><p></p><p>In an <code>order_status</code> message, status can be: <code>pending</code>, <code>processing</code>, <code>partially-shipped</code>, <code>shipped</code>, <code>completed</code> or <code>canceled</code>.</p></td></tr><tr><td><p><code>items</code></p><p>object</p></td><td><p><strong>Required</strong>.</p><p>An object with the list of items for this order, containing the following fields:<br></p><p><code>retailer_id</code> string</p><ul><li><strong>Required</strong>. Unique identifier of the Facebook catalog being used by the business</li></ul><p><code>name</code> string</p><ul><li><strong>Required</strong>. The item’s name to be displayed to the user. Cannot exceed 60 characters</li></ul><p><code>amount</code> string</p><ul><li><strong>Required</strong>. The price per item</li></ul><p><code>sale_amount</code> string</p><ul><li><strong>Optional</strong>. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount</li></ul><p><code>quantity</code> string</p><ul><li><strong>Required</strong>. The number of items in this order</li></ul></td></tr><tr><td><p><code>subtotal</code></p><p>object</p></td><td><p><strong>Required</strong>.</p><p>The value must be equal to sum of <code>order.amount.value</code> * <code>order.amount.quantity</code>. Refer to <code>total_amount</code> description for explanation of offset and value fields<br></p><p>The following fields are part of the subtotal object:<br></p><p><code>offset</code> string</p><ul><li><strong>Required</strong>. Must be <code>100</code> for <code>SGD</code></li></ul><p><code>value</code> string</p><ul><li><strong>Required</strong>. Positive integer representing the amount value multiplied by offset. For example, S$12.34 has value 1234</li></ul></td></tr><tr><td><p><code>tax</code></p><p>object</p></td><td><p><strong>Required</strong>.</p><p>The tax information for this order which contains the following fields:<br></p><p><code>offset</code> string</p><ul><li><strong>Required</strong>. Must be <code>100</code> for <code>SGD</code></li></ul><p><code>value</code> string</p><ul><li><strong>Required</strong>. Positive integer representing the amount value multiplied by offset. For example, S$12.34 has value 1234</li></ul><p><code>description</code> string</p><ul><li><strong>Optional</strong>. Max character limit is 60 characters</li></ul></td></tr><tr><td><p><code>shipping</code></p><p>object</p></td><td><p><strong>Optional</strong>.</p><p>The shipping cost of the order. The object contains the following fields:<br></p><p><code>offset</code> string</p><ul><li><strong>Required</strong>. Must be <code>100</code> for <code>SGD</code></li></ul><p><code>value</code> string</p><ul><li><strong>Required</strong>. Positive integer representing the amount value multiplied by offset. For example, S$12.34 has value 1234</li></ul><p><code>description</code> string</p><ul><li><strong>Optional</strong>. Max character limit is 60 characters</li></ul></td></tr><tr><td><p><code>discount</code></p><p>object</p></td><td><p><strong>Optional</strong>.</p><p>The discount for the order. The object contains the following fields:<br></p><p><code>offset</code> string</p><ul><li><strong>Required</strong>. Must be <code>100</code> for <code>SGD</code></li></ul><p><code>value</code> string</p><ul><li><code>Required</code>. Positive integer representing the amount value multiplied by offset. For example, S$12.34 has value 1234</li></ul><p><code>description</code> string</p><ul><li><strong>Optional</strong>. Max character limit is 60 characters</li></ul><p><code>discount_program_name</code> string</p><ul><li><strong>Optional</strong>. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters</li></ul></td></tr><tr><td><p><code>catalog_id</code></p><p>object</p></td><td><p><strong>Optional</strong>.</p><p>Unique identifier of the Facebook catalog being used by the business.</p></td></tr><tr><td><p><code>expiration</code></p><p>object</p></td><td><p><strong>Optional</strong>.</p><p>Expiration for that order. Business must define the following fields inside this object:<br></p><p><code>timestamp</code> string – UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds<br></p><p><code>description</code> string – Text explanation for expiration. Max character limit is 120 characters</p></td></tr></tbody></table>

</details>

<details>

<summary>By the end, the interactive object should look something like this:</summary>

```json
{
  "recipient_type": "individual",
  "to": "[recipient-whatsapp-id]",
  "type": "interactive",
  "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_type": "p2m-lite:stripe",
        "payment_configuration": "unique-payment-config-id",
        "currency": "SGD",
        "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": 5,
            "sale_amount": {
              "value": 10000,
              "offset": 100
            }
          }],
          "subtotal": {
            "value": 10000,
            "offset": 100
          },
          "shipping": {
            "value": 10000,
            "offset": 100,
            "description": "optional_text"
          },
          "discount": {
            "value": 10000,
            "offset": 100,
            "description": "optional_text",
            "discount_program_name": "optional_text"
          }
        }
      }
    }
  }
}
```

</details>
{% endstep %}

{% step %}

#### 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
{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id", // WhatsApp ID of the recipient
  "type": "interactive",
  "interactive":{
    // The interactive object  
   }
}
```

These are [parameters common to all message types](https://developers.facebook.com/docs/whatsapp/api/messages#sending-messages).
{% endstep %}

{% step %}

#### **Make a POST Call to /messages**

Make a POST call to the `/messages`endpoint with the `JSON` object you have assembled in steps 1 and 2. \
\
If your message is sent successfully, you get the following response:

```json
{
  "messages": [{
    "id": "{message-id}"
  }]
}
```

<details>

<summary><strong>Product Experience</strong></summary>

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 "Secure Checkout" button that opens up an in-app webview powered by Stripe (right).

<div align="left"><figure><img src="https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2FpA6eZ6zUNJjMwtmf7GGA%2FScreenshot%202023-05-29%20at%2010.47.38.png?alt=media&#x26;token=23efe1c3-e2fe-4e6c-b9d2-f5ab789cfe85" alt=""><figcaption></figcaption></figure></div>

</details>
{% endstep %}

{% step %}

#### Receive Webhook about Transaction Status

<details>

<summary>Businesses receive updates via <a href="../../webhook">WhatsApp webhooks</a> when the status of the user-initiated transaction changes in a status of type "payment". It contains the following fields:</summary>

| Object                                     | Description                                                                                                                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p><code>id</code></p><p>string</p>        | <p><strong>Required.</strong></p><p>Webhook ID for the notification.</p>                                                                                                                                                 |
| <p><code>from</code></p><p>string</p>      | <p><strong>Required.</strong></p><p>WhatsApp ID of the customer.</p>                                                                                                                                                     |
| <p><code>type</code></p><p>string</p>      | <p><strong>Required.</strong></p><p>For payment status update webhooks, type is "payment".</p>                                                                                                                           |
| <p><code>status</code></p><p>string</p>    | <p><strong>Required.</strong></p><p>Latest status of the payment. Can be one of <code>captured</code>, <code>failed</code> or <code>pending</code>.</p>                                                                  |
| <p><code>payment</code></p><p>object</p>   | <p><strong>Required.</strong></p><p>Contains the following field:</p><p><br></p><p><code>reference\_id</code> string</p><ul><li>Unique reference ID for the order sent in <code>order\_details</code> message.</li></ul> |
| <p><code>timestamp</code></p><p>string</p> | <p><strong>Required.</strong></p><p>Timestamp for the webhook.</p>                                                                                                                                                       |

</details>

A webhook notification for an updated transaction status looks like this:

```json
{
  "statuses": [{
    "id": "gBGGFlB5YjhvAgnhuF1qIUvCo7A",
    "from": "16315555555",
    "type": "payment",
    "status": "new-transaction-status",
    "payment": {
      "reference_id": "reference-id-value"
    },
    "timestamp": "1610561171"
  }]
}
```

{% endstep %}

{% step %}

#### 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.&#x20;

To do that, businesses must make a `GET` call to `/v1/payments/{payment-config-id}/{ref-id}`, using the reference ID provided in the `order_details` message.

<details>

<summary>Businesses should expect a response in the same HTTP session (not in a webhook notification). A response can return the following values:</summary>

| Field                                          | 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>status</code></p><p>string</p>        | <p><strong>Required.</strong></p><p>Status of the payment for the order. Can be one of, <code>pending</code>, <code>canceled</code>, <code>captured</code>, <code>failed</code>.<br></p><p>Refer the table below for what these statuses mean.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| <p><code>currency</code></p><p>string</p>      | <p><strong>Required.</strong></p><p>The currency for this payment. Currently the only supported value is <code>SGD</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| <p><code>total\_amount</code></p><p>object</p> | <p><strong>Required.</strong></p><p>The total amount for this payment. It contains the following fields:</p><p><code>offset</code> integer</p><ul><li><strong>Required.</strong> Must be 100.</li></ul><p><code>value</code> integer</p><ul><li><strong>Required.</strong> Positive integer representing the amount value multiplied by offset. For example, S$12.34 has value 1234.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| <p><code>transactions</code></p><p>array</p>   | <p>The list of transactions for this payment. Contains the following fields:<br></p><p><code>id</code> string</p><ul><li><strong>Required</strong>. The alpha-numeric ID of the Stripe transaction.</li></ul><p><code>type</code> string</p><ul><li><strong>Required</strong>. The payment type for this transactions. Only, p2m-lite is supported.</li></ul><p><code>status</code> string</p><ul><li><strong>Required</strong>. The status of the transaction. Can be one of <code>pending</code>, <code>success</code> or <code>failed</code>. \*\*At most one transaction can have a <code>success</code> status.</li></ul><p><code>created\_timestamp</code> integer</p><ul><li><strong>Required</strong>. Time when transaction was created in epoch seconds.</li></ul><p><code>updated\_timestamp</code> integer</p><ul><li><strong>Required</strong>. Time when transaction was last updated in epoch seconds.</li></ul> |

</details>
{% endstep %}

{% step %}

#### **Check Payment Status**

| Status     | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `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                       |

<details>

<summary>An example successful response looks like this:</summary>

```json
{
  "payments": [{
    "reference_id": "BM4321",
    "status": "success",
    "currency": "SGD",
    "total_amount": {
      "value": 21000,
      "offset": 100
    },
    "transactions": [{
        "id": "1243A432",
        "type": "p2m-lite",
        "status": "failed",
        "created_timestamp": 1663021545,
        "updated_timestamp": 1664024213
      },
      {
        "id": "1243A434",
        "type": "p2m-lite",
        "status": "success",
        "created_timestamp": 1664030516,
        "updated_timestamp": 1664040212
      }
    ]
  }]
}
```

</details>

<details>

<summary>In the case of any errors, this is the response:</summary>

```json
{
  "errors": [{
    "code": ERROR_CODE_INT,
    "title": "[ERROR_TITLE]",
    "details": "[ERROR_DESCRIPTION]"
  }]
}
```

{% hint style="info" %}
See [Error Messages](https://docs.360dialog.com/docs/support/api-error-message-list).
{% endhint %}

</details>
{% endstep %}

{% step %}

#### 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` message
{% endhint %}

To notify the customer with updates of 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",
          "description": "optional-text"
        }
      }
    }
  }
}
```

<details>

<summary>The following table describes the fields in the <code>order_status</code> interactive message:</summary>

<table><thead><tr><th width="210">Object</th><th>Description</th></tr></thead><tbody><tr><td><p><code>type</code></p><p>string</p></td><td><strong>Required.</strong> Must be "order_status"</td></tr><tr><td><p><code>body</code></p><p>object</p></td><td><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></td></tr><tr><td><p><code>footer</code></p><p>object</p></td><td><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></td></tr><tr><td><p><code>action</code></p><p>object</p></td><td><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="#parameters-object"> Parameters Object </a>for information</li></ul></td></tr></tbody></table>

</details>

<details>

<summary>The <code>parameters</code> object contains the following fields:</summary>

| 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></p><p><code>status</code> string \* <strong>Required.</strong> </p><p></p><p>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></p><p><code>description</code> string \* <strong>Optional.</strong> </p><p></p><p>Text for sharing status related information in <code>order\_details</code>. Could be useful while sending cancellation. Max character limit is 120 characters.</p> |

</details>

<details>

<summary><code>order_status</code> message introduces two new errors that are summarized below:</summary>

| Error Code                         | Description                                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `2046` - Invalid status transition | The order status transition is not allowed. More details [here](#supported-order-status-and-transitions). |
| `2047` - Cannot cancel order       | Cannot cancel the order since the user has already paid for it. More details [here](#canceling-an-order). |

</details>

<details>

<summary><strong>Product Experience</strong></summary>

Customers receive each `order_status` update as a separate message in their chat thread, that references their original `order_details` message as shown below.

<div align="left"><figure><img src="https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2FpLEI9SqtVdANt52yqzqC%2F342704388_535352198784382_7373073008630498111_n.png?alt=media&#x26;token=d0f1b1db-0c19-47e4-80b2-eb9cdda34245" alt="" width="188"><figcaption></figcaption></figure></div>

The order details page always displays the latest valid status communicated to the customer using the `order_status` message as shown below.

<div align="left"><figure><img src="https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2FG6kWQ4I1gWd1o5JsYYsD%2F342699491_237055468976173_225863445014635916_n.gif?alt=media&#x26;token=92b3795d-bbf2-49ea-91cd-498693e94e86" alt="" width="188"><figcaption></figcaption></figure></div>

</details>
{% endstep %}
{% endstepper %}

## **Supported Order Status and Transitions**

Currently, Meta supports 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 partner/merchant 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://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2Ft32YGjAV9x0AUbr3mBQS%2FScreenshot%202023-05-29%20at%2010.53.52.png?alt=media&#x26;token=b79d75a4-10b4-4426-a9ca-702507c50a61" 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'".

<figure><img src="https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2FWyTxLrt3RkZm0lHe8FIS%2FScreenshot%202023-05-29%20at%2010.54.32.png?alt=media&#x26;token=cf52ca2b-883e-4ce3-81be-d17e9f8a88a5" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
Merchant should always post this order-status message to consumer after reciving transaction updates for an order.
{% endhint %}

## Reconcile Payments

Please note that neither 360dialog nor WhatsApp supports payment reconciliations. Businesses should use their Stripe account to reconcile the payments using the `reference_id` provided in the `order_details` messages and the `transaction_id` of the transactions returned as part of the webhooks or the payment status query.

## Security Considerations for Payments API

{% hint style="info" %}
Review our [WABA Security](https://app.gitbook.com/s/uyAl2S0lSHJaNDXJHo7A/onboarding/integration-best-practices/architecture-and-security) documentation.
{% endhint %}

* Businesses should comply with local security and regulatory requirements in Singapore.&#x20;
* 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 Meta business portfolio**. If you wish to separate payments for different phone numbers, then additional Meta business portfolio must be created.&#x20;
* Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks.