For AI agents: visit https://developer.rmlconnect.net/route-mobile-project/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.
Use the WhatsApp Payments API to send order details, collect payments through UPI or supported payment gateways, update customers on order status, and retrieve payment status.
Availability and prerequisites
This solution is available only in India. Use an Indian bot phone number with the +91 country code.
Before you send a payment message:
Provide the required details to RML:
Bot phone number with the +91 country code.
WhatsApp Business Account ID (WABA ID) for that number.
Request a test account from the payment gateway (PG) you want to test.
Set to Razorpay or PayU when you have linked that payment gateway to accept payments.
payment_gateway.configuration_name
Yes
Name of the pre-configured payment configuration. Must match the payment configuration in WhatsApp Business Manager and must not exceed 60 characters.
Shared request fields
Top-level fields
Field
Required
Description
phone
Yes
Mobile number for the payment message recipient.
enable_acculync
No
Enables Acculync URL shortening.
body
Yes
Message body. Emojis and markdown are supported. Maximum length: 1024 characters.
footer
Yes
Footer text. Emojis, markdown, and links are supported. Maximum length: 60 characters.
image
No
Custom image displayed to the user. When you use image, the items array is limited to 10 items and cannot be used with retailer_id or catalog_id.
payment
Yes
Payment details for the order.
extra
No
Additional payment message value.
payment object
Field
Required
Description
reference_id
Yes
Unique order or invoice identifier. Case-sensitive; cannot be empty; may contain English letters, numbers, underscores, dashes, and dots; maximum 35 characters. Use a unique value for each order_details message. For multiple messages for the same order, add a sequence number such as BM345A-12.
payment_configuration
Required for UPI flow
Payment configuration for the order sent in an order_details message.
payment_gateway
Required for other payment modes
Gateway configuration. See the payment gateway fields in the other payment modes flow.
order_type
Yes
Transaction or purchase information, including item names, quantities, and delivery details.
product_type
Yes
Product type, such as digital-goods, clothing and apparel, electronics, or home appliances.
address
Yes
Recipient or shipping address.
items
Yes
Order line items.
subtotal_amount
Yes
Total charges before discounts, taxes, and additional fees.
discount_amount
No
Amount deducted as a price reduction.
discount_description
No
Discount description. Maximum length: 60 characters.
shipping_amount
Yes
Shipping cost.
shipping_description
No
Shipping details.
total_amount
Yes
Total amount to be paid, for example ₹12.34.
tax_amount
Yes
Tax amount added to the total bill.
tax_description
No
Description of the tax obligation.
address object
Field
Required
Description
first_name
Yes
Name of the recipient or business receiving physical goods.
address_line1
Yes
Shipping address, such as door or tower number and street name.
address_line2
No
Shipping address details, such as landmark or area.
city
Yes
Recipient city.
state
Yes
Recipient state.
country
Yes
Recipient country.
postal_code
Yes
Six-digit shipping address ZIP code.
items array
Field
Required
Description
retailer_id
No
Content ID for an order item from your catalog.
catalog_id
No
Facebook catalog identifier used by the business. If you do not provide this field, provide country_of_origin, importer_name, and importer_address inside the item object.
product_name
Yes
Product name that identifies the item.
amount
Yes
Amount value for the item. The source examples use values such as ₹12.34.
quantity
Yes
Number of items in the order. This value must be an integer and cannot be decimal.
expiration_timestamp
No
UTC expiration timestamp in seconds. Minimum threshold: 300 seconds.
expiration_description
No
Expiration explanation. Maximum length: 120 characters.
Order details enhancements
Use these enhancements when you need to guide customers toward a preferred gateway payment option, add gateway-specific data, send a direct UPI deep link, or update an existing order.
Template order details with a preferred payment method
Send the order_details payment experience through an approved WhatsApp message template. In this flow, the payment payload is nested in the media.payment array.
Use in place of payment_gateway to route payment through a merchant-generated UPI deep link.
upi_intent_link.link
Yes
Standard UPI deep link URI with merchant VPA, name, MCC, purpose code, and transaction reference parameters.
Implementation notes
The template-driven example uses media.payment as a single-element array, while interactive examples use payment as an object.
The source shows payment_gateway.notes only for Razorpay. Support and expected structure for other gateways are not documented here.
The only observed preferred_payment_methods[].method values are gpay and cred. Confirm additional values with gateway-specific integration documentation.
The source does not show upi_intent_link and payment_gateway together. Treat their combined use as unconfirmed.
Order status
Send an order_status message to update a customer about an order previously sent through the order_details flow. Use the same reference_id to associate the status update with the original order.
Use this flow to send WhatsApp payment messages through BillDesk. Configure the Payment Configuration Name in the Meta Business Account for the sending WABA before using this request.
Set to false for the BillDesk flow shown in the sample.
body
string
Yes
Message body text.
footer
string
Yes
Message footer text.
type
string
Yes
Fixed value: payment.
image.url
string
Yes
Publicly accessible media URL for the payment card image.
extra
string
No
Free-form passthrough field.
payment object fields
Field
Type
Required
Notes
reference_id
string
Yes
Merchant-side unique order or transaction reference.
order_type
string
Yes
Fixed value: order_details.
product_type
string
Yes
For example, digital-goods.
items[]
array
Yes
At least one line item.
subtotal_amount
number
Yes
Sum of item amounts before tax and shipping.
discount_description
string
No
Discount description.
shipping_amount
number
Yes
Use 0 if not applicable.
shipping_description
string
No
Shipping details.
total_amount
number
Yes
Final payable amount.
tax_amount
number
Yes
Use 0 if not applicable.
tax_description
string
No
Tax description.
address
object
Yes
Recipient shipping or billing address.
payment_gateway
object
Yes
BillDesk gateway configuration.
BillDesk gateway fields
Field
Type
Required
Notes
payment_gateway.type
string
Yes
Must be billdesk.
payment_gateway.configuration_name
string
Yes
Payment Configuration Name provisioned in the Meta Business Account for this WABA.
payment_gateway.billdesk
object
Yes
Mandatory container for BillDesk UDF fields.
billdesk.additional_info1
string
Yes
Mandatory arbitrary string. The request fails if it is omitted.
billdesk.additional_info2 to billdesk.additional_info7
string
No
Additional BillDesk UDF fields.
BillDesk responses and validation
200 OK
{
"message": "message received successfully",
"status": "processing",
"request_id": "799c8216-6afd-11f1-9f4f-0242ac130021"
}
400 Bad Request — additional_info1 missing
{
"message": "please check API docs for more info",
"status": "failed",
"reason": {
"payment": {
"payment_gateway": {
"billdesk": "additional_info1 is mandatory"
}
}
}
}
400 Bad Request — billdesk object missing
{
"message": "please check API docs for more info",
"status": "failed",
"reason": {
"payment": {
"payment_gateway": {
"billdesk": "You need to pass the billdesk json object in body for payment_gateway billdesk"
}
}
}
}
Implementation notes
Omitting payment_gateway.billdesk returns a distinct 400 error from omitting additional_info1.
The source only confirms that additional_info1 is mandatory. Validation behavior for additional_info2 through additional_info7 is not documented.
The source does not document validation behavior for an invalid configuration name, gateway type values other than billdesk, multiple or zero items, retry behavior, idempotency, rate limits, or payment status webhooks.
