Introduction

Welcome to the VSPAY Payment Gateway API. This documentation provides a comprehensive guide to integrating our secure payment solutions for deposits (Pay-In) and withdrawals (Pay-Out).

Version: 2.1
Base URL: https://your-domain.com

All requests must be made over HTTPS with Content-Type: application/json.

Authentication

We strictly use Header-Based Authentication using HMAC-MD5 signatures. Every request must be authenticated.

Required Headers

Header	Example Value	Description
`x-merchant-id`	`550e8400-e29b...`	Your unique Merchant UUID.
`x-signature`	`a1b2c3d4e5...`	The MD5 hash of your request body.

Generating the Signature

Formula

Signature = MD5( JSON_String_Body + Merchant_Secret_Key )

Node.js Example

const crypto = require('crypto');

// 1. Prepare Body (Must match exactly what you send)
const body = JSON.stringify({
    orderId: "ORD-123",
    amount: 100
});

// 2. Your Secret Key
const secretKey = "YOUR_MERCHANT_SECRET_KEY";

// 3. Generate MD5 Hash
const signature = crypto.createHash('md5').update(body + secretKey).digest('hex');

// 4. Send Request
// Headers: { 
//   'Content-Type': 'application/json',
//   'x-merchant-id': 'YOUR_UUID',
//   'x-signature': signature 
// }

Create Pay-In Order

Generate a payment link to collect funds from a user.

POST /api/payin/create

Parameter	Type	Description
`orderId`	String Required	Unique Order ID (Max 64 chars).
`orderAmount`	Number Required	Amount to collect (Min 100).
`callbackUrl`	String Required	Your HTTPS URL to receive webhook notifications.
`skipUrl`	String Optional	Redirect URL for the user after payment.
`param`	String Optional	Custom data to return in callback.

Example Request

{
    "orderId": "MC001-998877",
    "orderAmount": 500,
    "callbackUrl": "https://mysite.com/webhook",
    "skipUrl": "https://mysite.com/success"
}

Success Response

{
    "code": 1,
    "msg": "Order created",
    "data": {
        "orderId": "MC001-998877",
        "id": "e0b5...88",
        "orderAmount": 500,
        "paymentUrl": "https://gateway.com/pay/MC001-998877"
    }
}

Query Pay-In Status

Check the real-time status of a deposit.

POST /api/payin/query

Parameter	Type	Description
`orderId`	String Required	Your unique Order ID.

Response

{
    "code": 1,
    "data": {
        "orderId": "MC001-998877",
        "status": "success", // pending, success, failed
        "amount": 500,
        "utr": "123456789012",
        "createdAt": "2025-01-01T12:00:00Z"
    }
}

Submit UTR (Manual Claim)

If a user has paid but the order is pending, submit the UTR for verification.

POST /api/payin/submit-utr

Parameter	Type	Description
`orderId`	String Required	The pending Order ID.
`utr`	String Required	The 12-digit UTR/Reference Number.

Response

{
    "code": 1,
    "msg": "UTR Submitted successfully",
    "data": {
        "orderId": "MC001-998877",
        "status": "processing"
    }
}

Bank Payout

Transfer funds to a bank account via IMPS/NEFT.

POST /api/payout/bank

Parameter	Type	Description
`orderId`	String Required	Unique Transaction ID.
`amount`	Number Required	Amount to withdraw (Min 100).
`account`	String Required	Beneficiary Account Number.
`ifsc`	String Required	Beneficiary IFSC Code.
`personName`	String Required	Account Holder Name.
`code`	String Optional	2FA Code (Required for Dashboard, Optional for API).

USDT Payout

Transfer funds to a crypto wallet (TRC20).

POST /api/payout/usdt

Parameter	Type	Description
`orderId`	String Required	Unique Transaction ID.
`amount`	Number Required	Amount in INR (Min equivalent of 500 USDT).
`walletAddress`	String Required	TRC20 Wallet Address.
`code`	String Optional	2FA Code (Required for Dashboard, Optional for API).

Check Balance

Get your current available balance.

POST /api/balance/query

Body: {} (Empty JSON Object)

Response

{
    "code": 1,
    "msg": "Success",
    "data": {
        "availableAmount": 10050.00,
        "pendingAmount": 0,
        "totalAmount": 10050.00
    }
}

Webhooks (Callbacks)

We send a POST request to your callbackUrl when a transaction reaches a final state.

Notification Structure

{
    "status": 1,                // 1 = Success, 0 = Failed
    "amount": 500,              // Final Amount
    "orderId": "MC001-998877",  // Your Order ID
    "utr": "123456789012",      // Bank UTR
    "sign": "a1b2c3d4..."       // MD5 Signature
}

Verifying Callback Signature

You must verify the signature to ensure the request is from us.

Formula

sign == MD5( JSON_String_Body + Merchant_Secret_Key )

Depending on your server framework, ensure you allow us to send the raw JSON body.