Order Estamp

Endpoint Overview

POST /api/v1/stamper-v2/order-stamp

Description

This endpoint allows you to place an order for an electronic stamp paper (Estamp) for legal documents. Estamps are digital versions of traditional stamp papers that provide legal validity to agreements and contracts. This API facilitates the procurement of state-specific Estamps with designated monetary values, enabling seamless integration of stamp duty compliance into your document workflow.

Key Benefits

Instant Procurement: Order Estamps instantly without physical visits to stamp vendors

State-Specific Compliance: Ensure legal compliance with state-specific stamp duty regulations

Digital Integration: Seamlessly incorporate Estamps into your e-signing and document workflows

Real-time Status Tracking: Monitor the status of your Estamp orders through the API

Use Cases

Financial Services

Real Estate

Legal Services

Generate Estamps for loan agreements between lending institutions and borrowers

Create legally compliant promissory notes for financial transactions

Procure Estamps for mortgage documentation and collateral agreements

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 authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
first_party	String	Yes	Name of the first party on the stamp paper
second_party	String	Yes	Name of the second party (use generic terms like "Borrower")
state	String (Enum)	Yes	Two-letter state code where the stamp will be issued
article_id	Integer	Yes	Specific article ID for the stamp type
amount	Integer	Yes	The stamp duty amount in INR
consideration_amount	Integer	Yes	The consideration amount for the agreement
quantity	Integer	Yes	Number of identical stamps to order
description	String	Yes	Brief description of the stamp purpose

State Codes

The state parameter must be one of the following two-letter codes:

AN (Andaman and Nicobar Islands)
AP (Andhra Pradesh)
AR (Arunachal Pradesh)
AS (Assam)
BR (Bihar)
CH (Chandigarh)
CT (Chhattisgarh)
DL (Delhi)
GA (Goa)
GJ (Gujarat)
HR (Haryana)
HP (Himachal Pradesh)
JH (Jharkhand)
JK (Jammu and Kashmir)
KA (Karnataka)
KL (Kerala)
MH (Maharashtra)
ML (Meghalaya)
MN (Manipur)
MP (Madhya Pradesh)
MZ (Mizoram)
OR (Odisha)
PB (Punjab)
PY (Puducherry)
RJ (Rajasthan)
SK (Sikkim)
TG (Telangana)
TN (Tamil Nadu)
TR (Tripura)
UP (Uttar Pradesh)
UT (Uttarakhand)
WB (West Bengal)

 :::warning Sandbox Limitations
        In the sandbox environment, only the following values are supported:
        - **State:** `DL` (Delhi)
        - **Article ID:** `22128`
        :::

        #### Second Party Naming Guidelines
        Always use a generic name for the second party to allow the stamp paper to be reused for other e-sign processes.

        **Acceptable generic names:**
        - "Borrower" ✅
        - "Second Party" ✅
        - "Lessee" ✅

        **Names to avoid:**
        - "Deepak Raj" ❌
        - "Surjal Pvt Ltd" ❌
        - "Mr. John Smith" ❌


        #### Example Request
        ```json
        {
            "first_party": "ABC Pvt Ltd",
            "second_party": "Borrower",
            "state": "DL",
            "article_id": 22128,
            "amount": 40,
            "consideration_amount": 1,
            "description": "Estamp"
        }

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the Estamp order details
data.client_id	String	Unique identifier for the client
data.stamp_id	String	Unique identifier for the stamp
data.created_at	String	Timestamp of order creation (ISO format)
data.amount	Integer	Monetary value of the stamp in INR
data.consideration_amount	Integer	Value of the transaction/agreement
data.first_party	String	Name of the first party
data.second_party	String	Name of the second party
data.state	String	Two-letter state code
data.status	String Enum	Current status of the order
data.on_hold	Boolean	Indicates if the order is on hold
data.link	String or null	Link to access the stamp (if available)
status_code	Integer	HTTP status code
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the message

Status Values

The status field can have the following values:

pending: Order is being processed

available: Estamp is ready for use

on_hold: Order is temporarily on hold

used: Estamp has been utilized

Example Successful Response

{
    "data": {
        "client_id": "stamp_v2_jxXNHjntEoeaMHiiVcUi",
        "stamp_id": "stamp_v2_jxXNHjntEoeaMHiiVcUi",
        "created_at": "2024-12-24T13:55:40.168229",
        "amount": 40,
        "consideration_amount": 1,
        "first_party": "ABC Pvt Ltd",
        "second_party": "Borrower",
        "state": "DL",
        "status": "pending",
        "on_hold": false,
        "link": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

{
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired token",
    "message_code": "unauthorized"
}

This error occurs when the JWT token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption

Implement token refresh mechanisms to handle token expiration gracefully

User Experience Guidelines

Provide clear feedback to users about the Estamp order status

Implement retry logic for failed requests with exponential backoff

Cache frequently used state and article information to improve UI responsiveness

Display appropriate waiting indicators during the order processing period

Code Samples

cURL

Python

Node.js

Related APIs

Get Estamp Details: Retrieve information about an existing Estamp order

Get Estamp Status: Check the current status of an Estamp order

List Available Articles: Get a list of available article IDs for a specific state

Cancel Estamp Order: Cancel a pending Estamp order

Compliance and Legal Considerations

Estamps are governed by state-specific stamp duty regulations in India. The validity and requirements for Estamps vary by state. Ensure that you are using the correct state code and article ID as per the jurisdiction where the document will be executed. The monetary value of the stamp should comply with the stamp duty requirements for the specific document type in the relevant state. Improper use of Estamps may result in legal documents being deemed invalid or inadmissible in court.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/stamper-v2/order-stamp' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_party": "ABC Pvt Ltd", "second_party": "Borrower", "state": "DL", "article_id": 22128, "amount": 40, "consideration_amount": 1, "description": "Estamp" }'

{ "data": { "client_id": "stamp_v2_jxXNHjntEoeaMHiiVcUi", "stamp_id": "stamp_v2_jxXNHjntEoeaMHiiVcUi", "created_at": "2024-12-24T13:55:40.168229", "amount": 40, "consideration_amount": 1, "first_party": "ABC Pvt Ltd", "second_party": "Borrower", "state": "DL", "status": "pending", "on_hold": false, "link": null }, "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 Estamp

Order Estamp#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

State Codes#

Response Parameters#

Status Values#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Order Estamp

Description

Use Cases

Technical Implementation

Request Headers

Request Body

State Codes

Response Parameters

Status Values

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples