Skip to content

GSP Configuration

Applies to: e-Invoice · e-Way Bill · Which modules do I have?

Purpose

Configure the connection to the government systems: choose a provider, load its credentials, prove the connection works before it carries live traffic, and understand what a provider switch does to documents already issued.

Audience

System administrators and implementation consultants.

Prerequisites

  • GSP Abstraction — read first; the capability and provenance model explains most of what follows
  • GSP credentials issued for the relevant environment
  • Outbound network path open, and the egress address registered if the provider allow-lists
  • Administrator access

Steps

1. Confirm which provider, and for which environment

Two live providers are supported: Webtel and Masters India. Each has its own credentials and its own endpoint set, and — critically — separate sandbox and production endpoints.

Non-production environments must use sandbox credentials and sandbox endpoints, always. A test document sent with production credentials reaches NIC, consumes a real document number permanently, and cannot be undone.

2. Load the credentials

Provider credentials and endpoint URLs are host-level settings. See Environment Variables for the exact keys.

Item Source Note
Credentials The provider Some providers scope credentials per GSTIN
Endpoint URLs The provider Differ between sandbox and production
Timeouts Default unless the provider advises otherwise Too short produces failures on slow government days; too long ties up resources

Restart the API after changing them.

3. Assign the provider to the tenant

Assignment is made in the admin console, per tenant. Exactly one provider is active at a time for new documents.

4. Test the connection before anything else

Run the built-in provider connection test. Do this before go-live, not on the day.

Result Meaning
Success Credentials, network path and endpoints are all correct
Authentication failure Credentials wrong, expired, or not yet activated by the provider
Connection refused or timeout Network path blocked, or the egress address is not on the provider's allow-list
Certificate error An intercepting proxy whose certificate the application does not trust

The certificate case is the hardest to diagnose unaided, because the provider appears to be down while the network team can demonstrate that the host reaches the internet. If the connection test fails with a certificate error and the network is otherwise fine, look at the proxy first.

5. Review the capability matrix

Providers genuinely differ in what they can do. Review the matrix for the assigned provider against what the business actually needs.

State Meaning What to do
SUPPORTED Available Use it
NOT_SUPPORTED Permanent — this provider or adapter has no such operation Plan a workaround; do not wait
PENDING_VENDOR Temporary — the endpoint has been requested and not yet delivered Track it. Work skipped because of it must be redone when it flips

Do this before go-live. Discovering that a needed operation is unavailable during user acceptance testing is a schedule problem; discovering it in production is an incident.

5b. The complete variable list

Section 5 covers what each provider can do. This is what you set to make it do it.

Every GSP variable this build reads. A blank default means the value is absent unless you set it — and for an endpoint URL, absent means that operation fails rather than falling back to anything.

Variable Default Read by
MI_CLIENT_ID none config/mastersIndia.config.js
MI_CLIENT_SECRET Secret — no default config/mastersIndia.config.js
MI_COMMON_BASE_URL https://commonapi.mastersindia.co config/mastersIndia.config.js
MI_DEFAULT_GSTIN none config/mastersIndia.config.js
MI_EDOC_BASE_URL https://sandb-api.mastersindia.co config/mastersIndia.config.js
MI_LOG_RESPONSES empty string config/mastersIndia.config.js
MI_PASSWORD Secret — no default config/mastersIndia.config.js
MI_STATE_ENCODING CODE config/mastersIndia.config.js, services/GSP/mastersIndia/enums.js
MI_TIMEOUT_MS 60000 config/mastersIndia.config.js
MI_USERNAME none config/mastersIndia.config.js
PROVIDER WEBTEL config/nic.config.js
WEBTEL_CANCEL_EWAYBILL_URL none config/nic.config.js
WEBTEL_CANCEL_URL none config/nic.config.js
WEBTEL_CDKEY Secret — no default config/nic.config.js
WEBTEL_DECRYPT_SIGNED_URL none config/nic.config.js
WEBTEL_DISTANCE_URL none config/nic.config.js
WEBTEL_EXTEND_VALIDITY_URL none config/nic.config.js
WEBTEL_GENIRN2_URL none config/nic.config.js
WEBTEL_GEN_CEWB_URL none config/nic.config.js
WEBTEL_GEN_EWAY_BY_IRN_URL none config/nic.config.js
WEBTEL_GETGSTIN_URL none config/nic.config.js
WEBTEL_GET_EINV_BY_IRN_URL none config/nic.config.js
WEBTEL_GET_GSTN_STATUS_URL none config/nic.config.js
WEBTEL_GSTIN none config/nic.config.js
WEBTEL_GSTIN_LOOKUP_EINV_PASS none config/nic.config.js
WEBTEL_GSTIN_LOOKUP_GSTIN none config/nic.config.js
WEBTEL_MULTIVEH_ADD_URL none config/nic.config.js
WEBTEL_MULTIVEH_INIT_URL none config/nic.config.js
WEBTEL_MULTIVEH_TIMEOUT_MS 60000 services/GSP/webtel.gsp.js
WEBTEL_MULTIVEH_UPD_URL none config/nic.config.js
WEBTEL_PAN_CAPTCHA_URL none config/nic.config.js
WEBTEL_PAN_VALIDATE_URL none config/nic.config.js
WEBTEL_PRINT_EWB_URL none config/nic.config.js
WEBTEL_PRINT_URL none config/nic.config.js
WEBTEL_REGEN_CEWB_URL http://ewaysandbox.webtel.in/Sandbox/EWayBill/v1.3/ReGenConsolidatedEWB config/nic.config.js
WEBTEL_SANDBOX_AUTH Secret — no default config/nic.config.js
WEBTEL_UPDATE_VEHICLE_URL none config/nic.config.js
WEBTEL_WEBAPI_CDKEY Secret — no default config/nic.config.js
WEBTEL_WEBAPI_CLIENT_ID none config/nic.config.js
WEBTEL_WEBAPI_CLIENT_SEC Secret — no default config/nic.config.js
WEBTEL_WEBAPI_UDYAM_CDKEY Secret — no default config/nic.config.js
WEBTEL_WEBAPI_UDYAM_CLIENT_ID none config/nic.config.js
WEBTEL_WEBAPI_UDYAM_CLIENT_SEC Secret — no default config/nic.config.js
WEBTEL_WEBAPI_VALIDATEPAN_URL none config/nic.config.js
WEBTEL_WEBAPI_VERIFYUDYAM_URL none config/nic.config.js

45 variables. Generated from the process.env reads in the backend — do not edit by hand; run node tools/docs/gen-env-reference.js --write.

6. Understand what a switch does

Switching provider affects new documents only. Everything already issued continues to be serviced by the provider that issued it, through the provenance stamp on each document.

Aspect Effect of a switch
New documents Go to the new provider immediately
Existing documents Continue with their original provider, indefinitely
Cancel, extend, update vehicle Routed to the original provider automatically
Feature availability May change — compare matrices before switching
Historical evidence Unchanged and immutable
Old credentials Must remain valid while any document from that provider can still be acted on

The last row is the one most often missed. Decommissioning the old provider's credentials immediately after a switch strands every document it issued — cancellations and extensions then fail, typically with a confusing authentication error rather than a clear explanation.

7. Own credential expiry

Provider credentials expire. An expiry nobody owns becomes a total failure of government operations, arriving without warning, usually at month end.

Practice Detail
Record expiry dates In the operations calendar, with an owner
Set an alert well ahead Enough lead time to obtain replacements from a third party
Rehearse rotation An untested rotation fails when it is needed
Re-test after rotation Run the connection test immediately afterwards

Validation

Check Method Pass condition
Provider assigned Admin console Exactly one active provider for the tenant
Connection test passes Run it from the admin console Success
Correct environment Compare the configured endpoints against the provider's documentation Non-production points only at sandbox
Capabilities cover the business Review the matrix against the required operations Everything needed is SUPPORTED, or has a tracked workaround
End-to-end works Generate one IRN in the sandbox Succeeds, with an IRN and signed QR stored
Provenance stamped Inspect a generated document It records the provider that issued it
Continuing operations follow provenance In a test tenant, switch provider, then cancel a document issued by the old one Succeeds
Outage degrades gracefully Point the provider at a wrong endpoint temporarily Government operations fail; local screens and Branded Print keep working
Expiry owned Operations calendar Dates recorded with a named owner

The outage test is worth running once. It demonstrates concretely that a provider problem is a degradation rather than an outage — a claim the customer would otherwise have to take on trust.

Troubleshooting

Symptom Cause Action
Connection test fails on authentication Credentials wrong, expired, or not activated Confirm with the provider that they are active for this environment
Connection test times out Network path blocked, or egress address not allow-listed Test outbound reachability from the application host; confirm the address the provider sees
Connection test fails on a certificate Intercepting proxy not trusted by the application Trust the proxy's certificate authority. The provider is not down
All government operations fail suddenly, having worked Credentials expired, or the egress address changed Check expiry first, then the egress address. A new NAT or failover path is a common cause
Some operations work, others are unavailable Capability differences Check the matrix. PENDING_VENDOR is temporary; NOT_SUPPORTED needs a workaround
Cancellation fails after a provider switch Old provider's credentials withdrawn too early Restore them until no live document from that provider remains
e-Way Bill from an IRN fails after a switch Correctly routed to the issuing provider, whose credentials are gone Same fix as above
A test document appeared at NIC Non-production environment using production credentials Treat as an incident. The document number is permanently consumed and cannot be released
Provider bill higher than expected An integration polling a read that could be served locally Review the calling pattern. See GSP Abstraction
Intermittent failures at peak Provider rate limiting, or timeouts too short Check the provider's limits; review retry behaviour rather than raising retries blindly