LogoLogo
Become a PartnerStatus Page
  • get started
    • Welcome to 360Dialog
    • Quickstarts
      • Register as a Meta Tech Provider
      • Add a WhatsApp Number
      • Set up Integrated Onboarding
      • Create a Message Template
      • Send a Message
      • (temp title) Getting started as a partner
    • Pricing & Billing
      • Payment Methods for BR: Pix & Boleto
      • Month Closing Invoice (MCI)
    • Get API Access
    • Tech Provider Program
      • Understanding the Meta Tech Provider Program
      • Becoming a Meta Tech Provider: A Step-by-Step Guide
  • MM Lite Beta Program
    • Onboarding
    • Sending Messages
    • Expected Errors & Programming Languages
    • MM Lite Sandbox Testing
      • Sending Messages using MM Lite Sandbox
      • Expected Erros & Programming Languages
  • Partner & Account Management
    • Solutions for Partners
      • Benefits for Partners
      • Partner Hub
      • WABA Management
    • Account Setup & Management
      • Prerequisites and best practices for account creation
      • Account Structure
      • Account Creation
  • Integrations & API Development
    • Webhook Events & Setup
      • Webhook Events (Partner & Messaging API)
      • Webhook Configuration & Management
    • Integration Best Practices
      • Architecture and Security
      • Best Practices for Designing Integrations
        • Design a Stable Webhook Receiving Endpoint
      • Sizing Your Environment Based on Expected Throughput
      • Design a Resilient Message Sending Service
      • Integrated Onboarding
        • Basic Integrated Onboarding
        • Custom Integrated Onboarding
        • Host Your Own Embedded Signup
      • API Key Authentication for the Partner API
  • API Reference
    • Messaging API
    • Messaging Health Status
    • Sandbox (Test API Key)
    • Differences Between Cloud API and On-Premise API for Partners
      • [will be deprecated] Messaging with On-Premise API
    • Partner API
  • WABA Management
    • Managing WABA Accounts
      • Using the Partner Hub to manage Clients and Channels
      • Using the Partner API to manage Clients and Channels
      • Partner Permission to Generate API Key
      • Checking Usage & Statistics
    • Phone Number & Hosting
      • Migrating a Phone Number
        • Migrate number from Meta or alternate BSP to 360Dialog
        • Migrate a phone number to a new WABA
        • Migrate a phone number to a new WABA to change messaging Currency
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
      • Hosting type Change (On-premise API to Cloud API)
    • WABA Profile & Compliance
      • Display Name Guidelines
      • WABA Profile Info
      • WABA Policy Enforcement
      • Business Account Verification
    • Partner change (between 360Dialog Partners)
    • WhatsApp Flows
    • Accelerated Onboarding
    • Business Account Verification
  • Messaging
    • Sending & Receiving Messages
      • Conversations
      • Receiving messages
      • Before sending a message
    • Message Types
      • Conversational Components
      • Checklist for Message Broadcasts and Campaigns
      • Text messages
      • Interactive messages
        • Single and Multi Product Messages
        • Location Request Messages
        • Address Messages (India and Singapore only)
      • Contacts & Location Messages
    • Template Messages
      • Template Library
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Media Messages
      • Upload, retrieve or delete media
    • Messaging Health & Troubleshooting
      • Messaging Limits & Quality Rating
      • Errors While Messaging
      • Messages statuses
  • Commerce & Payments
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore Only)
      • Receive WhatsApp Payments via Stripe
    • Products and Catalogs
      • India Businesses: Compliance for Commerce
  • Support & Updates
    • Help & Troubleshooting
      • FAQ
      • Error Code Reference
      • User Support Documentation
        • Tutorials
          • Page How to Troubleshoot Login Issues in the 360dialog Hub
          • How to Report an Issue
          • How to Contact Support
        • How-To Guides
          • Raise a support request
          • Requesting a Status Update for Business Verification
        • Reference
          • Troubleshooting Embedded Signup Issues
          • Commerce Policy Checks for WhatsApp API Access
          • Support Availability & SLAs
          • Incident Issue Prioritization
          • Case Types Table
        • Explanation
          • Why Business Verification Takes Time
          • Why Some Issues Are Not Emergencies
          • Understanding the Support Process
      • Support with Meta
    • Imprint & Data Privacy
    • Product Updates & News
      • How to ensure your Template Messages will be received
      • Integrated Onboarding new look and Campaigns Best Practices
Powered by GitBook
On this page
  • How it Works
  • Purchase Flow in App
  • Link Your Payment Account
  • Get Started
  • Integration Steps
  • Step 1: Send Order Details Interactive Message
  • Step 2: Receive Webhook about Transaction Status
  • Step 3. Confirm Payment
  • Step 4. Update Order Status
  • Step 5: Reconcile Payments
  • Security Considerations for Payments API

Was this helpful?

  1. Commerce & Payments
  2. Payments (India Only)

Receive WhatsApp Payments via Payments Gateway

PreviousPayments (India Only)NextReceive WhatsApp Payments via Payment Links

Last updated 8 months ago

Was this helpful?

The Payments API feature is available only for Indian businesses using the 360dialog WhatsApp Business API with phone numbers only from India. Review .

This feature is now available to all Indian businesses. If the account is in , admins or finance editors users will have direct access to the page and can manage . If you have any trouble using this feature, please reach out to our Support Team.

Currently, customers browse business catalogs, add products to cart, and send orders with Meta's set of commerce messaging solutions, which includes . 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.

How it Works

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 webhook notifications due to security reasons. WhatsApp also provides a payment lookup API that can be used to retrieve the payment statuses directly anytime.

Please note that neither 360dialog nor WhatsApp supports payment reconciliations.

You must reconcile the payment with the business payment service provider using the respective order reference_id.

Purchase Flow in App

In the WhatsApp Messenger App, the purchase flow has the following steps:

  1. Customers send an order with selected products to the business either through simple text messages or using other interactive messages such as .

  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 Continue button, they are able to choose to pay natively on WhatsApp or any other UPI app.

  1. Once the payment has been confirmed by your payment gateway (PG) or payment service provider, the business can start processing the order.

  2. 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 above) that refers to the original order details message and also updates the status displayed on the order details page.

Link Your Payment Account

To receive payments on WhatsApp, businesses must add a payment configuration to the corresponding WhatsApp Business Account. A payment configuration allows you to link a payment gateway 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 checkout flow using the associated payment gateway account.

If the WABA is a Shared WABA (created through Embedded Signup)

Once the user enters the details, Meta redirects them to the payment gateway website to enter their credentials and link their account with WhatsApp as shown below.

If the WABA is an OBO (On-Behalf-of) WABA (created through Classic Signup)

In case of the OBO WhatsApp Business Accounts, 360dialog can enter the payment configuration details and generate a link URL. This link URL will be shared, which will allow you to log into the payment gateway account and connect it with WhatsApp.

For this, please reach out to our support team.

After linking the payment 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.

Get Started

Integration Steps

Sequence Diagram

The following sequence diagram demonstrates the typical integration flow for Payments API. The steps highlighted in green are the key integration steps.

Step 1: 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

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

  • Required if 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 fields:

text string

  • Required if 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

  • Required. Must be "review_and_pay"

parameters object

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 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

object

Required.

The type of goods being paid for in this order. Current supported options are digital-goods and physical-goods

beneficiaries

array

Required for shipped physical-goods.

An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the 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

  • Required. Name of the individual or business receiving the physical goods. Cannot exceed 200 characters

address_line1 string

  • Required. Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters

address_line2 string

  • Optional. Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters

city string

  • Optional. Name of the city.

state string

  • Optional. Name of the state.

country string

  • Required. Must be "India".

postal_code string

  • Required. 6-digit zipcode of shipping address.

currency

Required.

The currency for this order. Currently the only supported value is INR.

total_amount

object

Required.

The total_amount object contains the following fields:

offset integer

  • Required. Must be 100 for INR.

value integer

  • Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.

total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value.

payment_settings

object

Required.

order

object

Required.

Payment Settings Object

Object
Description

type

string

Required.

Must be set to "payment_gateway"

payment_gateway

object

Required.

An object that describes payment account information:

type string

  • Required. Unique identifier for an item in the order. Mustset this to "razorpay", if you have linked your RZP payment gateway to accept payments

configuration_name 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.

When configuration_name 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.

razorpay/payu object

  • Optional. For merchants/partners that want to use notes, receipt(for Razorpay) and UDF fields(for PayU), they can now pass these values in Order Details message and we would use these to create transaction/order at respective PGs.

RazorPay Notes and PayU UDF fields

We now have support for partners and merchants to pass notes, receipt and udf fileds in Order Details message and receive this data back in payment signals. Here we will take a look at merchants can pass notes, receipt fields for Razorpay and UDF for PayU PGs.

Object
Description

notes

object

Optional.

  • Only supported for Razorpay payment gateway

The object can be key value pairs with maximum 15 keys and each value limits to 256 characters.

receipt

String

Optional.

  • Only supported for Razorpay payment gateway

Receipt number that corresponds to this order, set for your internal reference. Maximum length of 40 characters supported with minimum length greater than 0 characters.

udf1-4

String

Optional.

  • Only supported for PayU payment gateway

User-defined fields (udf) are used to store any information corresponding to a particular order. Each UDF field has a maximum character limit of 255

Order Object

Object
Description

status

string

Required.

Only supported value in the order_details message is pending.

In an order_status message, status can be: pending, captured, or failed.

items

object

Required.

An object with the list of items for this order, containing the following fields:

retailer_id string

  • Required. Unique identifier for an item in the order.

name string

  • Required. The item’s name to be displayed to the user. Cannot exceed 60 characters

amount amount object with value and offset -- refer total amount field above

  • Required. The price per item

sale_amount amount object

  • Optional. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount

quantity integer

  • Required. The number of items in this order, this field cannot be decimal has to be integer.

country_of_origin string

  • Required if catalog_id is not present. The country of origin of the product

importer_name string

  • Required if catalog_id is not present. Name of the importer company

importer_adress string

  • Required if catalog_id is not present. Address of importer company

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 integer

  • Required. Must be 100 for INR

value integer

  • Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234

tax

object

Required.

The tax information for this order which contains the following fields:

offset integer

  • Required. Must be 100 for INR

value integer

  • Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234

description string

  • Optional. Max character limit is 60 characters

shipping

object

Optional.

The shipping cost of the order. The object contains the following fields:

offset integer

  • Required. Must be 100 for INR

value integer

  • Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234

description string

  • Optional. Max character limit is 60 characters

discount

object

Optional.

The discount for the order. The object contains the following fields:

offset integer

  • Required. Must be 100 for INR

value integer

  • Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234

description string

  • Optional. Max character limit is 60 characters

discount_program_name string

  • Optional. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters

catalog_id

object

Optional.

Unique identifier of the Facebook catalog being used by the business.

If you do not provide this field, you must provide the following fields inside the items object: country_of_origin, importer_name, and importer_address

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

The parameters value is a stringified JSON object.

By the end, the interactive object should look something like this for a catalog-based integration:

{
  "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_settings": [
          {
            "type": "payment_gateway",
            "payment_gateway": {
              "type": "razorpay",
              "configuration_name": "payment-config-id",
      	      "razorpay": {
                "receipt": "receipt-value",
                "notes": {
                  "key1": "value1"
                }
              }
            }
          }
        ],
        "currency": "INR",
        "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": 1,
              "sale_amount": {
                "value": 100,
                "offset": 100
              }
            }
          ],
          "subtotal": {
            "value": 20000,
            "offset": 100
          },
          "tax": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "shipping": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "discount": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text",
            "discount_program_name": "optional_text"
          }
        }
      }
    }
  }
}

The parameters value is a stringified JSON object.

For a non-catalog based integration i.e. when catalog-id is not present, an example payload looks as follows:

{
  "interactive": {
    "type": "order_details",
    "header": {
      "type": "image",
      "image": {
        "id": "your-media-id"
      }
    },
    "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_settings": [
          {
            "type": "payment_gateway",
            "payment_gateway": {
              "type": "razorpay",
              "configuration_name": "payment-config-id"
            }
          }
        ],
        "currency": "INR",
        "total_amount": {
          "value": 21000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "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": 1,
              "sale_amount": {
                "value": 100,
                "offset": 100
              },
              "country_of_origin": "country-of-origin",
              "importer_name": "name-of-importer-business",
              "importer_address": {
                "address_line1": "B8/733 nand nagri",
                "address_line2": "police station",
                "city": "East Delhi",
                "zone_code": "DL",
                "postal_code": "110093",
                "country_code": "IN"
              }
            },
            {
              "retailer_id": "14325",
              "name": "Product name, for example bread",
              "amount": {
                "value": 10000,
                "offset": 100
              },
              "quantity": 1,
              "sale_amount": {
                "value": 100,
                "offset": 100
              },
              "country_of_origin": "country-of-origin",
              "importer_name": "name-of-importer-business",
              "importer_address": {
                "address_line1": "B8/733 nand nagri",
                "address_line2": "police station",
                "city": "East Delhi",
                "zone_code": "DL",
                "postal_code": "110093",
                "country_code": "IN"
              }
            }
          ],
          "subtotal": {
            "value": 20000,
            "offset": 100
          },
          "tax": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "shipping": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "discount": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text",
            "discount_program_name": "optional_text"
          }
        }
      }
    }
  }
}

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.

If the WABA is registered in Cloud API

{
   "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     // interactive object here     
   }
 }

[will be deprecated] If the WABA is registered in On-premise API

If you are using On-Premise API, remember that it is being discontinued by Meta. No new signups will be allowed with this type of integration from May 15, 2024.

{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    // interactive object here
  }
}

Make a POST Call to /messages

Make a POST call to the /messages endpoint with the JSON object you have assembled. If your message is sent successfully, you get the following response:

If the WABA is registered in Cloud API

{
  "messaging_product": "whatsapp",
  "contacts": [ {
      "input": "[PHONE_NUMBER_ID]",
      "wa_id": "[PHONE-NUMBER_ID]"
  } ],
  "messages": [ {
      "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
  } ]
}

[will be deprecated] If the WABA is registered in On-premise API

{
  "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 "Continue" button that opens up a bottom sheet with the payment options (right).

Step 2: Receive Webhook about Transaction Status

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

  • Unique reference ID for the order sent in order_details message.

amount object

  • Has value and offset fileds corresponding to totao amount that user has paid.

currency string

  • currency is always INR.

notes object Optional.

  • Only sent for razorpay payment gateway when the value is sent in order details message. This contains key-value pair as passed in the Order Details message.

receipt string Optional.

  • Only sent for razorpay payment gateway when the value is sent in order details message.

udf1-4 string Optional.

  • Only sent for payu payment gateway when the value is sent in order details message. Each of the keys udf1-4 has string values in them.

timestamp

string

Required.

Timestamp for the webhook.

Here is an example status webhook of type payment:

{
  "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": "[TRANSACTION_STATUS]",
            "payment": {
               "reference_id": "[REFERENCE_ID]",
               "amount": {
                 "value": 21000,
                 "offset": 100
               },
               "currency": "INR",
               "receipt": "receipt-value",
               "notes": {
                 "key1": "value1",
                 "key2": "value2"
               },
               "udf1": "udf1-value",
               "udf2": "udf2-value",
               "udf3": "udf3-value",
               "udf4": "udf4-value",
            },
            "timestamp": "notification_timestamp"
         }]
      },
      "field": "messages"
    }]
  }]
}

Step 3. 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. To do that, businesses must make a GET call to /payments/{payment-config-id}/{reference_ID}.

Businesses should expect a response in the same HTTP session (not in a webhook notification). payment_configuration and reference_id must be the same as that provided in the initial order_details message.

A response can return the following values:

Field
Description

reference_id

The ID provided by the partner in the order_details message

status

currency

The currency for this payment. Currently the only supported value is INR.

total_amount

The total amount for this payment. This object contains the following fields:

offset integer

  • Required. Must be 100 for INR.

value integer

  • Required. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.

transactions

Required.

The list of transactions for this payment. Each transaction object contains the following fields:

id string

  • Required. The alpha-numeric ID of the payment gateway transaction.

type string

  • Required. The payment type for this transactions. Only, razorpay or payu are supported.

status string

  • Required. The status of the transaction. Can be one of pending or success.

At most one transaction can have a success status.

created_timestamp integer

  • Required. Time when transaction was created in epoch seconds.

updated_timestamp integer

  • Required. Time when transaction was last updated in epoch seconds.

refunds array

Optional. The list of refunds for this order. Each refund object contains the following fields:

  • id string Required. The alpha-numeric ID of the refund.

  • amount object Required. The total amount of the refund.

  • speed_processed string Required. Speed by which refund was processed. Can be one of instant or normal.

  • status string Required. The status of the refund. Can be one of pending, success or failed.

  • created_timestamp integer Required. Time when refund was created in epoch seconds.

  • updated_timestamp integer Required. Time when refund was last updated in epoch seconds.

receipt

string

Optional.

Supported for only Razorpay PG, this contains the receipt-value sent as part of Order Details message.

notes

object

Optional.

Supported for only Razorpay PG, this contains the key-value pairs sent as part of Order Details message.

udf1-4

string

Optional.

Supported for only PayU PG, this contains string values sent as part of Order Details message.

Payment Status

Status
Description

new

The partner sent an order_details message but the user didn’t start a payment yet

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

A successful response looks like this:

{
  "payments": [{
    "reference_id": "reference-id-value",
    "status": "status-of-payment",
    "currency": "INR",
    "total_amount": {
      "value": 21000,
      "offset": 100
    },
    "transactions": [
      {
        "id": "[PG-TXN-ID]",
        "type": "razorpay/payu",
        "status": "success",
        "created_timestamp": "CREATED_TIMESTAMP",
        "updated_timestamp": "UPDATED_TIMESATMP",
        "refunds": [
          {
            "id": "[REFUND-ID]",
            "amount": {
              "value": 100,
              "offset": 100
            },
            "speed_processed": "instant/normal",
            "status": "success",
            "created_timestamp": "CREATED_TIMESTAMP",
            "updated_timestamp": "UPDATED_TIMESATMP",
          }
        ],
      }
    ],
    "receipt": "receipt-value",
    "notes": {
      "key1": "value1",
      "key2": "value2"
    },
    "udf1": "udf1-value",
    "udf2": "udf2-value",
    "udf3": "udf3-value",
    "udf4": "udf4-value"
  }]
}

In the case of any errors, this is the response:

{
  "errors": [{
    "code": "<error code>",
    "title": "<title for error>",
    "details": "<details description of error>"
  }]
}

Step 4. Update Order Status

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:

{
  "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 | partially_shipped | shipped | completed | canceled",
          "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

  • Required if 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

  • Required if 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

  • Required. Must be "review_order".

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.

Error Code
Description

2046 - Invalid status transition

The order status transition is not allowed.

2047 - Cannot cancel order

Cannot cancel the order since the user has already paid for it.

Product Experience

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).

Supported Order Status and Transitions

Currently we support 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 business 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.

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'".

Step 5: Reconcile Payments

Please note that neither 360dialog nor WhatsApp supports payment reconciliations. Businesses should use their payment gateway account to reconcile the payments using the reference_id provided in the order_details messages and the id of the transactions returned as part of the payment lookup query.

Security Considerations for Payments API

  • 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.

  • Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks.

Businesses can use the 'Direct pay methods' page and under 'India' in .

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

See for information

See for more information.

See for more information.

Please referfor more information.

These types

Numbers registered before this date will still be supported, but should start planning a as soon as possible.

These types.

For all errors that can be returned and guidance on how to handle them, see .

For all errors that can be returned and guidance on how to handle them, see .

Businesses receive updates via when the status of the user-initiated transaction changes in a status of type "payment". It contains the following fields:

The payment status. See thetable for possible values. Note that this is not the same as transaction status.

For all errors that can be returned and guidance on how to handle them, see

See for information

Review our documentation.

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

WhatsApp Business Manager
List Messages, Reply Buttons, Single or Multi-Product Messages.
are parameters common to Cloud API message
change of hosting type
are parameters common to On-Premise message
WhatsApp Cloud API, Error Codes
Errors while Messaging
WhatsApp webhooks
Errors while Messaging
WABA Security
Business Manager Accounts must be created.
Parameters Object
Parameters Object
Payment Settings object
order object
Payment Gateway specific UDF object
payment status
WhatsApp Business Compliance for India
high or medium tiers
Payment Gateway
payment settings in Meta Business Manager
Single Product Message, Multi Product Message, and Product Detail Page
Single Product Message, Multi Product Message, and Product Detail
Checkout with WhatsApp Pay
Checkout on other UPI Apps