Your business can enable customers to pay for their orders through our payment partner Stripe without leaving WhatsApp. Businesses can send customers order_details
messages, then get notified about payment status updates via webhook notifications.
This feature is only available for businesses based in Singapore and their Singapore customers.
Currently, customers browse business catalogs, add products to cart, and send orders with our set of commerce messaging solutions, which includes Single Product Message, Multi Product Message, and Product Detail Page . Now, 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.
Our payments solution is currently enabled by Stripe, a global third-party payments service provider. You must have a Stripe account in order to receive payments on WhatsApp. We expect more payment providers to be added in the future.
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 webhooks notifications due to security reasons. WhatsApp also provides a payment lookup API that can be used to retrieve the payment statuses directly anytime.
In the WhatsApp customer app, the purchase flow has the following steps:
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.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.To receive payments on WhatsApp, you must add a payment configuration to your WhatsApp Business Account. You can create a payment configuration for your WhatsApp Business Account using the 'Direct pay methods' page under 'Singapore' in your WhatsApp Business Manager as shown below.
Only the business that owns the WhatsApp Business Account can connect their Stripe account to a payment configuration. We only support Embedded and Direct signups at this time.
In addition, only Admin and Financial Editors of such a business can connect the Stripe accounts.
A payment configuration allows you to link your 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. 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 Payments API:
To send an order_details
message, businesses must assemble an interactive object of type order_details
with the following components:
type
string
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 in the catalog (if using catalog) as the header.
body
object
Required.
An object with the body of the message. The object contains the following field:
text
string
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 field:
text
string
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:
name
string
parameters
object
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 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
string
Required.
Must be one of “digital-goods” or “physical-goods”
beneficiaries
array
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:
Beneficiary information isn't shown to users but is needed for legal and compliance reasons.
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
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 .
When payment_configuration
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.
currency
string
Required.
The currency for this order. Must be "SGD".
total_amount
object
Required.
The total_amount
object contains the following fields:
offset
integer
value
integer
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.
See Order Object for more information.
status
string
Required.
Only supported value in 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
integer
subtotal
object
Required.
The value must be equalto sum of item.amount.value
* item.amount.quantity
for all items in the order.
The following fields are part of the subtotal
object:
offset
string
100
for SGD
value
string
tax
object
Required.
The tax information for this order which contains the following fields:
offset
string
100
for SGD
value
string
description
string
shipping
object
Optional.
The shipping cost of the order. The object contains the following fields:
offset
string
100
for SGD
value
string
description
string
discount
object
Optional.
The discount for the order. The object contains the following fields:
offset
string
100
for SGD
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 the order. Business must define the following fields inside this object:
timestamp
string
description
string
By the end, the interactive object should look something like this:
{ "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": "expiration-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" }, "tax": { "value": 10000, "offset": 100, "description": "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
.
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "PHONE_NUMBER", "type": "interactive", "interactive": { // interactive object here } }
These are parameters common to all message types .
Make a POST call to the /[PHONE_NUMBER_ID]/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.
{ "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 .
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:
id
string
Required.
Webhook ID for the notification.
recipient_id
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
order_details
message. timestamp
string
Required.
Timestamp for the webhook.
Here is an example status webhook of type payment
:
POST / { "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": "new-transaction-status", "payment": { "reference_id": "reference-id-value" }, "timestamp": "notification_timestamp" }] }, "field": "messages" }] }] }
For more information about other statuses, see Components, Statuses Object ..
After receiving the payment status webhook, or at any time, the business can look up the status of the payment for the order. To do that, businesses must make a GET call to the payments endpoint as shown here:
GET /[PHONE_NUMBER_ID]/payments/{payment_configuration}/{reference_id}
where payment_configuration
and reference_id
are same as that sent in the order_details
message.
Businesses should expect a response in the same HTTP session (not in a webhook notification) that contains the following fields:
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 new
, 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
Required.
The list of transactions for this payment. Each transaction object contains the following fields:
id
string
type
string
p2m-lite
is supported. status
string
pending
, success
or failed
.At most one transaction can have a success
status.
created_timestamp
integer
updated_timestamp
integer
Status | Description |
---|---|
|
The user started the payment process and the payment object was created |
|
The payment was captured |
|
The payment was canceled by the user and no retry is possible |
|
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, response is similar to an error response for /[PHONE_NUMBER_ID]/messages
endpoint. For all errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes
.
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.
To notify the customer with updates to an order, you can send an interactive
message of type order_status
as shown below.
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "[PHONE_NUMBER]", "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:
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
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 field:
text
string
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:
name
string
parameters
object
The parameters
object contains the following fields:
Value | Description |
---|---|
string |
Required. The ID sent by the business in the |
object |
Required.This object contains the following fields: |
order_status
message introduces two new errors that are summarized below.
Error Code | Description |
---|---|
|
The order status transition is not allowed. More details here . |
|
Cannot cancel the order since the user has already paid for it. More details here . |
For all other errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes .
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).
Currently we support the following order status values:
Value | Description |
---|---|
|
User has not successfully paid yet |
|
User payment authorized, merchant/partner is fulfilling the order, performing service, etc. |
|
A portion of the products in the order have been shipped by the merchant |
|
All the products in the order have been shipped by the merchant |
|
The order is completed and no further action is expected from the user or the partner/merchant |
|
The partner/merchant would like to cancel the |
Order status transitions are restricted for consistency of consumer experience. Allowed status transitions are summarized below:
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.Upon sending an order_status
message with an invalid transition, you will receive an error webhook with the error code 2046
and message "The order status cannot be updated from the existing value to the new one."
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 "The order could not be cancelled."
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.
WhatsApp does not support payment reconciliations. Businesses should comply with local security and regulatory requirements in Singapore. They 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. Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks.