Order History

Endpoint Overview

GET /api/v1/revenue-stamp/order-history

Description

The Revenue Stamp Order History API enables businesses to retrieve comprehensive historical records of their revenue stamp orders. This endpoint provides detailed information about stamp orders, including order status, quantities, delivery details, and a complete history of all stamps issued under a specific order. The API returns real-time data on stamp inventory status, helping businesses track their available, issued, and pending stamps efficiently.

This endpoint is essential for businesses that need to maintain compliance records, manage stamp inventory, and audit stamp usage across their operations. It provides a single source of truth for all stamp-related transactions associated with a specific client order.

Key Benefits

Complete Order Visibility: Access full order details including quantity, purpose, courier address, and approval status in a single API call

Real-Time Inventory Tracking: Monitor available, issued, and pending stamps to manage inventory efficiently

Comprehensive Audit Trail: Retrieve timestamped records of all stamps issued under an order for compliance and auditing purposes

Simplified Integration: Simple GET request with minimal parameters makes integration straightforward and maintainable

Use Cases

Financial Services

Legal Services

Real Estate

Loan Documentation: Track revenue stamps used for loan agreements, mortgage documents, and other financial instruments

Compliance Auditing: Maintain comprehensive records of stamp usage for regulatory compliance and internal audits

Inventory Management: Monitor stamp inventory levels to ensure adequate supply for high-volume document processing

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`

Query Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Unique identifier for the revenue stamp order (e.g., `revenue_stamp_QXkOOBr`)

Example Request

Note: This is a GET request and does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding all order and history information
data.client_id	string	Unique identifier for the client's stamp order
data.quantity	integer	Total quantity of stamps ordered
data.courier_address	string	Delivery address for the stamp order
data.purpose	string	Business purpose or reason for the stamp order
data.status	string	Current status of the order (e.g., approved, pending, rejected)
data.total_stamps_issued	integer	Total number of stamps that have been issued from this order
data.available_stamps	integer	Number of stamps currently available for use
data.pending_stamps	integer	Number of stamps pending processing or delivery
data.order_history	array	Array of stamp issuance records with detailed timestamps
data.order_history[].stamp_id	string	Unique identifier for each issued stamp
data.order_history[].created_at	string	ISO 8601 timestamp of when the stamp was issued
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the request was successful
message	string	Human-readable message describing the response
message_code	string	Machine-readable code for the response status

Example Successful Response

{
    "data": {
        "client_id": "revenue_stamp_QXkOOBrPbr",
        "quantity": 100,
        "courier_address": "abc",
        "purpose": "Stamp Testing",
        "status": "approved",
        "total_stamps_issued": 11,
        "available_stamps": 19,
        "pending_stamps": 70,
        "order_history": [
            {
              "stamp_id":"revenue_stamp_reciev",
              "created_at": "2025-11-21T09:56:49.319000"
            },
            {
              "stamp_id":"revenue_stamp_reciev",
              "created_at": "2025-11-21T09:56:50.370000"
            },
            {
                "stamp_id": "revenue_stamp_recieved_jzyQcvvsvzegYxFnDxfb",
                "created_at": "2025-11-21T09:56:50.977000"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Client ID

Missing Parameters

Server Error

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

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

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely using environment variables or secure credential management systems, never hardcode tokens in your application code

HTTPS Only: Always use HTTPS endpoints to ensure data encryption in transit and protect sensitive stamp order information

Token Rotation: Implement automatic token refresh mechanisms to handle token expiration gracefully

Rate Limiting: Implement exponential backoff retry logic to handle rate limiting and maintain system stability

Access Control: Restrict API access to authorized personnel only and implement role-based access control in your application

User Experience Guidelines

Caching Strategy: Cache order history responses appropriately to reduce API calls and improve response times for frequently accessed orders

Progressive Loading: For orders with extensive history, implement pagination or lazy loading to display initial results quickly

Real-Time Updates: Consider implementing webhook notifications for order status changes rather than polling this endpoint repeatedly

Error Handling: Display user-friendly error messages and provide clear next steps when API calls fail

Data Visualization: Present stamp inventory data (available, issued, pending) using charts or visual indicators for better user comprehension

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Record Retention: Maintain order history records as required by local tax and revenue regulations, typically ranging from 3 to 7 years

Audit Trail: The order_history array provides a complete audit trail with timestamps for compliance verification

Data Privacy: Ensure that client_id and order details are handled in accordance with data protection regulations (GDPR, PDPA, etc.)

Stamp Validity: Verify that the usage of revenue stamps complies with local jurisdiction requirements and stamp denominations

Document Authenticity: Use this API as part of your document verification process to ensure proper stamp allocation and usage

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "revenue_stamp_QXkOOBrPbr", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "approved", "total_stamps_issued": 11, "available_stamps": 19, "pending_stamps": 70, "order_history": [ { "stamp_id": "revenue_stamp_recieved_wa", "created_at": "2025-11-21T09:56:49.319000" }, { "stamp_id": "revenue_stamp_recieved_glh", "created_at": "2025-11-21T09:56:50.370000" }, { "stamp_id": "revenue_stamp_recieved_jz", "created_at": "2025-11-21T09:56:50.977000" }, { "stamp_id": "revenue_stamp_recieved_Ka", "created_at": "2025-11-21T09:56:59.126000" }, { "stamp_id": "revenue_stamp_recieved_Fn", "created_at": "2025-11-21T09:57:13.122000" }, { "stamp_id": "revenue_stamp_recieved_pY", "created_at": "2025-11-21T09:57:24.519000" }, { "stamp_id": "revenue_stamp_recieved_KvM", "created_at": "2025-11-21T09:57:24.866000" }, { "stamp_id": "revenue_stamp_recieved_iJ", "created_at": "2025-11-21T09:57:25.219000" }, { "stamp_id": "revenue_stamp_recieved_kx", "created_at": "2025-11-21T09:57:25.605000" }, { "stamp_id": "revenue_stamp_recieved_fkh", "created_at": "2025-11-21T09:57:25.937000" }, { "stamp_id": "revenue_stamp_recieved_hf", "created_at": "2025-11-21T09:57:26.325000" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses