Verification Integration Guide

DigiLocker, PAN Verification, PAN Details Verification, and GST Verification integration reference. Examples use synthetic customer data and placeholder credentials.

1. Overview and API Summary

Production base URL: https://pay2new.in

Service	Operation	Endpoint
DigiLocker	Verify account	`POST /apis/v1/verification/digilocker/verifyAccount`
DigiLocker	Create consent URL	`POST /apis/v1/verification/digilocker/createUrl`
DigiLocker	Check status	`POST /apis/v1/verification/digilocker/status`
DigiLocker	Retrieve document	`POST /apis/v1/verification/digilocker/document`
PAN Verification	Basic PAN validation	`POST /apis/v1/verification/pan`
PAN Details	Detailed PAN verification	`POST /apis/v1/verification/panDetails`
GST Verification	GSTIN validation and details	`POST /apis/v1/verification/gst`

General characteristics

All endpoints use HTTPS and the POST method.
Request and response payloads use JSON.
Authentication is performed using the Pay2New-issued secret request header and source-IP whitelisting.
Commercial charges and wallet deductions are applied according to the client’s active Pay2New package.

2. Authentication and Common Conventions

2.1 Required headers

Header	Required	Value / Description
`secret`	Yes	API secret supplied to the client by Pay2New. Send it exactly as issued.
`Content-Type`	Yes	`application/json`
`Accept`	Recommended	`application/json`

secret: <YOUR_PAY2NEW_SECRET>
Content-Type: application/json
Accept: application/json

🚧
Source IP requirement
The public IP from which the request reaches Pay2New must be whitelisted on the partner account. The JSON ip field does not replace source-IP whitelisting.

2.2 Common top-level status values

Value	Meaning	Client action
`1`	Request processed successfully at the Pay2New layer.	Read the service-specific response. For DigiLocker status/document calls, also inspect `data.status`.
`2`	Authentication, validation, business-rule or provider failure.	Do not treat as verified. Correct the request only when the message indicates a correctable issue.
`3`	Indeterminate/pending internal outcome in an exceptional flow.	Do not retry blindly. Preserve `request_id`/`order_id` and confirm the outcome with Pay2New.

2.3 Important integration rules

Use a new, unique request_id for every chargeable operation. A minimum of 8 characters is recommended across all APIs.
Store the returned order_id and operator_reference. They are required for the DigiLocker status and document calls.
API business failures can be returned in JSON even when the HTTP response is 200. Always evaluate the JSON status.
Latitude and longitude must be decimal values. IPv4 must be supplied in the JSON ip field where requested.
Field names and endpoint paths are case-sensitive. For example, use panDetails, verifyAccount and createUrl exactly as shown.

3. DigiLocker API Suite

The DigiLocker service is a consent-based flow for retrieving verified Aadhaar, PAN or Driving Licence information.

Step	Action
1	Verify account
2	Create consent URL
3	User signs in and grants consent
4	Check status
5	Retrieve the consented document

📘
Supported document values
AADHAAR, PAN, DRIVING_LICENSE. The generated consent URL is time-sensitive and should be opened immediately; its expected validity is 10 minutes.

3.1 Verify DigiLocker Account

Checks whether the supplied mobile number is associated with a DigiLocker account. Use the result to select signin or signup when creating the consent URL.

POST https://pay2new.in/apis/v1/verification/digilocker/verifyAccount

Request fields

Field	Type	Required	Validation / Description
`mobile_number`	string	Yes	Exactly 10 numeric digits.
`latitude`	decimal	Yes	Customer/outlet latitude.
`longitude`	decimal	Yes	Customer/outlet longitude.
`ip`	string	Yes	Valid IPv4 address associated with the transaction/customer.
`request_id`	string	Yes	Client request reference, minimum 8 characters.

cURL example

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/digilocker/verifyAccount' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobile_number": "9999999999",
    "latitude": "19.0760",
    "longitude": "72.8777",
    "ip": "203.0.113.10",
    "request_id": "DLACC202608260001"
  }'

Success response example

{
  "status": 1,
  "message": "Success",
  "operator_reference": 12345678,
  "data": {
    "verification_id": "DLV202608260001",
    "mobile_number": "9999999999",
    "status": "ACCOUNT_EXISTS",
    "digilocker_id": "8aa626bf-34aa-5ffc-a123-f69207e129a7"
  }
}

`data.status`	Meaning	Next `user_flow`
`ACCOUNT_EXISTS`	DigiLocker account exists for the mobile number.	`signin`
`ACCOUNT_NOT_FOUND`	No DigiLocker account was found.	`signup`

3.2 Create DigiLocker Consent URL

Creates the URL where the user logs in or signs up and grants access to the requested documents.

POST https://pay2new.in/apis/v1/verification/digilocker/createUrl

Request fields

Field	Type	Required	Validation / Description
`mobile_number`	string	Yes	Exactly 10 numeric digits.
`document_requested`	array	Yes	One or more of `AADHAAR`, `PAN`, `DRIVING_LICENSE`.
`user_flow`	string	Yes	Exact lowercase value `signin` or `signup`.
`redirect_url`	string	Yes	Client URL to which the user is redirected after the journey. HTTPS is recommended.
`latitude`	decimal	Yes	Customer/outlet latitude.
`longitude`	decimal	Yes	Customer/outlet longitude.
`ip`	string	Yes	Valid IPv4 address.
`request_id`	string	Yes	Unique request reference, minimum 8 characters.

cURL example

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/digilocker/createUrl' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobile_number": "9999999999",
    "document_requested": ["AADHAAR", "PAN"],
    "user_flow": "signin",
    "redirect_url": "https://client.example.com/kyc/digilocker/callback",
    "latitude": "19.0760",
    "longitude": "72.8777",
    "ip": "203.0.113.10",
    "request_id": "DLURL202608260001"
  }'

Success response example

{
  "status": 1,
  "message": "Transaction Success",
  "order_id": "P2NDL202608260001",
  "request_id": "DLURL202608260001",
  "txn_value": "2.00",
  "balance": "998.00",
  "operator_reference": 12345678,
  "url": "https://verification.example/dgl/temporary-token"
}

🚧
Persist both values
Use response order_id and operator_reference in the next two API calls. Redirect the user only to the URL returned by the API. Amounts in this example are illustrative; actual values follow the client package.

3.3 Check DigiLocker Verification Status

Checks whether the user has completed DigiLocker authentication and document consent.

POST https://pay2new.in/apis/v1/verification/digilocker/status

Request fields

Field	Type	Required	Description
`order_id`	string	Yes	`order_id` returned by Create URL.
`operator_reference`	string/integer	Yes	`operator_reference` returned by Create URL.

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/digilocker/status' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "P2NDL202608260001",
    "operator_reference": "12345678"
  }'

Authenticated response example

{
  "status": 1,
  "message": "AUTHENTICATED",
  "operator_reference": 12345678,
  "data": {
    "user_details": {
      "name": "SAMPLE CUSTOMER",
      "dob": "02-02-1995",
      "gender": "M",
      "eaadhaar": "Y",
      "mobile": "9999999999"
    },
    "status": "AUTHENTICATED",
    "document_requested": ["AADHAAR", "PAN"],
    "document_consent": ["AADHAAR", "PAN"],
    "document_consent_validity": "2026-08-26T12:30:00Z",
    "verification_id": "P2NDL202608260001",
    "reference_id": 12345678
  }
}

`data.status`	Meaning	Client action
`PENDING`	User has not completed consent.	Keep the journey open; poll at a reasonable interval.
`AUTHENTICATED`	User authenticated and gave document consent.	Fetch only documents included in `document_consent`.
`EXPIRED`	Consent URL expired before completion.	Create a new URL with a new `request_id`.
`CONSENT_DENIED`	User denied document access.	Stop the fetch flow; request consent again only through an appropriate user journey.

📘
Status handling
Top-level status: 1 means the status lookup itself succeeded. It does not mean the DigiLocker journey is complete. Always evaluate data.status.

3.4 Retrieve DigiLocker Document

Retrieves one consented document after the status is AUTHENTICATED.

POST https://pay2new.in/apis/v1/verification/digilocker/document

Request fields

Field	Type	Required	Description
`order_id`	string	Yes	`order_id` returned by Create URL.
`operator_reference`	string/integer	Yes	`operator_reference` returned by Create URL.
`document_type`	string	Yes	One of `AADHAAR`, `PAN`, `DRIVING_LICENSE`; it must have user consent.

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/digilocker/document' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "P2NDL202608260001",
    "operator_reference": "12345678",
    "document_type": "AADHAAR"
  }'

Aadhaar response example

{
  "status": 1,
  "message": "Aadhaar Card Exists",
  "operator_reference": 12345678,
  "data": {
    "verification_id": "P2NDL202608260001",
    "status": "SUCCESS",
    "uid": "XXXXXXXX5647",
    "care_of": "S/O: SAMPLE PARENT",
    "dob": "02-02-1995",
    "gender": "M",
    "name": "SAMPLE CUSTOMER",
    "photo_link": "BASE64_ENCODED_IMAGE",
    "split_address": {
      "country": "India",
      "dist": "Mumbai",
      "house": "Sample House",
      "landmark": "",
      "pincode": "400001",
      "po": "Mumbai GPO",
      "state": "Maharashtra",
      "street": "Sample Street",
      "subdist": "Mumbai",
      "vtc": "Mumbai"
    },
    "year_of_birth": 1995,
    "xml_file": "https://secure.example/temporary-document-link",
    "message": "Aadhaar Card Exists"
  }
}

📘
Variable document schema
The object inside data changes by document_type. Aadhaar commonly contains masked UID, demographic details, photo and split address; PAN and Driving Licence return fields relevant to those documents. Treat non-mandatory fields as nullable. Any temporary document link should be downloaded/processed within its stated validity period.

4. PAN Verification API

Performs basic PAN validation and returns the registered name and PAN type when available.

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

4.1 Request fields

Field	Type	Required	Validation / Description
`number`	string	Yes	PAN in standard 10-character format: 5 letters, 4 digits, 1 letter. Send uppercase.
`request_id`	string	Yes	Unique client request reference.
`customer_number`	string	Yes	Exactly 10 numeric digits.
`latitude`	decimal	Yes	Customer/outlet latitude.
`longitude`	decimal	Yes	Customer/outlet longitude.
`pincode`	string	Yes	Exactly 6 characters; send a valid Indian PIN code.
`ip`	string	Yes	Valid IPv4 address.
`outletId`	string	Yes	Active Pay2New customer/outlet ID mapped for verification services.
`optional1` to `optional4`	string	No	Reserved for future/configured use. Omit unless instructed by Pay2New.

4.2 cURL example

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/pan' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "ABCDE1234F",
    "request_id": "PANVER202608260001",
    "customer_number": "9999999999",
    "latitude": "19.0760",
    "longitude": "72.8777",
    "pincode": "400001",
    "ip": "203.0.113.10",
    "outletId": "OUTLET12345"
  }'

4.3 Success response

{
  "status": 1,
  "message": "Transaction Successful",
  "data": {
    "pan_number": "ABCDE1234F",
    "registered_name": "SAMPLE CUSTOMER",
    "pan_type": "Individual"
  },
  "order_id": "P2NPAN202608260001"
}

Response field	Description
`status`	Pay2New result: `1` success, `2` failure, `3` indeterminate.
`data.pan_number`	Verified PAN.
`data.registered_name`	Name registered against the PAN.
`data.pan_type`	PAN holder type, such as Individual or Business.
`order_id`	Pay2New transaction identifier. Store it for reconciliation/support.

4.4 Failure response example

{
  "status": 2,
  "message": "PAN is invalid"
}

5. PAN Details Verification API

Performs detailed PAN verification and can return identity attributes, masked contact data, Aadhaar-linking status and address information, subject to upstream availability.

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

5.1 Request fields

The common PAN request fields from Section 4 are required. The following optional field has a specific meaning for this API:

Field	Type	Required	Description
`optional1`	string	No	Customer name as per PAN records. Recommended when available.
`optional2` to `optional4`	string	No	Reserved; omit unless instructed by Pay2New.

5.2 cURL example

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/panDetails' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "ABCDE1234F",
    "request_id": "PANDET202608260001",
    "optional1": "SAMPLE CUSTOMER",
    "customer_number": "9999999999",
    "latitude": "19.0760",
    "longitude": "72.8777",
    "pincode": "400001",
    "ip": "203.0.113.10",
    "outletId": "OUTLET12345"
  }'

5.3 Success response

{
  "status": 1,
  "message": "Transaction Successful",
  "data": {
    "status": "VALID",
    "message": "PAN verified successfully",
    "reference_id": 21637861,
    "verification_id": "P2NPD202608260001",
    "name_provided": "SAMPLE CUSTOMER",
    "pan": "ABCDE1234F",
    "registered_name": "SAMPLE CUSTOMER",
    "name_pan_card": "SAMPLE CUSTOMER",
    "first_name": "SAMPLE",
    "last_name": "CUSTOMER",
    "type": "Individual or Person",
    "gender": "Male",
    "date_of_birth": "27-10-1995",
    "masked_aadhaar_number": "XXXXXXXX8848",
    "email": "s*****@example.com",
    "mobile_number": "99XXXXXX99",
    "aadhaar_linked": true,
    "address": {
      "full_address": "Sample Address, Mumbai, Maharashtra 400001, India",
      "street": "Sample Street",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": 400001,
      "country": "India"
    }
  },
  "order_id": "P2NPD202608260001"
}

📘
Nullable/variable fields
Email, mobile number, address and some demographic fields may be masked, empty or unavailable. The registered_name from the authoritative PAN record may differ from the name printed on a physical PAN card. Build the integration to tolerate absent optional keys.

5.4 Key detailed fields

Field	Description
`data.status`	`VALID` or `INVALID` at the PAN verification layer.
`data.reference_id`	Upstream verification reference.
`data.registered_name`	Name in the PAN database.
`data.name_pan_card`	Name associated with the PAN card record, when available.
`data.type`	PAN holder/entity type.
`data.masked_aadhaar_number`	Masked Aadhaar value, when available.
`data.aadhaar_linked`	Boolean Aadhaar-linking indication, when available.
`data.address`	Address object; all child fields should be treated as optional.

6. GST Verification API

Validates a GSTIN and returns registered business, address, registration and jurisdiction details.

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

6.1 Request fields

Field	Type	Required	Validation / Description
`gst`	string	Yes	GSTIN. Send the standard 15-character value in uppercase.
`latitude`	decimal	Yes	Customer/outlet latitude.
`longitude`	decimal	Yes	Customer/outlet longitude.
`request_id`	string	Yes	Unique request reference, minimum 8 characters.
`ip`	string	Yes	Valid IPv4 address.

6.2 cURL example

curl --request POST \
  --url 'https://pay2new.in/apis/v1/verification/gst' \
  --header 'secret: <YOUR_PAY2NEW_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
    "gst": "27ABCDE1234F1Z5",
    "latitude": "19.0760",
    "longitude": "72.8777",
    "request_id": "GSTVER202608260001",
    "ip": "203.0.113.10"
  }'

6.3 Success response

{
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2NGST202608260001",
  "txn_value": "2.00",
  "balance": "996.00",
  "request_id": "GSTVER202608260001",
  "data": {
    "gstin": "27ABCDE1234F1Z5",
    "legal_Name": "SAMPLE ENTERPRISES PRIVATE LIMITED",
    "trade_Name": "SAMPLE ENTERPRISES",
    "principal_Address": "Sample Building Sample Road Mumbai",
    "state": "Maharashtra",
    "district": "Mumbai",
    "pincode": "400001",
    "date_of_Registration": "01/07/2017",
    "constitution_of_Business": "Private Limited Company",
    "taxpayer_Type": "Regular",
    "gstin_Status": "Active",
    "date_of_Cancellation": null,
    "state_Jurisdiction": "State - Maharashtra",
    "centre_Jurisdiction": "State - Maharashtra"
  }
}

6.4 Response fields

Response field names are case-sensitive; consume them exactly as returned.

Field	Description
`order_id`	Pay2New transaction identifier.
`txn_value`	Verification transaction value/charge as a formatted string.
`balance`	Partner wallet balance after the transaction.
`request_id`	Client request reference echoed back for reconciliation.
`data.legal_Name`	Legal name registered for the GSTIN.
`data.trade_Name`	Registered trade name.
`data.principal_Address`	Principal place of business.
`data.gstin_Status`	GSTIN status such as Active or Cancelled.
`data.date_of_Cancellation`	Currently returned as `null` by this integration.
`data.state_Jurisdiction`	State jurisdiction returned by the verification source.
`data.centre_Jurisdiction`	Centre jurisdiction returned by the verification source.

7. Errors, Security and Go-Live Checklist

7.1 Common error responses

Example message	Likely reason / action
`Secret Header not found!`	Add the `secret` header.
`Authantication Failed!1` / `Authantication Failed!2`	Secret is invalid or cannot be mapped. Confirm credentials with Pay2New.
`IP address not verified!`	The connection source IP is not on the partner whitelist.
`Partner API is not active!`	Partner API access is disabled.
`Partner Wallet is not active!`	Wallet access is disabled.
`Partner KYC not verified!`	Partner KYC is incomplete.
`Invalid Parameters`	One or more request fields failed validation. Inspect the `errors` object.
`Invalid Json!` / `Invalid JSON`	Body is empty or not valid JSON.
`Oops, Invalid OutletId!`	Outlet does not exist, is inactive or is not correctly mapped.
`Service not allowed` / `Oops, This service is not for you!`	The service is not enabled for the partner package/account.
`Your balance is low...`	Insufficient usable wallet balance or wallet lock/charge restriction.
`No Product Found` / `Biller is Down`	Service configuration/provider route is unavailable. Contact Pay2New.

Validation error example

{
  "status": 2,
  "message": "Invalid Parameters",
  "errors": {
    "customer_number": "The customer_number field must be exactly 10 characters in length.",
    "ip": "The ip field must contain a valid IP."
  }
}

7.2 Retry guidance

Situation	Recommended behaviour
Validation or authentication failure	Correct the input/configuration; do not automatically retry the same invalid request.
Top-level `status: 2`	Read `message`. Retry only if the cause is transient and use a new request reference where instructed.
Top-level `status: 3` or network timeout after submission	Treat as unknown. Preserve identifiers and confirm status before initiating another chargeable request.
DigiLocker `data.status: PENDING`	Poll the status endpoint with the same `order_id` and `operator_reference`; use a controlled interval.
DigiLocker `data.status: EXPIRED`	Create a fresh consent URL using a new `request_id`.

7.3 Security and privacy requirements

Call Pay2New APIs only from a secured backend. Never embed the secret in a browser, mobile application or public repository.
Mask PAN, Aadhaar, mobile numbers and other personal data in application logs.
Obtain and record the user’s appropriate consent before initiating DigiLocker or processing identity information.
Store only the data required for the declared business purpose, protect it at rest and in transit, and apply suitable retention/deletion controls.
Do not expose DigiLocker document payloads or temporary links to unauthorised users.

7.4 Go-live checklist

Done	Check
□	Production `secret` received and stored in a secrets manager.
□	All production source IPs shared with Pay2New and whitelisted.
□	Required services and outlet mappings activated.
□	Wallet funded and low-balance monitoring configured.
□	Unique `request_id` generation and identifier storage implemented.
□	Top-level status and DigiLocker nested status handling tested.
□	Timeout/unknown-result flow prevents accidental duplicate transactions.
□	Sensitive-data masking, access control and retention controls reviewed.
□	Success, validation failure, invalid outlet, low balance and IP-whitelist scenarios tested.

Integration support: When reporting an issue, share the endpoint name, timestamp, request_id, order_id (if available), and the response message. Do not share the API secret or unmasked identity data over unsecured channels.

End of document · Pay2New Verification API Integration Guide · Version 1.0

1. Overview and API Summary

General characteristics

2. Authentication and Common Conventions

2.1 Required headers

🚧Source IP requirement

2.2 Common top-level status values

2.3 Important integration rules

3. DigiLocker API Suite

📘Supported document values

3.1 Verify DigiLocker Account

Request fields

cURL example

Success response example

3.2 Create DigiLocker Consent URL

Request fields

cURL example

Success response example

🚧Persist both values

3.3 Check DigiLocker Verification Status

Request fields

Authenticated response example

📘Status handling

3.4 Retrieve DigiLocker Document

Request fields

Aadhaar response example

📘Variable document schema

4. PAN Verification API

4.1 Request fields

4.2 cURL example

4.3 Success response

4.4 Failure response example

5. PAN Details Verification API

5.1 Request fields

5.2 cURL example

5.3 Success response

📘Nullable/variable fields

5.4 Key detailed fields

6. GST Verification API

6.1 Request fields

6.2 cURL example

6.3 Success response

6.4 Response fields

7. Errors, Security and Go-Live Checklist

7.1 Common error responses

Validation error example

7.2 Retry guidance

7.3 Security and privacy requirements

7.4 Go-live checklist

🚧
Source IP requirement

📘
Supported document values

🚧
Persist both values

📘
Status handling

📘
Variable document schema

📘
Nullable/variable fields