Receive UPI Payments Through WhatsApp

Your business can enable customers to pay for their orders using all the UPI Apps installed on their devices via WhatsApp. Businesses can send customers invoice(order_details) messages, then get notified about payment status updates via webhook notifications from Payment Gateway.

Overview

Currently, customers browse business catalogs, add products to cart, and send orders in with our set of commerce messaging solutions, which includesSingle Product Message, Multi Product Message, and Product Detail Page.

With the WhatsApp Payments API, businesses can send customers a bill so the customer can complete their order with all the UPI Apps.

How It Works

The business must send an order_details message for the consumer to initiate payment. This type of 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 number is used throughout the flow to track the order. This reference_id is fetched from UPI intent link(tr value from the UPI payment intent) generated for a business order from Payment Gateway.

Once the message is sent, the business waits for a payment or transaction status updates directly from Payment Gateway. Upon receiving payment signal for an order, Business should relay this payment signal to consumer through interactive order status(order_status) message.

Updating user about the payment signal is important as this message updates the order details message and order details view for the consumer reflecting the order confirmation from merchant. This is shown with an example in subsequent sections.

Purchase Flow in App

In the WhatsApp customer app, the purchase flow has the following steps:

1. Customer sends an order with selected products to the business or Business identifies the products that the customer has shown interest to purchase.
2. After receiving the order/identifying the product, if a merchant accepts payment methods other than UPI, such as credit cards and payment wallets, then merchant will send a message to the user to get their preferred payment method for the order.
   
3. When consumers want to pay using UPI payment method, then merchants should retrieve the UPI payment intent by calling Payment Gateway. Merchant needs to use UPI intent to construct order details messages and send it to the consumer.
   
4. When the consumer taps the Pay now/continue button, they will be given the option to choose UPI payment Apps - WhatsApp or any other UPI payments apps. Consumers may choose any UPI option to pay for the order.
   
5. Consumer pays for the order and the payment method is saved for the future and automatically selected for the next payment transaction. Also, one quick note is the order details screen order-status will continue to show "Order pending" until merchant sends order status interactive message.
   
6. Once the payment is complete, the business receives a notification from Payment Gateway and the merchant needs to send order status updates to the consumer client notifying consumers about the progress to the order, this will update the order details message CTAs and order details screen - order status description.
   

Before You Start

To receive UPI payments on WhatsApp merchants have to set up their VPA on WhatsApp Business Manager using the direct payment methods option.

Each configuration must have a unique name, merchant categorization code (mcc), purpose code, and VPA handles as shown below. A business can have multiple payment configurations, but for each order merchant must specify a specific configuration to be used for payment. See payment_configuration field in order_details message.

[ 
  { 
    "name": "unique name 1", 
    "merchantVpa": "handle_1@paytm",
    "merchantMcc": "merchant categorization code",
    "merchantPurposeCode": "purpose code"
  },
  { 
    "name": "unique name 2", 
    "merchantVpa": "handle_2@paytm",
    "merchantMcc": "merchant categorization code",
    "merchantPurposeCode": "purpose code"
  },
]

name for each payment type must be unique. name will be used to reference the specific configurations for each payment type. If WA is unable to find a payment configuration name, the user will not be able to make the payment upon receiving the order_details message. mcc refers to a merchant categorization code for the items in the order. upi_pc refers to the purpose of the transaction. Some sample codes are below:

Manage Your Payment Methods (Beta Feature)

Self-service Payment Configuration allows you to add multiple payment configurations to your WhatsApp Manager profile. Each payment configuration will have its own UPI handle(VPA), MCC, and purpose code (for physical goods) so that merchants can accept payments for different categories with different UPI accounts. After setup, merchant can send invoice(order_details) messages to users with the corresponding payment configuration to collect payments.

Pre-requisites

Manage Payment Methods feature is in Beta, so please contact Business Engineering team to allow merchants/partners access the page in WhatsApp Business Manager portal.

Steps to link Payment Configuration for a Business Service Provider

You can create a payment configuration for a WhatsApp Business Account using the 'Payment configurations' page and under 'India' in WhatsApp Business Manager.

After linking your payment configuration, 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 is about to send order details message to consumer client.

The following sequence diagram demonstrates the typical integration flow for WA Payments API:

Step 1: Get UPI Intent from Payment Gateway

Once the consumer has expressed their interest to purchase an item using UPI payment method. Merchant needs to call payment gateway to create a UPI intent, the following is the sample UPI intent link:

upi://pay?pa=cfsukoonaa@yesbank&pn=Sukoon&tr=877376394&
	am=10.00&cu=INR&mode=00&purpose=00&mc=5399&tn=877376394

Merchant needs to parse the tr value from the above URI and use this as the reference id in invoice(order_details) interactive message.

Step 2: Assemble the Interactive Object

To send an order_details message, businesses must assemble an interactive object of type order_details with the following components:

Parameters Object

Order Object

Item Image 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_type": "upi",
        "payment_configuration": "unique-payment-config-id",
        "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 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_type": "upi",
        "payment_configuration": "unique-payment-config-id",
        "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.

Step 5: Consumer Pays for the Order

Consumers can pay using WhatsApp payment method or using any UPI supported app that is installed on the device.

Step 6: Get Notified About Transaction Status Updates from payment gateway

Businesses receive updates to the invoice via payment gateway webhooks, when the status of the user-initiated transaction changes. The unique identifier tr(reference-id passed in order_details message) can be used to map the transaction to the consumer invoice or interactive order details message.

Please refer to our PG integration guide for the exact payment sigals. [PayU], [Cashfree], [RazorPay] and Billdesk

Step 7: Update order status

Upon receiving transaction signals from payment gateway through webhook, the business must update the order status to keep the user up to date. Currently we support the following order status values:

Typically businesses update the order_status using either the WhatsApp payment status change notifications or their own internal processes. To update order_status, the partner sends an order_status message to the user.

{
  "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 returned values:

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

Step 8: Reconcile Payments

Businesses should use their bank statements to reconcile the payments using the reference_id provided in the order_details messages.

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": {
         "preferred_payment_methods": [
             {
                "method": "Application-ID"
             }
          ]
          ....
      }       
      "order": ..
      }
    }
  }
}

List of supported apps:

Optional Signals

When the consumer opts to use WhatsApp UPI payment method to pay for an order, upon completion of payment WhatsApp would send the merchant the following webhook signals. For this merchant should first need to onboard on to WhatsApp Payments.

Get Notified About Transaction Status Updates (For WhatsApp Pay Transaction only)

Businesses receive updates via WhatsApp webhooks when the status of the user-initiated transaction changes. A webhook notification for an updated transaction status looks like this:

{
  "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]"
            },
            "timestamp": "notification_timestamp"
         }]
      },
      "field": "messages"
    }]
  }]
}

Transaction status webhook payload constains the following fields within the status object:

For more information, see Components, Statuses Object.

Get Payment Confirmation Webhook

When a transaction with a customer is successful, the business gets the following: - A transaction status update with the status as success as seen in the transaction status table above. - A payment confirmation message webhook notification

The payment confirmation message webhook is of interactive and includes the following fields:

An example payment confirmation webhook looks like this:

{
  "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": [{
            "from": "sender_wa_id",
            "group_id": "group_id",
            "id": "message_id",
            "timestamp": "message_timestamp",
            "type": "interactive",
            "interactive": {
              "type": "payment",
              "payment": {
                "transaction_id": "[UPI_BANK_RRN]",
                "transaction_type": "upi",
                "reference_id": "[REF_ID]",
                "total_amount": {
                  "value": 100,
                  "offset": 100
                },
                "currency": "INR",
                "status": "success"
              }
            }
          }],
         "statuses": [{...}]
      },
      "field": "messages"
    }]
  }]
}

Confirm Payment Status

After receiving the transaction status notification, payment confirmation message, or at any time, the business can look up the status of the payment for an order. To do that, businesses must make a GET call to [PHONE_NUMBER_ID]/payments/{payment_configuration }/{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 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": "[UPI_BANK_RRN]",
        "type": "upi",
        "status": "failed",
        "created_timestamp": "[CREATED_TIMESTAMP]",
        "updated_timestamp": "[UPDATED_TIMESTAMP]"
      },
      {
        "id": "[UPI_BANK_RRN]",
        "type": "upi",
        "status": "success",
        "created_timestamp": "CREATED_TIMESTAMP]",
        "updated_timestamp": "UPDATED_TIMESATMP]"
      }
    ]
  }]
}

A response can return the following values:

Payment Status

We support the following payment statuses:

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

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 informatoin in the profile screen incase consumer wants to report any issues.