Stiamo disattivando l'API On-Premises. Consulta il nostro documento Disattivazione API On-Premises per i dettagli e per scoprire come eseguire la migrazione alla nostra API Cloud di nuova generazione.

L'account business di Meta, a volte chiamato account Business Manager o semplicemente account business, è stato rinominato in portfolio business. Questa modifica sarà introdotta gradualmente in tutte le tecnologie di Meta. La modifica è solo di carattere estetico e non influisce sugli ID di account business di Meta (ID del portfolio business).

Receive UPI Payments Through WhatsApp

For businesses working with Razorpay or PayU payment gateways, we have deeper integration with these PGs. Please refer to Payment Gateway Integration Guide

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.

This feature is only available for businesses based in India and their Indian customers. To enable payments for your businesses, please contact your Solution Partner. For any other questions about Payments on WhatsApp Business Platform please fill out this form.

Overview

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

Security Considerations

Payment configurations such as the business's VPA shared by all WhatsApp phone numbers must belong to the same business portfolio. If a business wants to separate payments for different phone numbers, then additional portfolios must be created.

Businesses should not rely solely on the status of the payment or transaction provided in the payment gateway webhook. They can also use payment lookup API to retrieve the statuses from the payment gateway. Businesses must always sanitize and validate the data in the API responses or webhooks to protect against SSRF attacks.

Before You Start

To receive UPI payments on WhatsApp, merchants have to set up their VPA on WhatsApp 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:

CodeTitle

00

Default

01

SEMI

02

AMC

03

Travel

04

Hospitality

05

Hospital

06

Telecom

07

Insurance

08

Education

09

Gifting

10

Others

If merchant/partner is not sure of the MCC and purpose code, then they may contact Payment Gateway to get this information as Payment Gateway sets up these values based on the type of business while generating business VPAs.

Manage Your Payment Methods

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

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.

Si è verificato un errore
Stiamo riscontrando problemi con la riproduzione di questo video.

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

Si è verificato un errore
Stiamo riscontrando problemi con la riproduzione di questo video.

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.

Get Started

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:

ObjectDescription

type

object

Required.

Must be set to "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 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. Use review_and_pay

parameters object

Parameters Object

ObjectDescription

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 the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id (for example, -) 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

  • Required. Name of the city.

state string

  • Required. Name of the state.

country string

  • Required. Must be "India".

postal_code string

  • Required. 6-digit zipcode of shipping address.

payment_configuration

Required.

The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters.

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.

order

object

Required.

See order object for more information.

Order Object

ObjectDescription

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 string

  • Required. The price per item

sale_amount amount object with value and offset as describes above in total_amount field

  • 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 - only supports integer, api client returns validation error if sent decimal

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

By the end, the interactive object for 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_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": [{
              "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"
          }
        }
      }
    }
  }
}  

For the catalog-based integration the order_details interactive message should look like the following:

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

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.

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

These are parameters common to all message types.

Step 4: Make a POST Call to /messages

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

{
  "messages": [{
    "id": "{message-id}"
  }]
}

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

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:

ValueDescription

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 partner/merchant 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

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:

ValueDescription

reference_id

The ID provided by the partner in the order_details message

status

The new order status

description

Optional text for sharing status related information in order_details. Could be useful while sending cancellation. Max character limit is 120 characters

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

Merchant should always post this order-status message to consumer after reciving transaction updates for an order. As the order_details message and order details screen experience is tied to to the order status updates.

Step 8: Reconcile Payments

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

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. To support payments, webhook notifications will include the following updates:

  • The type field can now have the value of payment
  • A new payment object will be included inside statuses. The new object mentions reference_id, the field supplied by the business in their order_details object
  • The status field can have the following values:

Transaction Status

StatusDescription

pending

The transaction started

failed

The transaction failed

success

The transaction succeeded

canceled

The transaction was canceled

For more information, see Components, Statuses Object.

A webhook notification for an updated payment status looks like this:

POST /
{
  "statuses": [{
    "id": "gBGGFlB5YjhvAgnhuF1qIUvCo7A",
    "from": "16315555555",
    "type": "payment",
    "status": "new-transaction-status",
    "payment": {
      "reference_id": "reference-id-value"
    },
    "timestamp": "1610561171"
  }]
}

Get Payment Confirmation

When a transaction with a customer is successful using WhatsApp Payment method, 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 an interactive type and includes the following fields:

FieldDescription

transaction_id

Unique id of UPI transaction

transaction_type

Type of payment interface for processing the transaction. Currently in India it is upi

reference_id

The partner supplied an ID that uniquely identifies the order_details message for this partner

total_amount

The total amount for this payment

currency

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

status

The new transaction status. See transaction status table for possible values.

An example payment confirmation notification looks like this:

{
  "messages": [{
    "from": "sender_wa_id",
    "group_id": "group_id",
    "id": "message_id",
    "timestamp": "message_timestamp",
    "type": "interactive",
    "interactive": {
      "type": "payment",
      "payment": {
        "transaction_id": "seq-no, id-of-upi-transaction",
        "transaction_type": "upi",
        "reference_id": "unique ID assigned by merchant",
        "total_amount": {
          "value": 100,
          "offset": 100
        },
        "currency": "INR",
        "status": "success"
      }
    }
  }]
}

Confirm Payment Status - Depreciated

After receiving the payment status change notification and only when the payment is made using WhatsApp Pay method, 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_configuration}/{reference_ID}, using the reference ID provided in the order_details message.

Businesses should expect a response in the same HTTP session (not in a webhook notification). A response can return the following values:

FieldDescription

payment_configuration

The name of the pre-configured payment configuration that is used in sending order-details message.

reference_id

The ID provided by the partner in the order_details message

status

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

currency

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

total_amount

The total amount for this payment

transactions

The complete list of transactions for this payment

transactions.id

The ID of the transaction

transactions.type

The payment type for this transaction. Currently, only upi is supported

transactions.status

The status of the transaction. Currently at most one transaction for each payment can have a pending or success status.

Payment Status

StatusDescription

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": "upi-txn-id",
        "type": "upi",
        "status": "status-of-transaction",
        "created_timestamp": "timestamp",
        "updated_timestamp": "timestamp"
      },
      {
        "id": "<transaction-2-id>",
        "type": "upi",
        "status": "status-of-transaction",
        "created_timestamp": "timestamp",
        "updated_timestamp": "timestamp"
      }
    ]
  }]
}

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

{
  "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 WhatsApp On-Premises API, Errors.

Errors and Statuses

These are the relevant errors for the WhatsApp Payments API:

Error CodeDescription

2040 - Message is not supported

The message you are trying to send cannot be received by this user

2046 - Order status invalid transition

The order status cannot be updated from the existing value to the new one

2047 - Order cancellation failure

The order could not be cancelled

For a comprehensive list with detailed descriptions of error codes and HTTP status codes, please refer to these pages:

On-Premises API Client Error Codes

HTTP Status Codes

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.