Biller System

Say you want to start collecting bills for your business using Setu Collect Network. Here is how you go about doing it as a developer.

Let us take this scenario

1. You can query bills from your existing software system using a unique identifier. Say it is the mobile number of the customer.
2. At any given time, your customer either has an outstanding amount to be paid or not.

Customer parameters

You would first need to define your customer parameters. Since you only need the mobile number of the customer to identify them, here is what your customer parameter definition looks like.

"customerParameters" : [{
   "displayName" : "Mobile number",
   "attributeName" : "mobileNumber",
   "dataType" : "string",
   "minLength" : 10,
   "maxLength" : 10,
   "isMandatory" : true
}]

You will need to submit this definition as part of your onboarding process into Setu Collect. The steps to do so are at the end of this article.

Defining APIs

In its simplest form, a Setu compatible biller system needs to implement the following Web APIs

1. Fetch bills
2. Fetch receipt

Both these APIs are authenticated using a JWT mechanism. It is documented in detail here.

Fetch Bills API

While the Setu Collect allows for a very detailed bill object that the biller needs to configure. You can find more details here.

Your API URL should look like:

https://<partner-base-api-url>/bills/fetch 

In our example, here is what we will send back to Setu when it sends the following request.

{
  "customerIdentifiers": [
    {
      "attributeName": "mobileNumber",
      "attributeValue": "<10 digit mobileNumber>"
    }
  ]
}

Based on the values in this object, you will need to handle the following scenarios.

1. Mobile number is not registered on your side.
2. The customer does not have an outstanding.
3. The customer has an outstanding.

If customer is not found in your system:

If there is no such customer in your account or the customer does not have any outstanding dues, you can send this response.

{
  "success": true,
  "status": 200,
  "data": {
    "customer": {
      "name": "Not Found"
    },
    "billDetails": {
      "billFetchStatus": "NO_OUTSTANDING",
      "bills": []
    }
  }
}

Setu will communicate this to the payer apps connected to the Setu Collect Network.

If customer is found but has no outstanding:

{
  "success": true,
  "status": 200,
  "data": {
    "customer": {
      "name": "Ashok Kumar"
    },
    "billDetails": {
      "billFetchStatus": "NO_OUTSTANDING",
      "bills": []
    }
  }
}

Notice that the billFetchStatus here is NO_OUTSTANDING.

If customer is found and has an outstanding:

If the customer is found in your system and say has an outstanding of ₹990.00, you can construct this bill object.

{
  "amountExactness": "EXACT",
  "aggregates": {
    "total": {
      "amount": {
        "value": 99000
      },
      "displayName": "Total Outstanding"
    }
  },
  "generatedOn": "2019-08-01T08:28:12Z",
  "billerBillID": "12123131322",
  "customerAccount": {
    "id": "8208021440"
  },
  "recurrence": "ONE_TIME"
}

And send it in the response.

{
  "success": true,
  "status": 200,
  "data": {
    "customer": {
      "name": "Ashok Kumar"
    },
    "billDetails": {
      "billFetchStatus": "AVAILABLE",
      "bills": [
        <BILL OBJECT>
      ]
    }
  }
}

Notice that the billFetchStatus here is AVAILABLE. Also the bill itself accepts only EXACT payments.

The Setu Bill API contracts allow for a lot of information to be passed to the payer apps. For an example of how to send line items and bill fees, read this article.

See more explanation about the bill object by reading our documentation on the fetch bills API.

Fetch receipt API

When Setu receives the payment against a given bill, it will make a call to your fetch receipt API.

Your API URL should look like

https://<partner-base-api-url>/bills/fetchReceipt

The fetch receipt API would sending data that would look like this in the request for the bill above.

{
  "billerBillID": "12123131322",
  "paymentDetails": {
    "amountPaid": {
      "value": 99000 
    },
    "billAmount": {
      "value": 99000
    },
    "platformTransactionRefID": "TXN12121219",
    "uniquePaymentRefID": "XXXXAYYDDD999999"
  },
  "platformBillID": "SETU121341312121"
}

Here is what you are expected to do when you receive this call:

1. In your database, create a receipt against this billId and platformTransactionRefID.
2. Update your ledger to reflect the new balance for the customer.
3. Respond back with a receipt

Here is the data you need to send back for the receipt:

{
  "data": {
    "billerBillID": "12123131322",
    "receipt": {
      "date": "2019-08-02T07:12:10Z",
      "id": "R12289171221"
    },
    "platformBillID": "SETU121341312121",
    "platformTransactionRefID": "TXN12121219"
  },
  "status": 0,
  "success": true
}

Next steps

Finished integration and ready to submit it to our sandbox? Apply to Setu Collect Network by filling this form and let us know at our dev support email.