GSTIN To MCC

Endpoint Overview

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

Description

This API endpoint maps a given GSTIN (Goods and Services Tax Identification Number) to relevant Merchant Category Codes (MCCs) for both goods and services. The mapping provides detailed classification information including confidence levels and justifications based on related HSN (Harmonized System of Nomenclature) codes. This service helps businesses and payment processors accurately categorize merchants based on their registered tax information.

Key Benefits

Automatic categorization of businesses based on their GSTIN

Separate classification for goods and services with confidence levels

Detailed justification for each MCC mapping

HSN code correlation for regulatory compliance

Use Cases

Payment Processing

Financial Services

Regulatory Compliance

Automatically assign appropriate MCC codes to merchants during onboarding

Ensure correct interchange fees based on merchant category

Validate merchant business type against their declared activities

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

Request Body

Parameter	Type	Required	Description
gstin	String	Yes	Valid GST Identification Number of the business to be categorized

Example Request

{
    "gstin": "32ABCPU7961K1YY"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the mapping results
data.client_id	String	Unique identifier for the request
data.gstin	String	The GSTIN that was provided in the request
data.goods	Array	List of goods classifications with MCC codes
data.services	Array	List of services classifications with MCC codes
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

Goods and Services Objects

Parameter	Type	Description
mcc_code	String	Merchant Category Code assigned to the business
justification	String	Explanation of why this MCC was assigned
confidence	String	Confidence level of the mapping (High, Medium, Low)
related_hsn	Array	List of HSN codes related to this classification

Example Successful Response

{
    "data": {
        "client_id": "gstin_to_mcc_kpiYdmkbOngxYStvuixb",
        "gstin": "32ABCPU7961K1YY",
        "goods": [
            {
                "mcc_code": "5311",
                "justification": "Retail business generally falls under department stores if selling a variety of goods. This is a common MCC for general retail.",
                "confidence": "High",
                "related_hsn": [
                    "4202",
                    "4203",
                    "4205"
                ]
            },
            {
                "mcc_code": "5941",
                "justification": "Sporting Goods Stores are common retail outlets. HSN codes related to sporting goods are relevant.",
                "confidence": "Medium",
                "related_hsn": [
                    "9506",
                    "9507"
                ]
            }
        ],
        "services": [
            {
                "mcc_code": "7299",
                "justification": "This MCC covers miscellaneous services not elsewhere classified, which could be relevant for a retail business offering minor services.",
                "confidence": "Low",
                "related_hsn": [
                    "9985",
                    "9986"
                ]
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Service 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, invalid, or expired.

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

Validate and sanitize the GSTIN input before sending to the API

Use HTTPS for all API communications

User Experience Guidelines

Consider confidence levels when using MCC codes for business decisions

Implement caching for frequently accessed GSTINs to improve response times

Display both goods and services classifications to provide complete business context

Use the justification field to explain MCC assignments to end users when needed

Code Samples

cURL

Python

Node.js

Related APIs

GSTIN Verification API: Validates and retrieves basic information about a GSTIN

Business Category API: Provides detailed business categorization based on business description

HSN Code Lookup API: Retrieves detailed information about specific HSN codes

Compliance and Legal Considerations

MCC codes are standardized by card networks and should be used in accordance with their guidelines

HSN codes are part of the GST framework in India and are subject to regulatory requirements

Ensure proper handling of business information in accordance with data protection regulations

The confidence level provided should be considered when making critical business decisions

{ "data": { "client_id": "gstin_to_mcc_kpiYdmkbOngxYStvuixb", "gstin": "32ABCPU7961K1YY", "goods": [ { "mcc_code": "5311", "justification": "Retail business generally falls under department stores if selling a variety of goods. This is a common MCC for general retail.", "confidence": "High", "related_hsn": [ "4202", "4203", "4205" ] }, { "mcc_code": "5941", "justification": "Sporting Goods Stores are common retail outlets. HSN codes related to sporting goods are relevant.", "confidence": "Medium", "related_hsn": [ "9506", "9507" ] } ], "services": [ { "mcc_code": "7299", "justification": "This MCC covers miscellaneous services not elsewhere classified, which could be relevant for a retail business offering minor services.", "confidence": "Low", "related_hsn": [ "9985", "9986" ] } ] }, "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 ********************

GSTIN To MCC

GSTIN To MCC#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Goods and Services Objects#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

GSTIN To MCC

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Goods and Services Objects

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples