Order Status

Endpoint Overview

GET /api/v1/stamper-v2/order-status

Description

This endpoint allows you to retrieve the current status of an e-Stamp order previously created through the system. It provides comprehensive details about the e-Stamp including its current status, certificate information, and a downloadable PDF link when available. This API is essential for tracking the lifecycle of e-Stamps and verifying their validity for legal documentation purposes.

Key Benefits

Real-time status tracking of e-Stamp orders

Access to certificate details and verification information

Direct link to download the e-Stamp PDF when available

Complete visibility into e-Stamp metadata for audit and compliance purposes

Use Cases

Legal Services

Financial Institutions

Real Estate

Track status of e-Stamps for legal agreements and contracts

Verify e-Stamp authenticity before finalizing legal documents

Maintain digital records of stamp duty payments for compliance

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication. Format: `Bearer {JWT_TOKEN}`
Content-Type	Yes	Must be set to `application/json`

Query Parameters

Parameter	Type	Required	Description
client_id	String	Yes	Unique Client ID received in the Order Estamp API response. This identifies the specific e-Stamp order.

Example Request

GET /api/v1/stamper-v2/order-status?client_id=stamp_v2_oeieAotinqqKvkaPXjrM

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the e-Stamp order details
data.client_id	String	Unique Client ID for the e-Stamp order
data.stamp_id	String	Unique Stamp ID for the e-Stamp
data.created_at	Date String	Timestamp when the e-Stamp was created
data.amount	Integer	Total stamp duty amount
data.consideration_amount	Integer	Consideration amount for the stamp duty
data.first_party	String	Name of the first party in the agreement
data.second_party	String	Name of the second party in the agreement
data.article_id	String	Article ID for the e-Stamp
data.state	String	State code where the e-Stamp is valid
data.description	String	Description of the agreement
data.status	String Enum	Current status of the e-Stamp order (pending, available, on_hold, used)
data.on_hold	Boolean	Indicates if the e-Stamp is on hold
data.link	String	Temporary URL to download the e-Stamp PDF (valid for a limited time)
data.certificate_details	Array of Objects	List of e-Stamp certificate details
data.certificate_details[].certificate_number	String	Unique certificate number for the e-Stamp
data.certificate_details[].issue_date	Date String	Issue date of the certificate in YYYY-MM-DD format
data.certificate_details[].denomination	Integer	Denomination value of the individual certificate
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API request was successful
message	String	Response message
message_code	String	Code representing the response message

Status Values

pending: The e-Stamp order is being processed

available: The e-Stamp is ready and available for use

on_hold: The e-Stamp order is currently on hold

used: The e-Stamp has been used and is no longer available

Example Successful Response

{
    "data": {
        "client_id": "stamp_v2_oeieAotinqqKvkaPXjrM",
        "stamp_id": "stamp_v2_oeieAotinqqKvkaPXjrM",
        "created_at": "2025-01-30T10:03:20.281000",
        "amount": 40,
        "consideration_amount": 1,
        "first_party": "ABC Pvt Ltd",
        "second_party": "Borrower",
        "article_id": "22128",
        "state": "DL",
        "description": "Test Agreement",
        "status": "available",
        "on_hold": false,
        "link": "https://bucket.s3.amazonaws.com/stamp_v2_oeieAotinqqKvkaPXjrM/DL_22128_1738231500922351.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5AT7ISOF4%2F20250130%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250130T101337Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=54a0a55971a76cbd74fc5594cf677fb2099adbf09ed7efabe7da0feb31a5ee5e",
        "certificate_details": [
            {
                "certificate_number": "IN DLTHASE401067",
                "issue_date": "2024-12-16",
                "denomination": 20
            },
            {
                "certificate_number": "IN DLTHASE401068",
                "issue_date": "2024-12-16",
                "denomination": 20
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid client_id provided",
    "message_code": "invalid_client_id"
}

This error occurs when the provided client_id is invalid or does not exist in the system.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to manage API failures gracefully

Set up monitoring for API responses to detect any issues with e-Stamp processing

Implement retry logic with exponential backoff for temporary failures

User Experience Guidelines

Poll the status endpoint at reasonable intervals (not more than once per minute) when tracking pending orders

Cache e-Stamp details locally to reduce API calls for frequently accessed information

Download and securely store the e-Stamp PDF when status changes to "available"

Provide clear status indicators to end-users based on the returned status value

Code Samples

cURL

Python

Node.js

Related APIs

Order Estamp API: Create a new e-Stamp order in the system

Cancel Estamp API: Cancel an existing e-Stamp order that is not yet used

Verify Estamp API: Verify the authenticity of an e-Stamp certificate

Compliance and Legal Considerations

E-Stamps are legal documents governed by the Indian Stamp Act and respective state stamp laws. The PDF documents generated through this API are legally valid and should be handled with appropriate security measures. Ensure that you maintain proper records of all e-Stamp transactions for audit and compliance purposes. The validity and acceptance of e-Stamps may vary by state and document type.

{ "data": { "client_id": "stamp_v2_oeieAotinqqKvkaPXjrM", "stamp_id": "stamp_v2_oeieAotinqqKvkaPXjrM", "created_at": "2025-01-30T10:03:20.281000", "amount": 40, "consideration_amount": 1, "first_party": "ABC Pvt Ltd", "second_party": "Borrower", "article_id": "22128", "state": "DL", "description": "Test Agreement", "status": "available", "on_hold": false, "link": "https://bucket.s3.amazonaws.com/stamp_v2_oeieAotinqqKvkaPXjrM/DL_22128_1738231500922351.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5AT7ISOF4%2F20250130%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250130T101337Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=54a0a55971a76cbd74fc5594cf677fb2099adbf09ed7efabe7da0feb31a5ee5e", "certificate_details": [ { "certificate_number": "IN DLTHASE401067", "issue_date": "2024-12-16", "denomination": 20 }, { "certificate_number": "IN DLTHASE401068", "issue_date": "2024-12-16", "denomination": 20 } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Order Status

Order Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Status Values#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Order Status

Description

Use Cases

Technical Implementation

Request Headers

Query Parameters

Example Request

Response Parameters

Status Values

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples