GST GSP API Reference

Environments

ClearTax GST GSP has 2 environments:
    1.
    Sandbox Environment
    2.
    Production Environment

Sandbox Environment

For testing, it is recommended to always use the sandbox environment. To create an account, contact our sales representative with the following information:
    1.
    Company Name
    2.
    Company Address
    3.
    Company Website address
    4.
    Authorized Signatory Name
    5.
    Contact Email ID
    6.
    Contact Mobile No
    7.
    PAN No
    8.
    Aadhaar No
    9.
    Type of user (Choose one of Normal Taxpayer, Composite User, TCS User, TDS User, ISD User)
    1.
    All the fields mentioned above are mandatory.
    2.
    The OTP will be sent to the contact details given above. Hence, please provide these details accordingly.
    3.
    Please ensure that valid DSC is available against the PAN given above. Otherwise, the filing of GSTR will not be possible.
    4.
    Aadhaar will be used for eSigning the GSTR.
Once a request for sandbox GSTIN credential creation is placed, GSTN processes the request fortnightly. So if you have applied on 1st Feb, you should expect credentials by 15th Feb.
Host:
1
https://sandbox.gsp.cleartax.in/
Copied!
Port: 443
IP: ClearTax does not use static IP for APIs. You can whitelist the endpoints based on the host.
SSL Certificate:
In case you want to add the SSL certificate of our sandbox host to your trust manager, you can download it here.
wildcard.gsp.cleartax.in.cer
2KB
Binary
ClearTax GST GSP Wildcard

GSTN server public key

You can download the latest public key of GSTN for sandbox environment from https://developer.gst.gov.in/apiportal/howToStart/download

Production Environment

Once you have completed testing, you can move to production. To create an account, contact our sales representative with the following information:
    1.
    Company Name
    2.
    Contact Name
    3.
    Contact Email
    4.
    Contact Phone
For API requests to the production environment, use the below information.
Host:
1
https://gsp.cleartax.in/
Copied!
Port: 443
IP: ClearTax does not use static IP for APIs. You can whitelist the endpoints based on the host.
SSL Certificate:
In case you want to add the SSL certificate of our production host to your trust manager, you can download it here. (This is valid only till 25 June 2021)
gsp.cleartax.in.cer
1KB
Binary
ClearTax GST GSP Production SSL Certificate
With effect from 25 June 2021, the SSL certificate of our production host will be changed to the below certificate.
wildcard.gsp.cleartax.in.cer
2KB
Binary
ClearTax GST GSP Wildcard

GSTN server public key

You can download the latest public key of GSTN for the production environment from https://developer.gst.gov.in/apiportal/howToStart/download

API documentation

Authentication

All requests require the user authentication token in the request header.
1
X-CT-Auth-Token: <YOUR-AUTH-TOKEN-HERE>
Copied!
To generate an authentication token, please contact ClearTax GST Sales.
For all new users, you DO NOT have to add clientid and client-secret to the request headers.
For customers migrating from Karvy, please contact [email protected] for your updated karvyclientid and karvyclient_secret.

Sample Request

1
curl --location --request POST 'https://gsp.cleartax.in/api/taxpayerapi/v0.2/authenticate' \
2
--header 'Content-Type: application/json' \
3
--header 'appkey: 48Kw7zR3L9nsbBJI3BJBmg8K0cx/XoGzR6uJaksufhaksfochguhJk1DTvvHYQqQwaU0yhOqfZHgalD9sGMikaEBmY7Y1YcjP5drvwhmmcqQmCLK3D1FE18ditvlqV4DWou5feLM07QwWTj/i8mDwc5YgWz0cYnr6r7wnd2nlbmMxdHOYbKjOP6SxOdD2Gb6GZDI5+RFkkfGSPKwtvXR9NfZQaLaTIY1w8O0X0NI56C9oqjcqT5+FgdpTnLYc3rodHJuEFVgqfeTpWSk3QfAcnQg9P1N9Azcx2OI+AXbLLhcLLbSpfveelhaK02uEdUDYgGHfztr//9RPfqOzg==' \
4
--header 'X-CT-Auth-Token: a2ceb341-asf12-1234-a54f-59d934acasaa' \
5
--header 'state-cd: 33' \
6
--header 'ip-usr: 123.456.789.100' \
7
--header 'txn: txn123' \
8
--header 'gstin: gstinNumber' \
9
--header 'username: username' \
10
--data-raw '{"action":"OTPREQUEST","app_key":"48Kw7zR3L9nsbBJI3BJBmg8K0cx/XoGzR6uJaksufhaksfochguhJk1DTvvHYQqQwaU0yhOqfZHgalD9sGMikaEBmY7Y1YcjP5drvwhmmcqQmCLK3D1FE18ditvlqV4DWou5feLM07QwWTj/i8mDwc5YgWz0cYnr6r7wnd2nlbmMxdHOYbKjOP6SxOdD2Gb6GZDI5+RFkkfGSPKwtvXR9NfZQaLaTIY1w8O0X0NI56C9oqjcqT5+FgdpTnLYc3rodHJuEFVgqfeTpWSk3QfAcnQg9P1N9Azcx2OI+AXbLLhcLLbSpfveelhaK02uEdUDYgGHfztr//9RPfqOzg==","username":"yourusername"}'
Copied!
For further information on different endpoints like returns, ledger, payment, etc, please refer to the GSTN documentation at https://developer.gst.gov.in/apiportal/

Error Codes

In case you have received an error code from GSTN, you can check the description of the code in the respective API page here: https://developer.gst.gov.in/apiportal/
Last modified 4mo ago