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.app

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

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")
article_id	Integer	Yes	Specific article ID for the stamp type
first_party_address	String	No	Address of the first party
courier_address	String	No	Address where the stamp should be couriered
first_party_father_name	String	No	Father's name of the first party
amount	Integer	Yes	The stamp duty amount in INR
consideration_amount	Integer	Yes	The consideration amount for the agreement
state	String	Yes	Two-letter state code where the stamp will be issued
description	String	No	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)

Sandbox Limitations

In the sandbox environment, only the following combination is 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:

"Rohit Sharma" ❌

"Surjal Pvt Ltd" ❌

"Mr. John Smith" ❌

Example Request

{
    "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
client_id	String	Unique identifier for the client
stamp_id	String	Unique identifier for the stamp
created_at	DateTime	Timestamp
amount	Integer	Monetary value of the stamp in INR
consideration_amount	Integer	Value of the transaction/agreement
first_party	String	First party name
second_party	String	Second party name
first_party_father_name	String	First party name
first_party_address	String	First party address
courier_address	String	Courier address of the stamp
article_id	String	Article ID
state	String	Two-letter state code
description	String	Stamp description
status	Enum	Current status of the order
on_hold	Boolean	Indicates if the order is on hold
link	String (URL)	Link to access the stamp (if available)
certificate_details	List	Certificate details

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",
    "first_party_father_name": null,
    "first_party_address": null,
    "courier_address": null,
    "article_id": null,
    "state": "DL",
    "description": null,
    "status": "pending",
    "on_hold": false,
    "link": null,
    "certificate_details": []
  },
  "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.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/stamper-v2/order-stamp' \ --header 'Authorization: Bearer <token>' \ --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" }

Order Estamp

Order Estamp#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

State Codes#

Sandbox Limitations#

Second Party Naming Guidelines#

Example Request#

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

Sandbox Limitations

Second Party Naming Guidelines

Example Request

Response Parameters

Status Values

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples