# 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

1. **Challan Creation:** SME creates a challan for GST payment on the GSTN Portal or Accounting Software
2. **Challan Upload:** SME Lender/ NBFC (“Lender”) will accept a GST challan (PDF) from an SME through their App.
3. **Challan Validation:** Once Lender receives the PDF, they will invoke the [Setu's Validate GST challan API.](https://docs.setu.co/api#operation/validateGSTChallanPDF) 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.
4. **Challan Payment:** Once the SME accepts the offer, Lender will call [Setu's Create Bill API](https://docs.setu.co/api#operation/createBill) 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
5. **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.](https://docs.setu.co/api#operation/getBillWithID) 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 [e-mail] and get yourself registered as a GST postpaid lender on the Setu Bill Network. 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.

1. JWT scheme ID & JWT secret.
2. Product Instance ID

For every request you make to Setu, you will need to set the following HTTP headers on each request:

1. `Authorization`: You would use this header to send the JWT token. The mechanism for generating JWT token is descibed on [our documentaion](https://docs.setu.co/authentication). You would be using the JWT scheme ID & JWT secret to generate this token.
2. `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:

1. `validateGSTChallanPDF`: To validate the GST challan
2. `createBill`: To create a bill on Setu and getting the payment address
3. `getBillWithID`: 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:

1. `CREATED`: When the bill has been created on Setu System
2. `CREDIT_RECEIVED`: When Setu has successfully received credit in the account number allocated to this bill.
3. `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.