Check GST return-filing status using a GSTIN and an active Pay2New customer/outlet. This is a fresh lookup, not a polling endpoint for a pending Pay2New order. Availability and charges depend on your account configuration.

For registration details such as legal name, address and registration status, use GST Verification.

Endpoint

POST https://pay2new.in/apis/v1/verification/gstStatus

Headers

📘

Before you call

Use an active partner account with verified KYC, an active wallet and API access, and a registered source IP. GST Status must be enabled for your account. The request body outletId must identify an active Pay2New customer/outlet.

Request body

The verification product and charge are selected for your account. You do not need to send product_code or amount.

📘

Current request mapping

Send the GSTIN as number, not gst or GstNumber. outletId belongs in the JSON body. FinancialYear is not exposed or forwarded by the current Pay2New mapping; optional1–optional4 do not select a year. Provider credentials and ApiMode are handled by Pay2New.

Request example

All values are illustrative. Replace the secret, GSTIN, outlet and customer details with the values for your integration.

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/gstStatus' \
  --header 'secret: YOUR_PAY2NEW_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "number": "27ABCDE1234F1Z5",
  "request_id": "GST202609260001",
  "customer_number": "9000000001",
  "latitude": "18.5204",
  "longitude": "73.8567",
  "pincode": "411001",
  "ip": "203.0.113.10",
  "outletId": "YOUR_PAY2NEW_OUTLET_ID"
}'

Response

Early failures may return only status and message. The success wrapper returns status, message, data and order_id; it does not currently echo request_id, txn_value, balance or operator_reference. Preserve your original request reference.

GST return data

Field names are case-sensitive: Data starts with a capital D. The configured provider response is unwrapped into Pay2New data; provider Errorcode, text status and outer response are not the Pay2New response envelope. The empty-result structure below follows the provider GST Status reference and the active Pay2New mapping. It is an illustrative example, not a newly executed customer lookup.

🚧

Lookup success is not proof of filing

status: 1 means the lookup succeeded. An empty data.Data array or null GstNumber/FinancialYear does not prove that returns were filed, the registration is active, or the taxpayer is compliant. Inspect the returned data and use GST Verification for registration information.

📘

Read the application result

A successful HTTP response does not establish a successful GST lookup. Read status and message. A lookup can be chargeable; for an unresolved result, preserve your request reference and reconcile before submitting another request. Replaying a request is not guaranteed to be idempotent.

Errors

Application errors can be returned with a successful HTTP status. For example:

{
  "status": 2,
  "message": "Invalid Json!"
}

For the general GST verification workflow, see GST Verification.

Response examples

Success — no filing records

{
  "status": 1,
  "message": "Transaction Successful",
  "data": {
    "GstNumber": null,
    "FinancialYear": null,
    "Data": []
  },
  "order_id": "P2N_GST_SAMPLE_001"
}

Validation error

{
  "status": 2,
  "message": "Invalid Parameters",
  "errors": {
    "number": "The number field is required."
  }
}

Invalid outlet

{
  "status": 2,
  "message": "Oops, Invalid OutletId!"
}

Service unavailable

{
  "status": 2,
  "message": "Oops, This service is not for you!"
}

Provider mapping unavailable

{
  "status": 2,
  "message": "Operator do not have bill fetch!"
}

Provider response missing status

{
  "status": 2,
  "message": "Status Not Found!"
}

Unresolved result

{
  "status": 3,
  "message": "Something went wrong! Kindly confirm status!"
}

Pending and retry handling

Use unique client references. Do not rely on an automatic GST filing webhook or retry the chargeable lookup merely because a callback is absent.