Register Stamp

Endpoint Overview

POST /api/v1/stamper/register-stamp

Description

This endpoint allows you to register a new e-stamp certificate in the system. E-stamps are digital equivalents of physical stamp papers used for legal and financial documents. The API creates a new stamp with the specified denomination and returns a unique identifier along with a secure link to access the stamp certificate.

Key Benefits

Instant creation of legally valid e-stamps without physical paperwork

Secure digital storage with tamper-proof verification

State-specific stamp registration compliant with local regulations

Real-time availability status tracking for registered stamps

Use Cases

Legal Services

Financial Services

Real Estate

Generate e-stamps for legal agreements and contracts

Create stamps for affidavits and legal declarations

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 {your_jwt_token}`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
amount	Integer	Yes	The denomination value of the stamp in INR
state	String	Yes	The Indian state for which the stamp is being registered
client_id	String	No	Optional client identifier for your reference

Example Request

{
  "amount": 500,
  "state": "Maharashtra",
  "client_id": "client_reference_123"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the stamp registration details
data.client_id	String	Unique identifier for the client
data.stamp_id	String	Unique identifier for the registered stamp
data.created_at	String	Timestamp when the stamp was created (ISO 8601 format)
data.amount	Integer	The denomination value of the stamp in INR
data.amount_added	Integer	The amount that was added to create this stamp
data.state	String	The state for which the stamp is registered
data.status	String	Current status of the stamp (e.g., "available")
data.on_hold	Boolean	Indicates if the stamp is currently on hold
data.link	String	Temporary URL to download the stamp certificate (expires in 10 minutes)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "stamp_houVgQfAvaijGNlWOyEi",
        "stamp_id": "stamp_houVgQfAvaijGNlWOyEi",
        "created_at": "2024-04-05T21:39:34.053696",
        "amount": 500,
        "amount_added": 500,
        "state": "Maharashtra",
        "status": "available",
        "on_hold": false,
        "link": "https://surepass-esign.s3.amazonaws.com/vishal.rathore/stamper/stamp_houVgQfAvaijGNlWOyEi/stamp_1712353173955622.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240405%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240405T213934Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=46a8c4477015e3a9f896fb413ebfa8bce208bace20dfec65295ce3941b84e06a"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

Insufficient Balance

{
    "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

Download and securely store the stamp PDF as soon as possible, as the link expires in 10 minutes

Implement proper error handling to manage authentication failures and token expiration

Use HTTPS for all API communications to ensure data encryption in transit

User Experience Guidelines

Provide clear feedback to users about the stamp registration status

Implement a download mechanism that automatically saves the stamp PDF

Display stamp details including denomination, state, and status to users

Include a preview option for the stamp certificate when possible

Code Samples

cURL

Python

Node.js

Related APIs

Get Stamp Details: Retrieve information about a previously registered stamp

Cancel Stamp: Cancel a stamp that is no longer needed

List Stamps: Get a list of all stamps registered by your account

Stamp Usage: Mark a stamp as used in a document

Compliance and Legal Considerations

E-stamps generated through this API are legally valid documents in accordance with the Indian Stamp Act and respective state stamp regulations. The stamps are state-specific and must be used in accordance with the regulations of the state for which they are registered. Improper use of stamps may lead to legal consequences. Ensure compliance with all applicable laws and regulations when using e-stamps for legal and financial documents.

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/register-stamp' \ --header 'Authorization: Bearer <token>' \ --form 'amount="500"' \ --form 'state="Maharashtra"' \ --form 'file=@""'

{ "data": { "client_id": "stamp_houVgQfAvaijGNlWOyEi", "stamp_id": "stamp_houVgQfAvaijGNlWOyEi", "created_at": "2024-04-05T21:39:34.053696", "amount": 500, "amount_added": 500, "state": "Maharashtra", "status": "available", "on_hold": false, "link": "https://surepass-esign.s3.amazonaws.com/vishal.rathore/stamper/stamp_houVgQfAvaijGNlWOyEi/stamp_1712353173955622.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240405%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240405T213934Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=46a8c4477015e3a9f896fb413ebfa8bce208bace20dfec65295ce3941b84e06a" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Register Stamp

Register Stamp#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Register Stamp

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples