#API integration

These set of APIs allow you to send bills to your customers directly on WhatsApp. The bills will have an embedded “Pay Now” payment link for seamless payments.

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

• Create and send bill—when you know the latest bill amount and want to create and share bill with the customer.
• Fetch latest bill—when you want the latest bill amount to be fetched from your system.

You can choose to integrate with one or more options as per your requirements.

Note, the production URL is https://prod.setu.co.

#Option 1 — Create and send bill

In this mode, you would know the amount to be collected beforehand and pass the amount in the request payload. Setu will then internally generate a UPI deep link and use the existing WhatsApp provider configurations to send the bill on WhatsApp.

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 where you can pass any key, value. This will be passed back in webhook notification.
• channels.template is based on the message template approved. Please contact Setu along with the whitelisted templates, to get the exact payload.
• bill.billerBillID is an identifier for this link in merchant’s system which they will later look up or reconcile against.
• 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 would always be 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 Setu 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 Setu’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 Setu.

• 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 Setu 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 Setu 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 similar to how it does in the “Create bill” mode. However, the CSV file format is changed to the following—

The CSV file format

The following format should be followed while posting the data to Setu.

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

For API details, refer to this.