Payments India
Payments API enable businesses to accept payments from their customers via WhatsApp through UPI apps and other payments methods as NetBanking, wallets or cards.
Pre-requisites
To enable payments on WhatsApp, your WhatsApp Business Account (WABA) must be linked to a payment configuration. Each payment configuration is uniquely identified by a name, and you can specify which configuration to use for a particular checkout via the order_details message.
The Onboarding APIs provide a seamless way to manage payment configurations programmatically. With these APIs, you can:
- Retrieve all payment configurations associated with your WhatsApp Business Account.
- Fetch details of a specific payment configuration linked to your WhatsApp Business Account.
- Create a new payment configuration to enable payments.
- Regenerate the OAuth link for a payment gateway to reconnect or update the link between a payment configuration and the payment gateway.
- Delete a payment configuration when it’s no longer needed.
These APIs simplify the process of managing payment setups, ensuring a smooth integration for your WhatsApp payment workflows
Creating a Payment Configuration
Before setting up a payment configuration — whether via API or the WhatsApp Manager UI — you must first accept the WhatsApp Payments Terms of Service. If this step is skipped, you will receive an error when sending the first payment messages until the terms are accepted. The acceptance link is provided in the error response (error code 131005) if you attempt to use the APIs before completing this step.
Option 1: Via WhatsApp Manager
You can set up their payment configuration directly from the WhatsApp Manager interface by following these steps:
- Go to WhatsApp Manager → Account Tools → Payment Configurations and select India.
- Click Add New Configuration and follow the on-screen steps to enter the configuration name, select a payment provider, and complete the gateway authorization.
This is the recommended path if you prefer a guided setup without using the API.
Option 2: Via the Onboarding API (programmatic)
To add a new payment configuration programmatically, use the Create Payment Configuration endpoint. Two configuration types are supported:
- Payment Gateway is for providers like Razorpay, PayU, or Zaakpay.
- UPI VPA is for direct UPI handle integrations.
Examples:
curl -X POST \
'https://graph.facebook.com/v21.0/{WABA_ID}/payment_configuration' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"configuration_name": "my-payment-config",
"purpose_code": "00",
"merchant_category_code": "0000",
"provider_name": "razorpay",
"redirect_url": "https://your-redirect-url.com"
}'
curl -X POST \
'https://graph.facebook.com/v15.0/{WABA_ID}/payment_configuration' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"configuration_name": "my-upi-config",
"purpose_code": "00",
"merchant_category_code": "0000",
"provider_name": "upi_vpa",
"merchant_vpa": "merchantname@bank"
}'
On success, the API returns an OAuth URL that you must visit to authorize the connection between the payment configuration and your payment gateway account:
json{
"oauth_url": "<https://www.facebook.com/payment/onboarding/init/">,
"expiration": 1721687287,
"success": true
}
You need to open the oauth_url and complete the authorization flow before the configuration becomes active. The link expires at the expiration timestamp, if it does, you can regenerate it using the Regenerate OAuth Link endpoint.
Important fields:
| Field | Required | Description |
|---|---|---|
configuration_name | Yes | Unique name for this configuration. Used in order_details messages to select which configuration applies to a checkout |
provider_name | Yes | One of upi_vpa, razorpay, payu, or zaakpay. |
merchant_category_code | No | MCC code for your business category. |
purpose_code | No | Purpose code for the transaction type. |
merchant_vpa | No | Required for upi_vpa. Ttype of your UPI handle. |
redirect_url | No | Where you are redirected after completing the gateway authorization. |
Configuration status, once created, a configuration will be in one of three states:
- Needs_Connecting: The OAuth authorization with the payment gateway is pending
- Needs_Testing: Linked but not yet verified with a test transaction
- Active: Fully configured and ready to process payments
Once you finish configuring the payment, your webhook will receive an update with the configuration status. For more information, refer to the Meta Payments India Docs.
Payments API Implementation Steps
Customers can either browse your WhatsApp catalog, select products, and submit their order, or businesses can identify products the customer has shown interest in purchasing and initiate the order. In both cases, the order details are sent to your system for processing.
Next, you should provide them with an order summary, including details like items, quantities, prices, and the total amount. Along with this summary, share the payment information, such as a UPI payments, payment links or via payment gateways on Whatsapp.
Sending the order_details message
The order_details message can be sent as either an interactive message or a template message. It may include a header, body, action, and footer, but only the body and action are required. The action section will contain the necessary order details that your customers need to complete their payment.
Requirements
Information
You must provide a unique reference_id for each order to avoid duplicates and to allow accurate internal tracking of payment statuses.
If you plan to send multiple order_details messages for the same order or invoice, we recommend including a sequence number in the reference_id to ensure uniqueness.
- Currency must be set to INR (Indian Rupee).
- The total_amount must be subtotal + tax + shipping - discount.
- The action component must be set to review_and_pay.
- Payment Settings: You must specify how you want to receive funds. Supported types in India include:
- UPI Intent: Integrations supported are Dynamic VPA, Cashfree, Billdesk and CCAvenue.
- Payment links and enhaced payment links.
- Payment gateway integration.
- The only supported value for status is pending.
Interactive order_details message examples
For interactive order_details message you can have order_details message with catalog products or not.
The type field inside parameters object is required and specifies the type of goods being paid for. Supported values are digital-goods and physical-goods. When shipping physical goods, you must also include the beneficiaries array — a list of intended recipients for the shipment. Beneficiary information is not shown to users but is required for legal and compliance purposes.
Information
On the order object type is an optional field. Currently, the only supported value is quick_pay. When provided, the Review and Pay button is hidden and only the Pay Now button is displayed in the order details bubble.
The following examples are with digital-goods and physical goods.
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"header": { //header is optional
"type": "image",
"image": {
"link": "https://your-media-url.com/image.jpg"
}
},
"body": {
"text": "Here is your order summary. Please review and complete your payment."
},
"footer": { //optional
"text": "Thank you for shopping with us!"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "order-ref-12345",
"type": "physical-goods",
"beneficiaries": [
{
"name": "Jane Doe",
"address_line1": "B8/733 Nand Nagri",
"address_line2": "Near Police Station",
"city": "East Delhi",
"state": "Delhi",
"country": "India",
"postal_code": "110093"
}
],
"currency": "INR",
"total_amount": {
"value": 21000,
"offset": 100
},
"payment_settings": [
{
"type": "upi_intent_link",
"upi_intent_link": {
"link": "upi://pay?pa=merchant_vpa&pn=Merchant_Name&mc=1234&purpose=00&tr=pg_generated_id"
}
}
],
"order": {
"status": "pending",
"type": "quick_pay", //optional, only value supported is quick_pay
"expiration": { //optional
"timestamp": "1700000000",
"description": "Order will be cancelled after expiry."
},
"items": [
{
"name": "Cotton T-Shirt",
"amount": {
"value": 10000,
"offset": 100
},
"sale_amount": { //optional, the discounted price per item
"value": 8000,
"offset": 100
},
"quantity": 2,
"country_of_origin": "India",
"importer_name": "Acme Imports Pvt Ltd",
"importer_address": {
"address_line1": "B8/733 Nand Nagri",
"address_line2": "Near Police Station",
"city": "East Delhi",
"zone_code": "DL",
"postal_code": "110093",
"country_code": "IN"
}
}
],
"subtotal": {
"value": 16000,
"offset": 100
},
"tax": {
"value": 2000,
"offset": 100,
"description": "GST 18%"
},
"shipping": { //optional, shipping cost of the order
"value": 5000,
"offset": 100,
"description": "Standard delivery"
},
"discount": { //optional, the discount for the order
"value": 2000,
"offset": 100,
"description": "Promo discount",
"discount_program_name": "WELCOME10"
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"header": { //optional
"type": "image",
"image": {
"link": "https://your-media-url.com/image.jpg"
}
},
"body": {
"text": "Here is your order summary. Please review and complete your payment."
},
"footer": { //optional
"text": "Thank you for shopping with us!"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "order-ref-12345",
"type": "digital-goods",
"currency": "INR",
"total_amount": {
"value": 19000,
"offset": 100
},
"payment_settings": [
{
"type": "upi_intent_link",
"upi_intent_link": {
"link": "upi://pay?pa=merchant_vpa&pn=Merchant_Name&mc=1234&purpose=00&tr=pg_generated_id"
}
}
],
"order": {
"status": "pending",
"type": "quick_pay", //optional
"expiration": { //optional
"timestamp": "1700000000",
"description": "Order will be cancelled after expiry."
},
"items": [
{
"name": "Premium Subscription - 1 Month",
"amount": {
"value": 19900,
"offset": 100
},
"sale_amount": {
"value": 17000,
"offset": 100
},
"quantity": 1,
"country_of_origin": "India",
"importer_name": "Acme Digital Pvt Ltd",
"importer_address": {
"address_line1": "12 Tech Park",
"address_line2": "Whitefield",
"city": "Bengaluru",
"zone_code": "KA",
"postal_code": "560066",
"country_code": "IN"
}
}
],
"subtotal": {
"value": 17000,
"offset": 100
},
"tax": {
"value": 3060,
"offset": 100,
"description": "GST 18%"
},
"shipping": { //optional
"value": 0,
"offset": 100,
"description": "No shipping for digital goods"
},
"discount": { //optional
"value": 1000,
"offset": 100,
"description": "Launch offer",
"discount_program_name": "LAUNCH20"
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"reference": "pruebareference2",
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
Catalog Examples
The following examples are with product catalog from your catalog manage in facebook.
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "Your body message content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "unique-reference-id",
"type": "digital-goods",
"payment_settings": [
{
"type": "upi_intent_link",
"upi_intent_link": {
"link": "upi://pay?pa=merchant_vpa&pn=merchant%20Name&mc=mc_code&purpose=purpose_code&tr=transaction_record"
}
}
],
"currency": "INR",
"total_amount": {
"value": 2700,
"offset": 100 //must be 100
},
"order": {
"status": "pending", //only supported pending value
"catalog_id": "333817456789654321", //optional if not provided those are mandatory country_of_origin, importer_name, and importer_address
"expiration": {
"timestamp": 12000,
"description": "your order will expire in 12000 seconds if is not confirmed."
},
"items": [
{
"retailer_id": "4270312345abc", //content id for your catalog item
"name": "License Key",
"amount": {
"value": 2700,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 2700,
"offset": 100
},
"shipping": {
"value": 1000,
"offset": 100,
"description": "optional_text"
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "This is your order details."
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "F63F3F99",
"type": "digital-goods",
"payment_type": "upi",
"payment_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://the-payment-link"
}
}
],
"currency": "INR",
"total_amount": {
"value": 2700,
"offset": 100
},
"order": {
"status": "pending",
"catalog_id": "333817456789654321",
"expiration": {
"timestamp": 12000,
"description": "your order will expire in 12000 seconds if is not confirmed."
},
"items": [
{
"retailer_id": "4270312345abc",
"name": "License Key",
"amount": {
"value": 2700,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 2700,
"offset": 100
},
"tax": {
"value": 0,
"offset": 100,
"description": "optional_text"
},
"shipping": {
"value": 0,
"offset": 100,
"description": "optional_text"
},
"discount": {
"value": 0,
"offset": 100,
"description": "optional_text",
"discount_program_name": "optional_text"
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"header": {
"type": "image",
"image": {
"link": "https://picsum.photos/200/300"
}
},
"body": {
"text": "This is your order details."
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "F63F3F99",
"type": "digital-goods",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "razorpay",
"configuration_name": "payment-config-id"
}
}
],
"currency": "INR",
"total_amount": {
"value": 2700,
"offset": 100
},
"order": {
"status": "pending",
"catalog_id": "333817456789654321",
"expiration": {
"timestamp": 12000,
"description": "your order will expire in 12000 seconds if is not confirmed."
},
"items": [
{
"retailer_id": "4270312345abc",
"name": "License Key",
"amount": {
"value": 2700,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 2700,
"offset": 100
},
"tax": {
"value": 0,
"offset": 100,
"description": "optional_text"
},
"shipping": {
"value": 0,
"offset": 100,
"description": "optional_text"
},
"discount": {
"value": 0,
"offset": 100,
"description": "optional_text",
"discount_program_name": "optional_text"
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
Non-catalog Examples
When submitting products without a catalog, retailer_id is not required. Instead, include country_of_origin with the product's country of origin, importer_name with the importing company's name and importer_address with the importing company's address.
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "Your body message content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "unique-reference-id",
"type": "digital-goods",
"payment_settings": [
{
"type": "upi_intent_link",
"upi_intent_link": {
"link": "upi://pay?pa=merchant_vpa&pn=merchant%20Name&mc=mc_code&purpose=purpose_code&tr=transaction_record"
}
}
],
"currency": "INR",
"total_amount": {
"value": 2700,
"offset": 100
},
"order": {
"status": "pending",
"catalog_id": "333817562061258", //optional if not provided those are mandatory country_of_origin, importer_name, and importer_address
"expiration": { //optional
"timestamp": 12000,
"description": "your order will expire in 12000 seconds if is not confirmed."
},
"items": [
{
"country_of_origin": "India",
"importer_address": {
"address_line1": "Saket District Centre, District Centre, Sector 6, Pushp Vihar",
"address_line2": "apartments",
"city": "New Delhi",
"country_code": "IND",
"postal_code": "110017"
},
"importer_name": "name-of-importer-business",
"name": "Anker Speaker",
"amount": {
"value": 2700,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 2700,
"offset": 100
},
"shipping": {
"value": 1000,
"offset": 100,
"description": "primary address"
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"reference": "pruebareference2",
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
Example of order_details message.
Template order_details
Sending a order_details template example
The order details message template enhances the call-to-action button by incorporating interactive components, enabling the sharing of order details and offering a more engaging experience than text-only templates.
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "order_details_in_payments_test",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"media": {
"mediaUri": "https://picsum.photos/200/300",
"mimeType": "image/png"
},
"type": "image"
}
]
},
{
"type": "button",
"sub_type": "order_details",
"index": 0,
"parameters": [
{
"type": "action",
"action": {
"order_details": {
"currency": "INR",
"order": {
"discount": {
"offset": 100,
"value": 0
},
"items": [
{
"amount": {
"offset": 100,
"value": 4000
},
"country_of_origin": "India",
"importer_address": {
"address_line1": "Saket District Centre, District Centre, Sector 6, Pushp Vihar",
"city": "New Delhi",
"country_code": "IND",
"postal_code": "110017"
},
"importer_name": "CM.com",
"name": "Anker Speaker",
"quantity": 1,
"retailer_id": "42703ed5a"
}
],
"shipping": {
"offset": 100,
"value": 0
},
"status": "pending",
"subtotal": {
"offset": 100,
"value": 4000
},
"tax": {
"offset": 100,
"value": 0
}
},
"payment_configuration": "D6CC1687-5BCE-44DD-AAF9-357BEDBD9C8B",
"payment_settings": [
{
"type": "upi_intent_link",
"upi_intent_link": {
"link": "upi://pay?pa=anything@payu&pn=ABC&tr=877376394&am=10.00&cu=INR&mode=00&purpose=00&mc=5399&tn=877376394"
}
}
],
"payment_type": "upi",
"reference_id": "F63F3F99",
"total_amount": {
"offset": 100,
"value": 4000
},
"type": "digital-goods"
}
}
}
]
}
]
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
Once an order is created and paid by the customer you should send a message indicating to your customer that the order is in status processing with the order_status message.
Example of order_details message template.
Sending the order_status message
The order_status messages are used to notify customers when businesses update the status of an order. These updates can be triggered either by changes in the WhatsApp payment status notification or through the business's internal processes.
- Supported Order Statuses:
- pending: The default state when the order is created.
- processing: Use this when you receive the payment from your customers.
- shipped / partially-shipped: Use this for physical goods in transit.
- completed: The final state once the service is rendered or the item is delivered.
- canceled: Only available if the payment hasn't been captured yet.
- Supported Payment Statuses:
- pending: Payment is pending.
- captured: This automatically adds a "Paid" label with a green checkmark to the customer’s order bubble.
- failed: Notifies the customer the transaction did not go through.
Updating Payment Status
When your system receives a payment notification (via your payment provider or webhook), you should send an order_status update with the payment field.
Best practices
To manage time-sensitive offers or stock availability, utilize the expiration object. Once the expiration time is reached, the "Pay" button will automatically be disabled for the user, ensuring accurate and timely transactions.
For Body Text, leverage markdown formatting in the body text to emphasize critical information. For example:
“Please complete your Pix payment within 15 minutes.”
Interactive order_status message example
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_status",
"body": {
"text": "This is the status of your order."
},
"action": {
"name": "review_order",
"parameters": {
"reference_id": "F63F3F99",
"order": {
"status": "pending",
"description": "Order will be canceled if not paid by the expiration time."
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
order_status template message example
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "order_status_in_payments_test",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "order_status",
"parameters": [
{
"type": "order_status",
"order_status": {
"reference_id": "F63F3F99",
"order": {
"status": "processing",
"description": "Thanks for your order. We are working on it!"
}
}
}
]
}
]
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"reference": "pruebareference2",
"body": {
"content": "text"
},
"from": "00916098765432",
"to": [
{
"number": "00916012345678"
}
]
}
]
}
}
Example of an order_status message.
Updated about 23 hours ago