Payment API 2.0 Documentation

Setup

The integrating party must provide the following information to complete the integration setup:

• AES Key: for data encryption/decryption, 128-bit (Base64 encoded).

• RSA Public Key: for request signature verification, 2048-bit (Base64 encoded).

• Static egress IP: to enhance communication security.

• PayIn / PayOut callback URLs: for risk control.

Download the configuration template, fill it in, and send an email:

• To: starplatinum777777777@gmail.com

• CC: vme50tokfconthu@gmail.com

• Subject: Merchant Name - API Config

Use the online tool to generate keys:
Key Generator

Our RSA Public Key (for response signature verification):

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyrTMBsbImv/SC/XDywx4CeU7F0hBbzCvDGME+qrBzbE0KWAI+tTZmLmTGEocUU7galj+cafdVuk+0d6HkpRJcNf7AKF5C4AUEIqJTWnSkGtToutrHkr/6ICLd+SCeKEdfO71t1x2OqEr8lqhCpVf/jT5TOjlyAgCRmPL4JJtBSeZoF7I96KC8VSuk9KURBGK/Fy+BFIdI6Se1h3Efv08ZUU8xv3cUDJr5gOzipIanL5RZ3pzh1TLomEmvYOfcucmeSLkwOggSBhrjeWNsG1aF9AHj9fjpwxrezEd7ibH8KQ22X7uvYSsjWUdHHvFi6i5Lt+p//pazcMJ91FM8R65TQIDAQAB

Overview

All APIs are based on HTTPS. Integrators must call via the POST method.
Request and response bodies are JSON-formatted with UTF-8 encoding.
All requests and responses carry common parameters in their headers — see the Common Parameters section.
All requests and responses are encrypted and signed — see the Encryption and Signature sections.

• A response header x-code of 10000 indicates the request succeeded; check the response body for the business result. For any other value, read the failure reason from x-msg — no response body is returned in this case.
• Always verify x-sign on all responses and callbacks to ensure data integrity.

Common Parameters

Common Request Headers

Name	Description
content-type	Fixed as application/json
x-merchant-id	Integrator's merchantId
x-request-id	Unique request identifier; must be distinct for each request
x-timestamp	Request timestamp
x-version	Version, fixed as 2.0
x-sign	RSA request signature

Common Response Headers

Name	Description
x-merchant-id	Echoed from request header
x-request-id	Echoed from request header
x-timestamp	Response timestamp
x-version	Fixed as 2.0
x-sign	RSA response signature
x-code	Response code
x-msg	Response message

Encryption

To ensure data security, all requests and responses are encrypted.
Both parties use AES/GCM/NoPadding for encryption/decryption, with results encoded in Base64.
Provide a 128-bit AES key (Base64 encoded) in advance — see Setup.

⚠ AES/GCM Implementation Specification
• Algorithm: AES-128-GCM, no padding, 128-bit (16-byte) authentication tag.
• IV: A fresh random 12-byte IV must be generated for every encryption call.
• Encrypted output layout: Prepend the IV to the encrypted output, then Base64-encode the combined bytes for transmission:
Base64( IV[12 bytes] + CipherText + AuthTag[16 bytes] )
• Decryption: After Base64-decoding, extract the first 12 bytes as the IV and pass the remaining bytes (ciphertext + auth tag) to the decryption function.

Request Body Encryption

See each API section for original request body field definitions.

Integrator workflow:

Encrypt the original request body with the AES key
Base64-encode the encrypted result
Send the encoded string as the payload field

Our workflow:

Base64-decode the payload
Decrypt with the AES key
Obtain the original request body

Original request body example:

{
    "key_1": "value_1",
    "key_2": "value_2",
    "key_3": "value_3"
}

Actual request body example:

{
    "payload": "8YryQ8hYkTL3UzzEdvlUGGrL...9lvPN+U0iERGz9wpHtxvA=="
}

Response Body Encryption

See each API section for original response body field definitions.

Our workflow:

AES-encrypt the original response body
Base64-encode the encrypted result
Return the encoded string as payload

Integrator workflow:

Base64-decode the payload
Decrypt with the AES key
Obtain the original response body

Original response body example:

{
    "key_1": "value_1",
    "key_2": "value_2",
    "key_3": "value_3"
}

Actual response body example:

{
    "payload": "8YryQ8hYkTL3UzzEdvlUGGrL...9lvPN+U0iERGz9wpHtxvA=="
}

Signature

To ensure secure API calls, all requests and responses are authenticated via digital signatures.
Both parties use SHA256withRSA to sign the string-to-sign. The Base64-encoded result is placed in the x-sign request or response header.
The full flow involves two RSA key pairs: our key pair T and your key pair U. Public keys verify signatures; private keys generate signatures.
Our RSA public key T is available in the Setup section. You must provide your 2048-bit RSA public key U (Base64 encoded) in advance.

Request String-to-Sign

Concatenate all fields in the following order using | as the separator:

merchantId|version|requestId|timestamp|payload

merchantId: From request header x-merchant-id
version: From request header x-version
requestId: From request header x-request-id
timestamp: From request header x-timestamp
payload: From request body payload field (encrypted ciphertext)

Note: The payload is encrypted only once. Pass the ciphertext directly to the signing method — do not re-encrypt it.

You Sign the string-to-sign with private key U, Base64-encode the result, and set it as the x-sign request header.

Us Base64-decode the x-sign request header, then verify the signature using public key U.

Response String-to-Sign

Concatenate all fields in the following order using | as the separator:

merchantId|version|requestId|timestamp|payload

merchantId: From response header x-merchant-id
version: From response header x-version
requestId: From response header x-request-id
timestamp: From response header x-timestamp
payload: From response body payload field (encrypted ciphertext)

Note: Confirm x-code is 10000 before processing the payload.

Us Sign the string-to-sign with private key T, Base64-encode the result, and set it as the x-sign response header.

You Base64-decode the x-sign response header, then verify the signature using public key T.

PayIn

This module initiates UPI payment collection and returns a payment link for the user to complete.
When processing order queries and callbacks, pay close attention to the statusRefund field — it reflects the risk-control refund status and is independent of tradeStatus. If a user rejects a payment, the system automatically initiates a refund. Whenever statusRefund is true, the funds have been refunded regardless of the trade status. Refunds are subject to a processing window and are not credited instantly.

Create UPI Payment Link

POST /trade/pay_in

Request Parameters

Field	Type	Required	Description
mchId	String	Y	Merchant ID
outTradeNo	String	Y	Merchant order number, must be unique
notifyUrl	String	Y	Async callback URL
payerIp	String	Y	User's real IP, must be dynamically obtained at order time
userId	String	Y	Unique user identifier
successfulTopUpTimes	Integer	Y	User's cumulative successful top-up count
tradeAmount	Decimal(8,2)	Y	Transaction amount
phoneNumber	String	Y	User's phone number
email	String	Y	User's email

Example

{
    "mchId": "20221010100015",
    "notifyUrl": "http://localhost/in/resp",
    "outTradeNo": "9abe9cbfda7348728cb2364e6c4c9b40",
    "payerIp": "127.0.0.1",
    "userId": "10001",
    "successfulTopUpTimes": 0,
    "phoneNumber": "91223211223",
    "email": "sample@gmail.com",
    "tradeAmount": 1
}

Response Fields

Field	Type	Description
mchId	String	Merchant ID
outTradeNo	String	Merchant order No.
tradeId	String	Trade ID
tradeLink	String	Payment page link (use this as the payment URL)

Response Code	Description
1044	Upstream did not return a UPI link
1042	Phone or email is blacklisted, please use a different one
2005	Upstream request error

Example

{
    "code": "10000",
    "currentTime": "1676442883367",
    "data": {
        "code": "10000",
        "mchId": "20221010100015",
        "msg": "The operation succeeded",
        "outTradeNo": "48fd8714bb5e453b9027d2d516a5fe88",
        "tradeId": "2023021510000003",
        "tradeLink": "https://localhost/trade/link?payNo=20250001"
    },
    "msg": "The operation succeeded"
}

Callback

We will send notifications via POST to the callback URL (notifyUrl) provided at order creation. Please verify the signature on all callback requests.
The same notification may be delivered multiple times — implement idempotency handling accordingly.
Respond with a plain-text string (no encryption or signature required):
• Return SUCCESS: Acknowledges receipt and stops further notifications.
• Return WRONG: Indicates an anomaly (e.g., order not found or disputed); we will log and investigate.

Response Fields

Field	Type	Description	Remarks
tradeAmount	Decimal(8,2)	Trade amount
mchId	String	Merchant ID
outTradeNo	String	Merchant order No.
tradeId	String	Trade ID
tradeStatus	String	Trade status	`CREATE` Payment link created `TIMEOUT` Timed out `FAIL` Payment failed `SUCCESS` Payment succeeded
statusRefund	Boolean	Refund status after receiving payment; regardless of tradeStatus, the funds may have been returned directly	true / false
utr	String	UTR
refundMessage	String	Refund reason

Example

{
    "mchId": "20221010100015",
    "nonceStr": "1at0gfk809lukc4tcq7ccn8px0lgs1du",
    "accountAmount": 1,
    "outTradeNo": "48fd8714bb5e453b9027d2d516a5fe88",
    "sign": "27a54fe2cd22dc6183a5c322190564ab",
    "timestamp": 1676443961,
    "tradeAmount": 1,
    "tradeId": "2023021510000003",
    "tradeStatus": "SUCCESS",
    "statusRefund": false,
    "utr": "5500003",
    "refundMessage": ""
}

Query Status

POST /trade/query/in

Request Parameters

Field	Type	Description	Required	Remarks
tradeId	String	Trade ID	Yes (one of two)	tradeId / outTradeNo One of these two is required
outTradeNo	String	Merchant order No.	Yes (one of two)	tradeId / outTradeNo One of these two is required
mchId	String	Merchant ID	Yes

Example

{
    "mchId": "20221010100015",
    "tradeId": "2023021410000003"
}

Response Fields

Field	Type	Description	Remarks
tradeAmount	Decimal(8,2)	Trade amount
outTradeNo	String	Merchant order No.
tradeId	String	Trade ID
tradeStatus	String	Trade status	`CREATE` Link created `TIMEOUT` Timed out `FAIL` Failed `SUCCESS` Succeeded
statusRefund	Boolean	Refund status after receiving user payment	Note: Regardless of tradeStatus, true means funds have been refunded (may be delayed)
utr	String	UTR (upstream transaction ref)
refundMessage	String	Refund reason	Only returned when refund occurs

Example

{
    "code": "10000",
    "currentTime": "1676444797353",
    "data": {
        "code": "10000",
        "createdAt": "2023-02-15 12:04",
        "currency": "INR",
        "mchId": "20221010100015",
        "msg": "The operation succeeded",
        "outTradeNo": "48fd8714bb5e453b9027d2d516a5fe88",
        "tradeAmount": 1,
        "tradeId": "2023021510000003",
        "tradeStatus": "CREATE",
        "statusRefund": false,
        "utr": "5500003",
        "refundMessage": ""
    },
    "msg": "The operation succeeded"
}

PayOut

Currently, tradeMode only supports IMPS.
An order is considered successfully submitted only when both the outer code and the data.code in the response equal 10000; all other cases should be treated as failure.
For successfully submitted orders, update your business status based on the returned tradeStatus:
• PAY_ING: Processing
• PAY: Payment succeeded
• PAY_FAIL: Payment failed

Important: An HTTP 500 or request timeout does not indicate failure. Once a request is sent, keep polling the order status until a definitive result is received before marking the order. If the order remains unresolvable, contact support. We are not liable for losses caused by failure to query order status promptly.

Initiate Payment

POST /trade/pay_out

Request Parameters

Field	Type	Description	Required	Remarks
mchId	String	Merchant ID	Y
outTradeNo	String	Merchant order No.	Y
notifyUrl	String	Callback URL	Y
tradeAmount	Decimal(8,2)	Trade amount	Y
Users (payment account details, only one record supported)
amount	Decimal(8,2)	Payment amount	Y
userId	String	User ID	Y
payerIp	String	User IP	Y	User's IP at order time, must be dynamically obtained
bankAccount	String	Exact name of the beneficiary	Y
bankCardNo	String	UPI address for UPI channel, bank account number for bank channel	Y
bankName	String	Bank name	N
tradeMode	String	Payment method	Y	IMPS / UPI (currently only IMPS)
bankCode	String	IFSC bank code	N	Required only for bank transfer
mobileNumber	String	User's mobile number	Y
email	String	User's email	Y
userKey	Integer	Detail identification	N
payTime	String	Payment time (yyyy-MM-dd HH:mm:ss)	N

Example

{
    "mchId": "20221010100015",
    "notifyUrl": "https://pay.rupetech.net/pay/out/resp",
    "outTradeNo": "529d3845c5f74f3bbc932e96750b87b4",
    "tradeAmount": 105,
    "users": [
        {
            "userId": "10001",
            "payerIp": "0.0.0.0",
            "amount": 105,
            "bankAccount": "CHAGANTI SURENDER REDDY",
            "bankCardNo": "50100562054556",
            "bankCode": "HDFC0001639",
            "bankName": "HDFC",
            "email": "kpuppala02@gmail.com",
            "mobileNumber": "9097634567",
            "tradeMode": "imps",
            "userKey": 1
        }
    ]
}

Response Fields

This only submits to the bank — it does NOT mean payment succeeded

Field	Type	Description	Remarks
outTradeNo	String	Merchant order No.
tradeId	String	Trade ID
tradeStatus	String	Trade status	`PAY_ING` Submitted to bank `PAY` Payment completed `PAY_FAIL` Payment failed
payType	String	Upstream bank

Example

{
    "code": "10000",
    "currentTime": "1676445014225",
    "data": {
        "code": "10000",
        "mchId": "20221010100015",
        "msg": "The operation succeeded",
        "outTradeNo": "377c7115f0064756915b6d3fa35e32ba",
        "tradeId": "2023021510000009",
        "tradeStatus": "TASK"
    },
    "msg": "The operation succeeded"
}

Callback

flowOrderId and reversalTime are only populated when reversal = true.

Callbacks fall into two categories:

Initial callback: Notifies the payment outcome (success or failure); funds have been deducted or refunded at this point.
Reversal callback (reversal = true): The original outcome has been reversed — take the opposite action: if the original was success (deducted), issue a refund; if the original was failure (refunded), re-deduct.

Response Fields

{
    "accountAmount": 509.5,
    "mchId": "20221010100015",
    "outTradeNo": "9f98a38478c54fd4b9741ee03c8f7e7d",
    "payType": "T",
    "tradeAmount": 500,
    "tradeId": "202407101120000675",
    "tradeStatus": "PAY",
    "users": [
        {
            "accountAmount": 509.5,
            "bankAccount": "1",
            "bankCardNo": "116",
            "bankCode": "3",
            "bankName": "1",
            "flowOrderId": 567135485075525,
            "reversal": true,
            "reversalTime": "2024-07-24 11:50:05",
            "status": "PAY",
            "tradeAmount": 500,
            "userKey": 1,
            "payTime": "2025-01-01 00:00:00",
            "utr": "V2pNo0MEA_"
        }
    ]
}

Query Status

POST /trade/query/out

Request Parameters

Field	Type	Description	Required	Remarks
tradeId	String	Trade ID	Yes (one of two)	tradeId / outTradeNo One of these two is required
outTradeNo	String	Merchant order No.	Yes (one of two)	tradeId / outTradeNo One of these two is required
mchId	String	Merchant ID	Yes

Example

{
    "mchId": "20221010100015",
    "tradeId": "2023021410000003"
}

Response Fields

Field	Type	Description
accountAmount	Decimal(8,2)	Actual account deduction
tradeAmount	Decimal(8,2)	Trade amount
payType	String	Upstream bank
details	Object	Payment account details
bankAccount	String	Beneficiary name
bankCardNo	String	Beneficiary account
payTime	String	Payment time (yyyy-MM-dd HH:mm)
tradeMode	String	upi / imps
userKey	Integer	User ID
reversal	Boolean	Whether reversal occurred (true/false)
flowOrderId	Integer	Use flowOrderId to view deduction/reversal records
reversalTime	String	Reversal timestamp (yyyy-MM-dd HH:mm:ss)
accountAmount	Decimal(8,2)	Actual account deduction
tradeAmount	Decimal(8,2)	Trade amount
utr	String	UTR

Example

{
    "code": "10000",
    "currentTime": "1721810396184",
    "data": {
        "accountAmount": 509.50,
        "code": "10000",
        "createdAt": "2024-07-10 13:10",
        "currency": "INR",
        "details": [
            {
                "bankAccount": "1",
                "bankCardNo": "116",
                "bankCode": "3",
                "bankName": "1",
                "flowOrderId": "567135485075525",
                "payTime": "2024-07-10 13:10",
                "rate": 0.00,
                "reversal": true,
                "reversalTime": "2024-07-24 11:50:05",
                "status": "PAY",
                "tradeAmount": 509.50,
                "tradeMode": "imps",
                "userKey": "1",
                "utr": "V2pNo0MEA_"
            }
        ],
        "msg": "The operation succeeded",
        "nonceStr": "kjvnrocwyokv9qgea3vuggg0h5ukn8g2",
        "orderNo": "202407101120000675",
        "outTradeNo": "9f98a38478c54fd4b9741ee03c8f7e7d",
        "payStatus": "PAY",
        "sign": "bf6a7686000d49f57f8fdfd4619d2103",
        "timestamp": 1721810396,
        "tradeAmount": 500.00
    },
    "msg": "The operation succeeded"
}

Account Query

POST /mch/account

Request Parameters

Field	Type	Description	Remarks
accountType	String	Account type	`COLLECTION` Collection `PAYMENT_ACCOUNT` Payment Default: `COLLECTION`
mchId	String	Merchant ID

Example

{
    "mchId": "20221010100015",
    "accountType": "COLLECTION"
}

Response Fields

Field	Type	Description
merchantNo	String	Merchant ID
notTradeAmount	Decimal(10,2)	Non-tradable amount
tradeAmount	Decimal(10,2)	Tradable amount

Example

{
    "code": "10000",
    "currentTime": "1676891873065",
    "data": {
        "code": "10000",
        "merchantNo": "20221010100015",
        "msg": "The operation succeeded",
        "notTradeAmount": 13.26,
        "totalAmount": 2504.19,
        "tradeAmount": 2435.85
    },
    "msg": "The operation succeeded"
}