#WhatsApp Collect

#What are WhatsApp Business APIs?

In 2018, WhatsApp released Business APIs that allow businesses to serve their customers via their WhatsApp accounts. Businesses can use these APIs to build various customer experiences.

With Website Name WhatsApp Collect, you can start collecting payments via WhatsApp.

#What is WhatsApp Collect?

(website name)’s WhatsApp Collect product enables businesses to collect payments natively via WhatsApp. Our “pay now” buttons offer a seamless 3-click payment experience for your customer.

To get started, simply set up a WhatsApp business account with one of our partner BSPs.

Time to integrate: 5 days

Time to go live: 2 weeks

#Who are WhatsApp Business Service Providers (BSPs)?

BSPs are entities authorised by Facebook to provision and distribute WhatsApp Business accounts. Website Name has partnered with top BSPs to build a state of the art WhatsApp collection stack.

#How can I use this product?

At (website name), we classify WhatsApp Collect into two product constructs—

• Collection Reminders, where you can send reminders to your customers for any payment to be collected from them.
• Collection Journey, where your customer can initiate a WhatsApp chat to fetch their latest outstanding bill with your business.

For either alternative, a customer can initiate their payment, right from WhatsApp and use any available UPI app on their phone to complete payment.

#Collection Journey

In WhatsApp collection journeys, the customer discovers your WhatsApp business number and starts a conversation. The customer will be taken through a conversational collection journey through which the customer can make a payment.

#Discovery of business number

The customer can discover your WhatsApp number in different ways. Some of the recommended ways are listed below.

WhatsApp Deeplink

WhatsApp officially endorses a specific URL type known as WhatsApp Deeplink. When a customer clicks on this link, they are seamlessly directed to the chat window associated with your Business number. The text box within the chat can be pre-populated with text of your choosing, enabling the customer to initiate a conversation instantly. This feature streamlines the communication process and enhances user engagement.

You can send WhatsApp Deeplinks to your customers via SMS or embed them on your website.

You can create WhatsApp Deeplinks for your business number with (Website Name).

Here’s a standard payment flow on sample WhatsApp Deeplink created by (Website Name)—try it out yourself.

QR Code

You can encode WhatsApp Deeplinks as QR codes, and WhatsApp natively allows you to scan them and start a conversation.

You can use these QR codes in your physical branches and in print and digital advertising campaigns. (Website Name) will help you create customised QR code with your logo on it.

(Website Name) created the QR code below using the WhatsApp Deeplink sample previously shared. Scan and try out the flow—

#How to get started?

Step 1 — Start KYC and business documentation

Once (website name)’s Sales team has interacted with you and confirmed integration, you can get started with KYC and review legal agreements—

1. You can start KYC and review legal agreements once (Website Name)'s Sales team has contacted you and confirmed integration -
2. KYC and business contact details (KYC varies by business category) Sign the SOP agreement with (Website Name) and the pricing agreement.

Step 2 — Link your BSP to Website Name account

Your customers interact with the WhatsApp business account set up via a BSP. All of the top BSPs in the country are integrated with (Website Name).

Step 3 — Finalise the collection journey

Using defined message templates, (Website Name) works with BSP partners to bring your collection journey to life. (Website Name) will help you whitelist templates via your BSP once you confirm message content. Please refer here for a standard (Website Name) collection journey.

Step 4 — Share customer bills

To allow your customers to fetch bills, you need to share your customers' bills with (Website Name). If you are already a BBPS biller, you can integrate with our fetch bill APIs right away.

If you’re not registered as biller, contact (Website Name) for more details on how to get started.

Step 5 — Go live and start collections

You can now track your live transactions on The Bridge once you go live. To learn how to use reports, refer to this guide

#Collection Reminders

(Website Name) WhatsApp Reminders lets you send interactive bill reminders to your customers via WhatsApp. Using your existing WhatsApp Business number provisioned by any BSP, you can send the bill.

An embedded payment link allows the user to pay in three steps through this interactive bill.

#How to get started?

Step 1 — Start KYC and business documentation

Once (Website Name)'s Sales team has interacted with you and confirmed integration, this process will begin. Add a few details and review the agreements—

1. Your KYC and business contact details need to be added (KYC varies based on your business category).
2. The SOP agreement with (Website Name) and the pricing agreement must be signed.

Step 2 — Link your BSP to (Website Name) account

What your customers interact with is the WhatsApp business account set up through a BSP. (Website Name) actively maintains integrations with all top BSPs in the country.

Step 3 — Whitelist the message templates

All reminder messages follow the same template(s) for all customers. As soon as you confirm the message content, (Website Name) will assist you in getting templates whitelisted via your BSP. Please refer here for (Website Name) recommended templates.

Step 4 — Share customer bills

In order to send payment reminders to your customers, you need to share your customers' bills with (Website Name). You can do this by integrating with our APIs for sending bills.

Step 5 — Go live and start collections

Start tracking your live transactions on The Bridge once you go live. To learn how to use reports, refer to this guide

#Recommended use cases

Collections on WhatsApp are most effective when they are linked to a trigger. These APIs should be integrated with the following systems, according to (Website Name).

• Field Agent Collection Portal—Convert your cash collection to digital via WhatsApp
• Call center/IVR - Automated WhatsApp bill reminders can increase your call center's efficiency
• CRM/LMS—Trigger bill reminders based on set business logic

Apart from these recommended use cases, you can still leverage our APIs to integrate with any system of your choice.

#API integration

With these APIs, you can send bills directly to your customers on WhatsApp. For seamless payments, the bills will have an embedded "Pay Now" link.

There are 2 modes in which you could integrate, to be able to send bills—

• Creating and sending a bill—when you know the latest bill amount and want to share it with the customer.
• Fetch latest bill—If you want your system to retrieve the latest bill amount.As per your needs, you can integrate with one or more options.

Note, the production URL is https://prod.(Website Name).co.

#Option 1 — Create and send bill

In this mode, you would know the amount to be collected beforehand and pass it along in the request payload. To send the bill on WhatsApp, (Website Name) will internally generate a UPI deep link and use the existing WhatsApp provider configurations.

Request body

POST /api
{
    "bill": {
        "amount": { // Mandatory
            "value": 20000, // Defined in paisa
            "currencyCode": "INR"
        },
        "billerBillID": "TEST_TRANSACTION_01", // Mandatory
        "expiryDate": "2022-04-28T18:30:59Z", // Optional
        "additionalInfo": { //Optional, with custom key, value pairs
        },
        "amountExactness": "EXACT_DOWN", // Mandatory
        "transactionNote": "Loan Repayment of 200rs", // Optional
        "campaignID": "WA-Coll-Apr-2022", // Optional
        "settlement": { // Optional
          "primaryAccount": {
            "id": "123467890", // Mandatory
            "ifsc": "IFSC12345", // Mandatory
            "name": "" // Optional
          }
        }
    },
    "channels": [{
        "destination": "918147077475", // Mandatory
        "campaignID": "234-2343-234324" // Mandatory
        "channel": "whatsapp", // Mandatory
        "template": { // Mandatory, to be approved
            "name":"Ramesh", // Template Variables
            "loanNumber":"12344"
        }
    }]
} 

• bill.additionalInfo is an object that permits the inclusion of any key-value pair, which will be transmitted back in the webhook notification.
• channels.template adheres to an approved message template. To obtain the precise payload, kindly reach out to (Website Name) along with the whitelisted templates.
• bill.billerBillID serves as an identifier in the merchant's system for future lookup or reconciliation.
• bill.amount.value is the value in paise of the amount needed to be collected from the user, expressed as data type integer
• bill.amount.currencyCode is always set to INR.
• bill.amountExactness allows flexibility in the amount being paid by the customer, as per merchant specification.
  • Specifying EXACT will allow your customer to pay only the exact amount specified by you in the create link API.
  • Specifying ANY will simply allow your customer to pay any amount above INR 1.
  • Specifying EXACT_DOWN will only allow the paid amount to be more than INR 1 and less than the amount specified in the Create bill API.
• bill.transactionNote is a field that allows you to display a note on the Payer application.
• bill.campaignID is a field that allows you to group payment links and view all payments with the same bill.campaignID on Bridge Dashboard.
• channels.campaignID is a Website Name internal Campaign ID that maps to a specific Collection Template and Acknowledgement Template.
• bill.settlement is a dictionary that allows you to specify the details of whitelisted account(s) to which the amount paid needs to be settled to.

Note that UPI does not recognise a “maximum allowed amount” and any payment value above INR 1 will be successful with EXACT_DOWN.

However, paying more than the amount specified in the Create bill API will fail (website name)’s validation, and will be refunded to your customer. Contact our support team for more details on how refunds are handled.

Response

{ 
    "success": true, 
    "status" : 200, 
    "data": { 
        "messageID": "<message id sent by whatsapp provider>", 
        "platformBillID": "", 
        "paymentLink": { 
            "shortURL": "<short_url>", 
            "upiID": "<upi_id>", 
            "upiLink": "<upi_deeplink>" 
        } 
    } 
} 

Add on — Campaign API to share bills in bulk

Most of the time, businesses want to collect bill payments from a lot of their customers at once. Although the above two APIs can be used for that, it’s a tedious job to do so in bulk.

For that reason, we also support a either of the above two actions in bulk using a Campaign API. .

The CSV file format

The following format should be followed while posting the data to (website name).

• The Template Param (1...n) columns of the CSV should contain all the template variables in the same order as in the pre-approved WhatsApp template that would be used for bill reminder campaigns. It cannot be changed once you go live.
• If referenceID is not null, billerBillID on bridge will be dynamically generated in <mobile>_<referenceID> format. Otherwise, it will be mobile.

Request body

POST /api/v1/message/bill/campaign
{
    name: <campaign_name> 
    id: <campaign_id>
    channel: whatsapp,sms
    file: <should contain the csv file>
} 

Response

{ 
    "success": true, 
    "status": 200, 
} 

#Option 2 — Fetch latest bill

In this mode, you would need to be integrated with (Website Name) BBPS BillCollect already. The customer identifiers that are required to fetch the bill are passed in the request body. Once the bill is successfully fetched, we use the configured WhatsApp partner to send the bill to your customer.

Request body

POST /api/v1/message/bill/fetch
{
    "bill": {
        "customerIdentifiers": [{ //Mandatory
          "attributeName": "Loan Number", //Sample value
          "attributeValue": "122342" //Sample value
        },{
          "attributeName": "Loan Type", //Sample value
          "attributeValue": "cat loan" //Sample value
        }]
    },
    "channels": [{
        "destination": "918147077475", //Mandatory
        "campaignID": "234-2343-234", //Mandatory
        "channel": "whatsapp", //Mandatory
        "template": { //Mandatory, to be approved
            "name":"Ramesh", //Template Variables
            "loanNumber":"12344"
        }
    }]
}

• channels.template is based on the message template approved. Please contact (Website Name) along with the whitelisted templates, to get the exact payload.

Response

{ 
    "success": true, 
    "status" : 200, 
    "data": { 
        "messageID": "<message id sent by whatsapp provider>", 
        "platformBillID": "", 
        "paymentLink": { 
            "shortURL": "<short_url>", 
            "upiID": "<upi_id>", 
            "upiLink": "<upi_deeplink>" 
        } 
    } 
} 

Add on — Campaign API to share bills in bulk

This works similarly to the "Create bill" mode. CSV files are now formatted as follows:

The CSV file format

The following format should be followed while posting the data to (Website Name).

• The Template Param (1...n) columns within the CSV file should encompass all template variables arranged in the exact order as the pre-approved WhatsApp template designated for bill reminder campaigns. This order is immutable once your system goes live.

For API details, refer to this.

#Error codes

Below, we have listed out various error scenarios that you may encounter while calling our APIs.