Online Retail (Physical Goods)

For merchants classified under the Online Retail (physical goods) vertical in India, a 6 or 8 digit HSN Code (Harmonized System of Nomenclature — a global standard used to classify traded goods) must be included in the items array of every one-time payment request.

This requirement applies to all one-time payment types supported in India, including UPI (QR Code, Intent) and credit/debit cards.

This guide covers the required parameter, validation rules, and sample requests for including HSN codes in your integration.

Note

• Please review the Indian Government's Foreign Trade Policy and do not trade in any restricted goods.
• For the latest information on HSN codes, please refer to the Indian GST Department's website.

---

Parameter

Parameter	Requirement	Description
payment.items[].hsn_code	Mandatory	HSN code for each distinct item in the transaction. Must be a 6 or 8 digit numeric code. Codes with any other number of digits are rejected.

Info

The HSN code parameter applies to both the Direct API (/ws/direct) and the Payment Page (/ws/request) endpoints. For the Payment Page, use items[].hsn_code at the top level of the request body.

---

Points to Consider

DOs	DON'Ts
Only send 6 or 8 digit HSN codes	Don't send 2 or 4 digit HSN codes
Send a distinct HSN code for each category of good in the transaction	Don't send a single HSN code for different categories of goods
Send one HSN code if the category of good is the same and only quantity varies	Don't send HSN codes restricted for trade by the Indian Government
	Don't send blank or empty HSN codes

---

Applicable payment types

HSN codes are required for all one-time payment types available in India:

Payment type	payment_type_code	HSN required
UPI QR Code	upi-qrcode	Yes
UPI Intent	upi-intent	Yes
Credit Card	creditcard	Yes
Debit Card	debitcard	Yes
Payment Page (all methods)	_all	Yes

---

Sample requests

Direct API (/ws/direct)

The following example shows how to include HSN codes in a Direct API credit card payment request for India.

Shell

curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "payment": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "document": "{{tax_id}}",
        "phone_number": "5555555555",
        "address": "123 Main Street",
        "street_number": "100",
        "city": "Capital City",
        "state": "State Name",
        "zipcode": "00000",
        "country": "in",
        "payment_type_code": "creditcard",
        "merchant_payment_code": "{{unique_merchant_code}}",
        "currency_code": "INR",
        "amount_total": 99.85,
        "card": {
            "card_number": "4111111111111111",
            "card_name": "John Doe",
            "card_due_date": "{{MM/YYYY}}",
            "card_cvv": "123"
        },
        "items": [
            {
                "hsn_code": "61091000"
            },
            {
                "hsn_code": "84713000"
            }
        ]
    }
}'

Payment Page (/ws/request)

The following example shows how to include HSN codes in a Payment Page request for India.

Shell

curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/request' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "in",
    "payment_type_code": "_all",
    "merchant_payment_code": "{{unique_merchant_code}}",
    "currency_code": "INR",
    "amount": 1000,
    "items": [
        {
            "hsn_code": "61091000"
        },
        {
            "hsn_code": "84713000"
        }
    ]
}'

Response

No change to the response. It remains as per the standard response format for the respective API endpoint.

---

Error handling

If the HSN code validation fails, the API returns error code BP-DR-191 with a descriptive message. Common error scenarios:

Scenario	Error message
No items array in request	payment items is required
Missing hsn_code in an item	hsn_code is required for each item
Code with a digit count other than 6 or 8	hsn_code must be 6 or 8 digits
Code contains non-numeric characters	hsn_code must contain only digits

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.