Receive WhatsApp Payments via Payments Gateway

Get Started

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

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.

Integration Steps

1

Send Order Details Interactive Message

Elements Table

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

2

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.

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

These are parameters common to Cloud API message types

3

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:

{
  "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, Error Codes.

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

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}/{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.

4

Responses

A response can return the following values:

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:

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

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

{
  "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 See Parameters Object for information

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

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

Review our WABA Security documentation.

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