Receive WhatsApp Payments via Payment Links
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:
Get Payment Link from Payment Gateway
Once the consumer has expressed their interest to purchase an item using payment link. Business needs to call payment gateway with necessary information like reference-id, amount and validity to generate the payment link. Following is a sample payment link:
https://rzp.io/i/rNiAagU8yBusiness needs to use the same reference-id, amount and expiration in invoice(order_details) interactive message.
Assemble the Interactive Object
To send an order_details message, businesses must assemble an interactive object of type order_details with the following components:
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_idis not present. The country of origin of the product
importer_name string
Required if
catalog_idis not present. Name of the importer company
importer_adress string
Required if
catalog_idis 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
100forINR
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
100forINR
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
100forINR
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
100forINR
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 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_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://the-payment-link"
}
}
],
"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_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://the-payment-link"
}
}
],
"currency": "INR",
"total_amount": {
"value": 21000,
"offset": 100
},
"order": {
"status": "pending",
"expiration": {
"timestamp": "utc_timestamp_in_seconds",
"description": "cancellation-explanation"
},
"items": [
{
"retailer_id": "1234567",
"name": "Product name, for example bread",
"amount": {
"value": 10000,
"offset": 100
},
"quantity": 1,
"sale_amount": {
"value": 100,
"offset": 100
},
"country_of_origin": "country-of-origin",
"importer_name": "name-of-importer-business",
"importer_address": {
"address_line1": "B8/733 nand nagri",
"address_line2": "police station",
"city": "East Delhi",
"zone_code": "DL",
"postal_code": "110093",
"country_code": "IN"
}
},
{
"retailer_id": "14325",
"name": "Product name, for example bread",
"amount": {
"value": 10000,
"offset": 100
},
"quantity": 1,
"sale_amount": {
"value": 100,
"offset": 100
},
"country_of_origin": "country-of-origin",
"importer_name": "name-of-importer-business",
"importer_address": {
"address_line1": "B8/733 nand nagri",
"address_line2": "police station",
"city": "East Delhi",
"zone_code": "DL",
"postal_code": "110093",
"country_code": "IN"
}
}
],
"subtotal": {
"value": 20000,
"offset": 100
},
"tax": {
"value": 1000,
"offset": 100,
"description": "optional_text"
},
"shipping": {
"value": 1000,
"offset": 100,
"description": "optional_text"
},
"discount": {
"value": 1000,
"offset": 100,
"description": "optional_text",
"discount_program_name": "optional_text"
}
}
}
}
}
}Add Common Message Parameters
Once the interactive object is complete, append the other parameters that make a message: recipient_type, to, and type. Remember to set the type to interactive.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
// interactive object here
}
}Make a POST Call to Messages Endpoint
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"
} ]
}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 reference-id passed in order_details message can be used to map the transaction to the consumer invoice or interactive order details message.
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:
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.
The following table describes the returned values:
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
Last updated
Was this helpful?