Revenue Stamp Order API

Endpoint Overview

POST /api/v1/revenue-stamp/order-stamp

Description

The Revenue Stamp Order API enables businesses and individuals to programmatically order government-issued revenue stamps for official documentation purposes. This endpoint streamlines the process of requisitioning revenue stamps by allowing users to specify the quantity needed, delivery address, and intended purpose through a simple API call.

Revenue stamps are essential for legal validation of various documents including agreements, contracts, affidavits, and other official paperwork. This API eliminates the need for manual procurement by providing a digital ordering mechanism with real-time order tracking capabilities. Upon successful order placement, the system generates a unique client identifier and processes the request through the appropriate government channels.

The API is designed for high reliability and compliance with regulatory requirements, ensuring that all stamp orders are properly documented and traceable. It serves as a critical component for businesses requiring frequent revenue stamp procurement for their operations.

Key Benefits

Instant Order Processing: Submit revenue stamp orders in real-time without manual intervention or physical visits to stamp vendors

Automated Tracking: Receive unique order identifiers for seamless tracking and audit trail maintenance

Flexible Delivery: Specify custom courier addresses for convenient delivery to any location

Compliance Ready: Built-in validation ensures all orders meet regulatory requirements and documentation standards

Use Cases

Legal & Compliance

Real Estate & Property

Financial Services

Law firms ordering revenue stamps for client contracts, affidavits, and legal agreements requiring government validation

Corporate legal departments managing bulk stamp procurement for merger & acquisition documentation, partnership agreements, and regulatory filings

Notary services requiring regular stamp inventory for document authentication and certification services

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 for API authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
quantity	integer	Yes	Number of revenue stamps to order. Must be a positive integer (minimum: 1)
courier_address	string	Yes	Complete delivery address where the revenue stamps should be delivered. Include street address, city, state, and postal code
purpose	string	Yes	Intended purpose or use case for the revenue stamps (e.g., "Stamp", "Legal Documentation", "Contract Validation")

Example Request

{
    "quantity": 3,
    "courier_address": "abc",
    "purpose": "Stamp"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the order details and processing information
data.client_id	string	Unique identifier for the revenue stamp order, used for tracking and reference
data.quantity	integer	Confirmed number of revenue stamps ordered
data.courier_address	string	Confirmed delivery address for the order
data.purpose	string	Confirmed purpose/use case for the revenue stamps
data.status	string	Current order status. Possible values: `pending`, `processing`, `dispatched`, `delivered`, `cancelled`
status_code	integer	HTTP status code indicating the result of the request
success	boolean	Indicates whether the request was successful (`true`) or failed (`false`)
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "revenue_stamp_ZDrtFNlinzspCelwscnZ",
        "quantity": 3,
        "courier_address": "New Delhi",
        "purpose": "Stamp",
        "status": "pending"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Service Unavailable

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

This error occurs when the JWT Bearer token is missing, invalid, or expired. Verify your authentication credentials and generate a new token if necessary.

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose JWT tokens in client-side code or version control systems. Store tokens securely using environment variables or secure vaults

Token Rotation: Implement regular token refresh mechanisms to minimize security risks from compromised credentials

HTTPS Only: Always use HTTPS endpoints for API communication to ensure data encryption in transit

Rate Limiting: Implement appropriate rate limiting and retry logic with exponential backoff to handle API throttling gracefully

Input Validation: Validate and sanitize all input parameters on the client side before sending requests to prevent injection attacks

User Experience Guidelines

Order Confirmation: Display the client_id prominently to users for tracking and reference purposes

Status Updates: Implement polling or webhook mechanisms to provide real-time order status updates to end users

Address Validation: Validate delivery addresses on the client side to ensure accurate and complete information before order submission

Error Handling: Provide clear, user-friendly error messages that guide users on how to resolve issues without exposing technical details

Order History: Maintain a local record of orders using the client_id for users to track their revenue stamp procurement history

Code Samples

cURL

Python

Node.js

Related APIs

Revenue Stamp Order Status API: Query the current status and delivery details of an existing revenue stamp order using the client_id

Revenue Stamp History API: Retrieve a complete history of all revenue stamp orders placed by your organization

Revenue Stamp Cancellation API: Cancel pending revenue stamp orders before they are processed or dispatched

Bulk Revenue Stamp Order API: Place multiple revenue stamp orders in a single API call for high-volume procurement scenarios

Compliance and Legal Considerations

Revenue stamps are government-regulated instruments subject to specific legal requirements and restrictions. Ensure compliance with the following:

Authorized Use Only: Revenue stamps must be used only for their intended legal purposes as specified during order placement

Record Keeping: Maintain detailed records of all revenue stamp orders for audit and compliance purposes, including order IDs, quantities, and purposes

Jurisdictional Requirements: Verify that revenue stamp usage complies with local, state, and national regulations in your jurisdiction

Non-Transferability: Revenue stamps are typically non-transferable between entities or purposes without proper authorization

Stamp Validity: Ensure awareness of any expiration dates or validity periods associated with revenue stamps in your jurisdiction

Documentation Requirements: Maintain proper documentation linking revenue stamp usage to specific legal documents or transactions for regulatory compliance

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/revenue-stamp/order-stamp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "quantity": 3, "courier_address": "abc", "purpose": "Stamp" }'

{ "data": { "client_id": "revenue_stamp_ZDrtFNlinzspCelwscnZ", "quantity": 3, "courier_address": "New Delhi", "purpose": "Stamp", "status": "pending" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Order Stamp

Revenue Stamp Order API#

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