Receive Payments via Payment Gateways on WhatsApp

Your business can enable customers to pay for their orders through our partner payment gateways without leaving WhatsApp. Businesses can send customers order_details messages, then get notified about payment status updates via webhook notifications.

Overview

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.

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

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 Single Product Message, Multi Product Message, and Product Detail.
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.

   Checkout with WhatsApp Pay
   

   Checkout on other UPI Apps
   

4. Once the payment has been confirmed by your payment gateway (PG) or payment service provider, the business can start processing the order.
5. 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 below) 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, you 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.

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

Steps to unlink Payment Configuration

Note: Make sure no new order messages requesting payment from consumer are sent with the payment config your are trying to remove before you perform the unlink action.

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.

Sequence Diagram

The following sequence diagram demonstrates the typical integration flow for Payments API. The steps higlighted 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:

Parameters Object

Payment Settings Object

BillDesk, RazorPay, PayU and Zaakpay 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 additional_info for BillDesk, notes and receipt fields for Razorpay, udf for PayU, extra for Zaakpay PGs.

Order Object

Item Image Object

By the end, the interactive object should look something like this for a BillDesk 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": "billdesk",
              "configuration_name": "payment-config-id",
      	      "billdesk": {
                "additional_info1": "additional_info1-value",
                "additional_info2": "additional_info2-value",
                "additional_info3": "additional_info3-value",
                "additional_info4": "additional_info4-value",
                "additional_info5": "additional_info5-value",
                "additional_info6": "additional_info6-value",
                "additional_info7": "additional_info7-value",
              }
            }
          }
        ],
        "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"
          }
        }
      }
    }
  }
}

By the end, the interactive object should look something like this for a RazorPay 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"
          }
        }
      }
    }
  }
}

For a PayU 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": {
        "link": "your-media-url-link"
      }
    },
    "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": "payu",
              "configuration_name": "payment-config-id",
              "payu": {
                "udf1": "value1",
                "udf2": "value2",
              	"udf3": "value3",
              	"udf4": "value4"
              }
            }
          }
        ],
        "currency": "INR",
        "total_amount": {
          "value": 21000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "expiration": {
            "timestamp": "utc_timestamp_in_seconds",
            "description": "cancellation-explanation"
          },
          "items": [
            {
              "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"
              }
            },
            {
              "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"
          }
        }
      }
    }
  }
}

For a Zaakpay 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": {
        "link": "your-media-url-link"
      }
    },
    "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": "zaakpay",
              "configuration_name": "payment-config-id",
              "zaakpay": {
                "extra1": "value1",
                "extra2": "value2"
              }
            }
          }
        ],
        "currency": "INR",
        "total_amount": {
          "value": 21000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "expiration": {
            "timestamp": "utc_timestamp_in_seconds",
            "description": "cancellation-explanation"
          },
          "items": [
            {
              "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"
              }
            },
            {
              "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"
          }
        }
      }
    }
  }
}

Step 3: 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 all message types.

Step 4:Make a POST Call to Messages Endpoint

Make a POST call to the /[PHONE_NUMBER_ID]/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 Cloud API, 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).

Step 2: Receive Webhook about Transaction Status

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:

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
               },
               "transaction": {
                 "id": "[PG-TXN-ID]",
                 "type": "billdesk/razorpay/payu/zaakpay",
                 "status": "success/failed",
                 "created_timestamp": "CREATED_TIMESTAMP",
                 "updated_timestamp": "UPDATED_TIMESATMP",
                 "method": {
                   "type": "upi/card/netbanking/wallet"
                 },
                 "error": {
                   "code": "pg-generated-error-code",
                   "reason": "pg-generated-descriptive-reason"
                 }
               },
               "currency": "INR",
               "receipt": "receipt-value",
               "notes": {
                 "key1": "value1",
                 "key2": "value2"
               },
               "udf1": "udf1-value",
               "udf2": "udf2-value",
               "udf3": "udf3-value",
               "udf4": "udf4-value",
               "additional_info1": "additional_info1-value",
               "additional_info2": "additional_info2-value",
               "additional_info3": "additional_info3-value",
               "additional_info4": "additional_info4-value",
               "additional_info5": "additional_info5-value",
               "additional_info6": "additional_info6-value",
               "additional_info7": "additional_info7-value",
               "refunds": [{
                 "id": "[REFUND-ID]",
                 "amount": {
                   "value": 100,
                   "offset": 100
                 },
                 "speed_processed": "instant/normal",
                 "status": "success",
                 "created_timestamp": "CREATED_TIMESTAMP",
                 "updated_timestamp": "UPDATED_TIMESATMP",
              }],
            },
            "timestamp": "notification_timestamp"
         }]
      },
      "field": "messages"
    }]
  }]
}

For more information about other statuses, see Components, Statuses Object.

Step 3: Confirm Payment

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:

Payment Status

An example 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": "billdesk/razorpay/payu/zaakpay",
        "status": "success/failed",
        "created_timestamp": "CREATED_TIMESTAMP",
        "updated_timestamp": "UPDATED_TIMESATMP",
        "method": {
           "type": "upi/card/netbanking/wallet"
        },
        "error": {
           "code": "pg-generated-error-code",
           "reason": "pg-generated-descriptive-reason"
        },
        "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"
    "additional_info1": "additional_info1-value",
    "additional_info2": "additional_info2-value",
    "additional_info3": "additional_info3-value",
    "additional_info4": "additional_info4-value",
    "additional_info5": "additional_info5-value",
    "additional_info6": "additional_info6-value",
    "additional_info7": "additional_info7-value",
  }]
}

In the case of any errors, response is similar to an error response for /v1/messages endpoint. For all errors that can be returned and guidance on how to handle them, see WhatsApp On-Premises API, Errors. Show here is an example for a generic error:

{
  "errors": [{
    "code": 500,
    "title": "Generic error",
    "details": "System error. Please try again."
  }]
}

Step 4: Update Order Status

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:

The parameters object contains the following fields:

order_status message introduces two new errors that are summarized below.

For all other errors that can be returned and guidance on how to handle them, see WhatsApp On-Premises API, Errors.

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:

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 and order details page is updated to show that the order is canceled and the "Continue" button removed. 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

WhatsApp does not support 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.

Step 6: Refunds

Business can initiate a refund for an order. To do that, businesses must make a POST call to the /[PHONE_NUMBER_ID]/payments_refund endpoint with the following JSON object:

{
  "reference_id": "reference-id-value",
  "speed": "normal",
  "payment_config_id": "payment-config-id",
  "amount": {
    "currency": "INR",
    "value": "100",
    "offset": "100"
  }
}

The following table describes the fields in the refunds endpoint request object:

Businesses should expect a response in the same HTTP session (not in a webhook notification) that contains the following fields:

An example successful response looks like this:

{
  "id": "refund-id",
  "status": "pending",
  "speed_processed": "normal"
}

Merchant Preferred UPI Payment Method

Now merchants can specify upto one UPI Payment app to showup in checkout flow. Merchant preferred payment app will be shown on top of the list of available UPI apps in - "Choose payment method" screen. To enable this capability we require partners to specify the external app-id in the Order Details or order-invoice message.

Note: This feature is available on consumer apps on and above version: 2.24.21.0

Updates to Order Details Payload

{
  "messaging_product": "whatsapp",
  "interactive": {
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "payment_settings": [
           {
             "type": "payment_gateway",
             "preferred_payment_methods": [
               {
                 "method": "Application-ID"
               }
             ]
           }
         
        ],
      "order": ..
      }
    }
  }
}

List of supported apps:

Restrict Available Payment Options

Merchants can specify which payment options to show in checkout flow between UPI and Web options. This will allow merchants to enable only UPI or credit card(any PG available option) to accept payments for invoices.

Note: This feature is available on consumer apps on and above version: 2.24.22.4

Updates to Order Details Payload

{
  "messaging_product": "whatsapp",
  "interactive": {
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "payment_settings": [
           {
             "type": "payment_gateway",
             "enabled_payment_options": ["upi"/"web"]
           }
         
        ],
      "order": ..
      }
    }
  }
}

List of payment options

Third Party Validation with Razorpay Payment Gateway

We now support TPV for RazorPay merchants, this allows merchants to specify the consumer accounts from which orders needs to be paid. Since, the consumer bank account information is sensitive, please work with Razorpay to procure public encryption key and pass the encryption information as part of Order details message.

To use this feature which is in alpha testing, please reach out to Meta payments team - whatsappindia-bizpayments-support@meta.com

Updates to Order Details Payload to support TPV

{
  "messaging_product": "whatsapp",
  "interactive": {
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "payment_settings": [
          {
            "type": "razorpay",
            "razorpay": {
              "encrypted_payment_gateway_data": "encrypted-data"
            }
          }
        ],
        "order": {}
      }
    }
  }
}

The raw value before encryption should look someting like the following:

{
  "bank_account": {
    "account_number": "account-no",
    "name": "consumer-cbs-name",
    "ifsc": "ifsc-code"
  }
}

Security Considerations

Businesses should comply with local security and regulatory requirements in India. 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.

Checklist for Integrated Merchants

• Ensure that order_status message is send to consumer informing them about updates to an order after receiving transaction updates for an order.

• Ensure the merchant is verified and WABA contact is marked with a verified check.

• Verify the WABA is mapped to appropriate merchant initiated messaging tier(1k, 10k and 100k per day)

• Merchant should list the customer support information in the profile screen incase consumer wants to report any issues.

• Migrate to "payment_settings" in place of "payment_type" and "payment_configuration". This is the recommended way, and gives access to features likes "notes" and "udf" fields. For an example, view the payloads above.