Setu GST Postpaid: Integration guide
Setu GST Postpaid will enable the SME to pay their GST Challan directly from their SME Lenders/NBFC partners’ application, by utilizing a credit line or short-term loan.
If you are a lender, this guide would help you enable you to enable GST lending for SMEs.
GST Postpaid User Flow
- Challan Creation: SME creates a challan for GST payment on the GSTN Portal or Accounting Software
- Challan Upload: SME Lender/ NBFC (“Lender”) will accept a GST challan (PDF) from an SME through their App.
- Challan Validation: Once Lender receives the PDF, they will invoke the Setu’s Validate GST challan API. Setu will receive this information, validate bill information and respond to Lender. If the response is a success (this means, Setu can accept payment for the challan uploaded), then Lender will make a loan offer to the SME for paying his challan.
- Challan Payment: Once the SME accepts the offer, Lender will call Setu’s Create Bill API to initiate payment for that GST challan. Setu will respond to the lender with a unique Account no. and IFSC code to in the API response for money transfer. Lender will use their banking APIs to transfer money to the account no provided by Setu for that challan
- Challan Reconciliation:. When Setu gets the money in the account, it will initiate a transaction and make a payment to RBI pool account. RBI responds back with a challan payment receipt number. Setu will update this challan payment receipt number for that particular challan on Setu system. Lender can get the updated challan information by polling the Setu’s Get Bill API. Lender can display the receipt number to the SME when the challan has been successfully paid.
API Integration Guide
Registration
To begin your intgeration, contact dev.support@setu.co and get yourself registered as a GST lender. You will receive the auth credentials and the product instace ID to begin the integration.
Authentication
Setu uses the JWT auth mechanism to do autherization. You will receive the following information from Setu once you have registerd.
- JWT scheme ID & JWT secret.
- Product Instance ID
For every request you make to Setu, you will need to set the following HTTP headers on each request:
Authorization: You would use this header to send the JWT token. The mechanism for generating JWT token is descibed on our documentaion. You would be using the JWT scheme ID & JWT secret to generate this token.X-Setu-Product-Instance-ID: In this header you would be sending the Product Instance ID.
Using the APIs
You would be using the following Setu APIs:
validateGSTChallanPDF: To validate the GST challancreateBill: To create a bill on Setu and getting the payment addressgetBillWithID: To get the status of the payment and the receipt number.
1. Validate GST Challan PDF API
Documentation for this API can be found here: https://docs.setu.co/api#operation/validateGSTChallanPDF
POST Request body
You would be sending the PDF as multipart/form-data. The form key is validatePDFRequest and the value is the binary of PDF.
Response body
You would be receiving the a response that would look like this.
{
"status": 200,
"success": true,
"data": {
"Customer": {
"additionalInfo": {
"Mobile": "9XXXXX1795",
"Address": "XXXXXXXXXX Karnataka,560029",
"EmailID": "rXXXXXXX@XXXXXXXXom"
},
"name": "BHARTI AIRTEL LIMITED"
},
"additionalInfo": {
"gstin": "29AAACBXXXXXXXXXX",
"entityName": "JAGANMOHAN ENTERPRISES LIMITED",
"cpin": "19012900432175",
"remittingBank": "KOTAK MAHINDRA BANK LIMITED",
"beneficiaryDetails": {
"accountNo": "XXXXXXXXXXXXXX",
"bankName": "Reserve Bank of India",
"ifsc": "RBIS0GSTPMT"
}
},
"aggregates": {
"discount": {
"amount": {
"value": 0
},
"displayName": ""
},
"fee": {
"amount": {
"value": 0
},
"displayName": ""
},
"itemQuantity": {
"displayName": "",
"quantity": 0
},
"subTotal": {
"amount": {
"value": 0
},
"displayName": ""
},
"tax": {
"amount": {
"value": 0
},
"displayName": ""
},
"total": {
"amount": {
"currencyCode": "INR",
"value": 230000
},
"displayName": "Total Amount"
}
},
"amountExactness": "EXACT",
"billType": "GST",
"billerBillID": "19012900432175",
"customerAccount": {
"additionalInfo": null,
"id": "29AAACB2894G1ZJ"
},
"discounts": null,
"dueDate": "2019-02-09T00:00:00.000Z",
"fees": null,
"generatedOn": "2019-01-25T00:00:00.000Z",
"items": null,
"recurrence": "ONE_TIME",
"taxes": null,
"isValid": true,
"reason": null
}
}
The GST amount is at the path data.aggregates.total.value. In this example, the value is 230000. This value in paisas and the loan amount value is 2300 INR
You need to extract the data attribute from this API and send it as the payload for the createBill API.
2. Create Bill API
Documentation for this API can be found here: https://docs.setu.co/api#operation/createBill
POST Request body
You need to extract the data part of the API response for validateGSTChallanPDF API and use it as the POST request body in this API. The request Content-Type is application/json
For example in the above case, the post body would look like this:
{
"Customer": {
"additionalInfo": {
"Mobile": "9XXXXX1795",
"Address": "XXXXXXXXXX Karnataka,560029",
"EmailID": "rXXXXXXX@XXXXXXXXom"
},
"name": "BHARTI AIRTEL LIMITED"
},
"additionalInfo": {
"gstin": "29AAACBXXXXXXXXXX",
"entityName": "JAGANMOHAN ENTERPRISES LIMITED",
"cpin": "19012900432175",
"remittingBank": "KOTAK MAHINDRA BANK LIMITED",
"beneficiaryDetails": {
"accountNo": "XXXXXXXXXXXXXX",
"bankName": "Reserve Bank of India",
"ifsc": "RBIS0GSTPMT"
}
},
"aggregates": {
"discount": {
"amount": {
"value": 0
},
"displayName": ""
},
"fee": {
"amount": {
"value": 0
},
"displayName": ""
},
"itemQuantity": {
"displayName": "",
"quantity": 0
},
"subTotal": {
"amount": {
"value": 0
},
"displayName": ""
},
"tax": {
"amount": {
"value": 0
},
"displayName": ""
},
"total": {
"amount": {
"currencyCode": "INR",
"value": 230000
},
"displayName": "Total Amount"
}
},
"amountExactness": "EXACT",
"billType": "GST",
"billerBillID": "19012900432175",
"customerAccount": {
"additionalInfo": null,
"id": "29AAACB2894G1ZJ"
},
"discounts": null,
"dueDate": "2019-02-09T00:00:00.000Z",
"fees": null,
"generatedOn": "2019-01-25T00:00:00.000Z",
"items": null,
"recurrence": "ONE_TIME",
"taxes": null,
"isValid": true,
"reason": null
}
Response body
The same bill object from the request would be sent back to you but with a payment address attached to it.
{
"status": 200,
"success": true,
"data": {
"Customer": {
"additionalInfo": {
"Address": "XXXXXXXXXX Karnataka,560029",
"EmailID": "rXXXXXXX@XXXXXXXXom",
"Mobile": "9XXXXX1795"
},
"name": "BHARTI AIRTEL LIMITED"
},
"additionalInfo": {
"beneficiaryDetails": {
"accountNo": "XXXXXXXXXXXXXX",
"bankName": "Reserve Bank of India",
"ifsc": "RBIS0GSTPMT"
},
"cpin": "19012900432175",
"entityName": "JAGANMOHAN ENTERPRISES LIMITED",
"gstin": "29AAACBXXXXXXXXXX",
"remittingBank": "KOTAK MAHINDRA BANK LIMITED"
},
"aggregates": {
"discount": {
"amount": {
"value": 0
},
"displayName": ""
},
"fee": {
"amount": {
"value": 0
},
"displayName": ""
},
"itemQuantity": {
"displayName": "",
"quantity": 0
},
"subTotal": {
"amount": {
"value": 0
},
"displayName": ""
},
"tax": {
"amount": {
"value": 0
},
"displayName": ""
},
"total": {
"amount": {
"currencyCode": "INR",
"value": 230000
},
"displayName": "Total Amount"
}
},
"amountExactness": "EXACT",
"billType": "GST",
"billerBillID": "19012900432175",
"billerProductInstanceID": "162154530992031094",
"customerAccount": {
"id": "29AAACB2894G1ZJ"
},
"discounts": null,
"dueDate": "2019-02-09T00:00:00.000Z",
"fees": null,
"generatedOn": "2019-01-25T00:00:00.000Z",
"items": null,
"recurrence": "ONE_TIME",
"taxes": null,
"name": "Bill-19012900432175",
"paymentAddresses": [
{
"additionalInfo": {
"ifsc": "SETU0000002"
},
"addressType": "ACCOUNT",
"identifier": "SETUSPA7282996538"
}
],
"platformBillID": "218257216422020425",
"platformBillStatus": "CREATED"
}
}
In this API response, the paymentAddresses field is what is relevant for the next step.
In this example the account number allocated to the GST bill is:
{
"additionalInfo": {
"ifsc": "SETU0000002"
},
"addressType": "ACCOUNT",
"identifier": "SETUSPA7282996538"
}
The amount to be paid into Setu’s account.
3. Pay into Setu’s account
You need to pay into Setu’s account using your bank. In this example the account details are
Account Holder's Name: BROKENTUSK TECHNOLOGIES PVT LTD
Account IFSC: SETU0000002
Account number: SETUSPA7282996538
You can choose any of the NEFT/IMPS/RTGS as the payment method.
Use your bank’s payout APIs to carry out the transaction.
Once Setu receives money in the account, it will deposit that money in the RBI’s account and update the bill object. You can poll the getBillWithID API to get the payment status.
4. Get bill with ID API
Documentation for this API can be found here: https://docs.setu.co/api#operation/getBillWithID
This is a GET API and here is what the API response would look like once the payment has been ackowledged by RBI.
{
"status": 200,
"success": true,
"data": {
"Customer": {
"additionalInfo": {
"Address": "XXXXXXXXXX Karnataka,560029",
"EmailID": "rXXXXXXX@XXXXXXXXom",
"Mobile": "9XXXXX1795"
},
"name": "BHARTI AIRTEL LIMITED"
},
"additionalInfo": {
"beneficiaryDetails": {
"accountNo": "XXXXXXXXXXXXXX",
"bankName": "Reserve Bank of India",
"ifsc": "RBIS0GSTPMT"
},
"cpin": "19012900432175",
"entityName": "JAGANMOHAN ENTERPRISES LIMITED",
"gstin": "29AAACBXXXXXXXXXX",
"remittingBank": "KOTAK MAHINDRA BANK LIMITED"
},
"aggregates": {
"discount": {
"amount": {
"value": 0
},
"displayName": ""
},
"fee": {
"amount": {
"value": 0
},
"displayName": ""
},
"itemQuantity": {
"displayName": "",
"quantity": 0
},
"subTotal": {
"amount": {
"value": 0
},
"displayName": ""
},
"tax": {
"amount": {
"value": 0
},
"displayName": ""
},
"total": {
"amount": {
"currencyCode": "INR",
"value": 230000
},
"displayName": "Total Amount"
}
},
"amountExactness": "EXACT",
"billType": "GST",
"billerBillID": "19012900432175",
"billerProductInstanceID": "162154530992031094",
"customerAccount": {
"id": "29AAACB2894G1ZJ"
},
"discounts": null,
"dueDate": "2019-02-09T00:00:00.000Z",
"fees": null,
"generatedOn": "2019-01-25T00:00:00.000Z",
"items": null,
"recurrence": "ONE_TIME",
"taxes": null,
"name": "Bill-19012900432175",
"paymentAddresses": [
{
"additionalInfo": {
"ifsc": "SETU0000002"
},
"addressType": "ACCOUNT",
"identifier": "SETUSPA7282996538"
}
],
"receipt": {
"id": "118257216422021115",
"date": "2019-02-10T12:00:11Z"
}
"platformBillID": "218257216422020425",
"platformBillStatus": "SETTLED"
}
}
The value of platformBillStatus will have the following possible values:
CREATED: When the bill has been created on Setu SystemCREDIT_RECEIVED: When Setu has successfully received credit in the account number allocated to this bill.SETTLED: When the fund has been transferred to RBI.
When the platformBillStatus is SETTLED, the receipt attribute would contain the UTR number and the datetime at which the settlement was successfully done to RBI.