HSN To MCC

Endpoint Overview

POST /api/v1/mcc-mapping/hsn-to-mcc

Description

This API endpoint maps Harmonized System Nomenclature (HSN) codes to their corresponding Merchant Category Codes (MCC) with confidence levels and detailed justifications. It helps businesses accurately categorize products or services based on standardized industry classifications, ensuring proper transaction categorization for regulatory compliance, financial reporting, and business analytics.

Key Benefits

Accurate merchant categorization for regulatory compliance and reporting

Simplified tax classification based on standardized industry codes

Improved transaction analytics with consistent merchant categorization

Reduced manual effort in mapping product codes to merchant categories

Use Cases

Financial Services

E-commerce

Compliance

Categorize merchant transactions for expense reporting and analysis

Determine applicable interchange rates based on merchant category

Identify transaction types for fraud detection and risk management

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	JWT Bearer token for authentication (format: `Bearer YOUR_TOKEN`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
hsn	String	Yes	The HSN (Harmonized System Nomenclature) code to be mapped to an MCC

Example Request

{
    "hsn": "0101"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the API request
data.hsn	String	The HSN code that was submitted in the request
data.mcc_code	String	The mapped Merchant Category Code (MCC)
data.confidence	String	Confidence level of the mapping (High/Medium/Low)
data.justification	String	Detailed explanation of why the HSN maps to the given MCC
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": "hsn_to_mcc_COhgTtVTHpfSuWSDtsgK",
        "hsn": "0101",
        "mcc_code": "0742",
        "confidence": "Medium",
        "justification": "This HSN code represents live horses, asses, mules, and hinnies. This falls under agricultural services, specifically livestock. MCC 0742 is designated for Veterinary Services, which is closely related to the care and maintenance of live animals, especially livestock. While not a direct sale of the animals themselves, it's the closest applicable MCC."
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Server Error

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

The JWT token is missing, expired, or invalid.

Integration Best Practices

Security Recommendations

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

Implement token refresh mechanisms to handle token expiration

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

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Cache frequently used HSN-to-MCC mappings to improve response times

Implement retry logic with exponential backoff for transient errors

Display confidence levels to end-users when appropriate for transparency

Provide the justification to users when they need to understand the mapping rationale

Code Samples

cURL

Python

Node.js

Related APIs

MCC to HSN Mapping: Maps Merchant Category Codes to corresponding HSN codes

MCC Validation: Validates if a given MCC code is valid and returns its description

HSN Validation: Validates if a given HSN code is valid and returns its description

Bulk HSN to MCC Mapping: Maps multiple HSN codes to MCCs in a single request

Compliance and Legal Considerations

HSN codes and MCC classifications are standardized systems used for regulatory compliance, taxation, and financial reporting. Ensure that you use the mapped codes appropriately according to your jurisdiction's requirements. The confidence level provided with each mapping should be considered when making business decisions based on these classifications.

{ "data": { "client_id": "hsn_to_mcc_COhgTtVTHpfSuWSDtsgK", "hsn": "0101", "mcc_code": "0742", "confidence": "Medium", "justification": "This HSN code represents live horses, asses, mules, and hinnies. This falls under agricultural services, specifically livestock. MCC 0742 is designated for Veterinary Services, which is closely related to the care and maintenance of live animals, especially livestock. While not a direct sale of the animals themselves, it's the closest applicable MCC." }, "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 ********************

HSN To MCC

HSN To MCC#

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

HSN To MCC

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples