Receive WhatsApp Payments via Stripe (Singapore only)
Payments API Integration with Stripe allow customers to pay for their orders without leaving the WhatsApp customer app
On this page, you will learn how to send customers a bill, so that the client can complete their order by paying the business with Stripe without having to leave WhatsApp app.
The Stripe Payment Integration is available only for businesses registered in Singapore using the 360dialog WhatsApp Business API with phone numbers from Singapore. If you are eligible, please get in touch with our Support Team to enable the Payments feature.
Currently, customers browse business catalogs, add products to their cart, and send orders with the set of commerce messaging solutions, which includes Multi Product Message, and Product Detail Page. Now, with the Payments API, businesses can send clients a Stripe bill so the customer can complete their order by paying the business without having to leave WhatsApp. See how it works below:
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 must wait for a payment or transaction status update. There are three payment statuses currently supported by WhatsApp:
pending
, captured
, and failed
. Each payment can include one or more transactions.Notifications will be transmitted when the transaction
status
changes, but do not solely rely on these webhook notifications due to security reasons. WhatsApp provides a payment-lookup API to retrieve the payment statuses directly, and, is possible to query payment status using different phone numbers under the same Business Manager account.Please note that neither 360dialog nor WhatsApp supports payment reconciliations.
You must reconcile the payment with Stripe using the
reference_id
of the order or transaction_id
of transaction.The purchase flow has the following steps in the WhatsApp customer app:
- 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.
- 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 Secure Checkout button, a secure in-app webview will appear for the user to pay for the order.
- 4.Once the payment has been confirmed, the business will be notified of the latest payment status using a webhook notification as shown in section 2 below.
- 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 below) that refers to the original order details message and also updates the status displayed on the order details page.

Businesses should add a Stripe payment configuration to the WhatsApp Business Account to receive payments on WhatsApp.
Accounts created with Embbeded-Sign up model (Shared WABA) can add it using the 'Direct pay methods' page under 'Singapore' in the WhatsApp Business Manager as shown below. In addition, only Admin and Financial Editors users of such a business are eligible connect the Stripe accounts.
If the WABA was created using the OBO (On Behalf-Of) model, please reach out to our support team and we will assist you during this step.

A payment configuration allows businesses to link their Stripe 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 payment link using the associated Stripe account indicated in the request. This link opens up in an in-app webview so consumers can pay for their order. After linking your Stripe 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.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.
The following sequence diagram demonstrates the typical integration flow for WA Payments API:

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
|
footer object | Optional. An object with the footer of the message. The object contains the following field:
text string
|
action object | Required. An action object you want the user to perform after reading the message. This action object contains the following fields:
name string
parameters object |
Object | Description |
---|---|
reference_id string | Required. 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 the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness. |
type string | Required. Must be one of “ digital-goods ” or “physical-goods ” |
beneficiaries array **Beneficiary information isn't shown to users but is needed for legal and compliance reasons. | Required for shipped physical-goods. 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: name string
address_line1 string
address_line2 string
city string
state string
country string
postal_code string
|
payment_type string | Required. Must be " p2m-lite:stripe ". |
payment_configuration
string **When payment_configuration 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. | 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 as shown here. |
currency string | Required. The currency for this order. Must be SGD . |
total_amount object | Required. The total_amount object contains the following fields:
offset string
value string
total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value .
The smallest amount supported by Stripe is 0.50 USD or equivalent. |
order object | Required. |
Object | Description |
---|---|
status string | Required. Only supported value in the order_details message is pending . In an order_status message, status can be: pending , processing , partially-shipped , shipped , completed or canceled . |
items object | Required. An object with the list of items for this order, containing the following fields:
retailer_id string
name string
amount string
sale_amount string
quantity string
|
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 string
value string
|
tax object | Required. The tax information for this order which contains the following fields:
offset string
value string
description string
|
shipping object | Optional. The shipping cost of the order. The object contains the following fields:
offset string
value string
description string
|
discount object | Optional. The discount for the order. The object contains the following fields:
offset string
value string
description string
discount_program_name string
|
catalog_id object | Optional. Unique identifier of the Facebook catalog being used by the business. |
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 |
By the end, the interactive object should look something like this:
{
"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"
}
}
}
}
}
}
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
.{
"recipient_type": "individual",
"to" : "whatsapp-id", // WhatsApp ID of the recipient
"type": "interactive",
"interactive":{
// The interactive object
}
}
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:{
"messages": [{
"id": "{message-id}"
}]
}
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 "Secure Checkout" button that opens up an in-app webview powered by Stripe (right).
Businesses receive updates via WhatsApp 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
|
timestamp string | Required. Timestamp for the webhook. |
A webhook notification for an updated transaction status looks like this:
POST /
{
"statuses": [{
"id": "gBGGFlB5YjhvAgnhuF1qIUvCo7A",
"from": "16315555555",
"type": "payment",
"status": "new-transaction-status",
"payment": {
"reference_id": "reference-id-value"
},
"timestamp": "1610561171"
}]
}
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 make a
GET
call to /v1/payments/{payment-config-id}/{ref-id}
, using the reference ID provided in the order_details
message. Businesses should expect a response in the same HTTP session (not in a webhook notification). A response can return the following values:
Field | Description |
---|---|
reference_id string | Required. The ID sent by the business in the order_details message |
status string | Required. Status of the payment for the order. Can be one of, pending , canceled , captured , failed .
Refer the table below for what these statuses mean. |
currency string | Required. The currency for this payment. Currently the only supported value is SGD . |
total_amount object | Required. The total amount for this payment. It contains the following fields: offset integer
value integer
|
transactions array | The list of transactions for this payment. Contains the following fields:
id string
type string
status string
created_timestamp integer
updated_timestamp integer
|
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 |
An example successful response looks like this:
{
"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
}
]
}]
}
In the case of any errors, this is the response:
{
"errors": [{
"code": ERROR_CODE_INT,
"title": "[ERROR_TITLE]",
"details": "[ERROR_DESCRIPTION]"
}]
}
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
messageTo notify the customer with updates of an order, you can send an
interactive
message of type order_status
as shown below:{
"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"
}
}
}
}
}
The following table describes the fields in the
order_status
interactive message:Object | Description |
---|---|
type string | Required. Must be "order_status" |
body object | Required. An object with the body of the message. The object contains the following field: text string
|
footer object | Optional. An object with the footer of the message. The object contains the following field: text string
|
action object | Required. An action object you want the user to perform after reading the message. This action object contains the following fields: name string
parameters object |
The
parameters
object contains the following fields:Value | Description |
---|---|
reference_id string | Required. The ID sent by the business in the order_details message |
order object | Required. This object contains the following fields: status string * Required. The new order status . Must be one of processing , partially_shipped , shipped , completed , canceled . description string * Optional. Text for sharing status related information in order_details . Could be useful while sending cancellation. Max character limit is 120 characters. |
order_status
message introduces two new errors that are summarized below.Customers receive each
order_status
update as a separate message in their chat thread, that references their original order_details
message as shown below.
The order details page always displays the latest valid status communicated to the customer using the
order_status
message as shown below.
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 inorder_details
message. canceled
andcompleted
are terminal status and cannot be updated to any other status.pending
can transition to any of the other statuses includingprocessing
,shipped
,partially-shipped
.processing
,shipped
andpartially-shipped
are equivalent statuses and can transition between one another or to one of the terminal statuses.

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."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'".
Merchant should always post this order-status message to consumer after reciving transaction updates for an order.
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.- Businesses should comply with local security and regulatory requirements in Singapore.
- 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.
- Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks.
Last modified 3mo ago