API Documentation - Payment Gateway

Authentication

Most API endpoints require authentication using appid and clientip parameters. These credentials are provided when you create a user account.

Note: Your appid can be found in your account settings after logging in. The clientip is your client IP address. Keep these credentials secure and never expose them in client-side code.

Signature Verification

All API requests that create or modify data require signature verification to ensure data integrity and prevent tampering.

How Signature Works

The signature is calculated using all request parameters (except sign and sign_type) and your API key (stored securely on the server).

Signature Algorithm:

Collect all parameters except sign and sign_type
Sort parameters alphabetically by key
Join parameters as key=value pairs with &
Append your API key to the string
Calculate MD5 hash (lowercase) of the resulting string

Signature Parameters

Parameter	Type	Required	Description
`sign`	string	Required	MD5 signature of all parameters (calculated using your API key)
`sign_type`	string	Optional	Signature type, currently only `MD5` is supported (default: `MD5`)

Important: The signature must match exactly. If the signature verification fails, the request will be rejected with a 400 error.

Code Examples

Here are code examples for calculating signatures in different programming languages:

    import hashlib

    apikey = '42ba8e8f-7cbb-4bf9-ba2a-57904f3d9451'

    def md5_lower(text):
        md5 = hashlib.md5()
        md5.update(text.encode('utf-8'))
        return md5.hexdigest()

    def sign_str(data):
        print(f'start MD5 ,param data:{data}')
        exclude_keys = {'sign', 'sign_type'}
        filtered_data = {k: v for k, v in data.items() if k not in exclude_keys and v is not None}
        sorted_data = dict(sorted(filtered_data.items()))
        result = '&'.join([f"{k}={v}" for k, v in sorted_data.items()])
        print(f'start MD5 ,param result:{result}')
        new_sign = md5_lower(f'{result}{apikey}')
        print(f'create new sign:{new_sign}')
        return new_sign

    if __name__ == '__main__':
        data = {
            "data": {
                "pid": "1019",
                "type": "alipay",
                "out_trade_no": "ba799866dc2a4e089ca229a7b8fa471a",
                "notify_url": "https://pay.test.io/api/test_notify_url/",
                "money": 257.4,
                "clientip": "45.32.63.36",
                "name": "345345345345test",
                "param": "33"
            }
        }
        print(sign_str(data))
        #148518e0144b7c82ee336467c7560251

                    

    const crypto = require("crypto");

    function toPythonDict(obj) {
        const parts = [];
        for (const key of Object.keys(obj)) {
            const val = obj[key];
            let v;
            if (typeof val === "string") v = `'${val}'`;
            else if (typeof val === "number") v = val;
            else v = `'${String(val)}'`; // Simplified version
            parts.push(`'${key}': ${v}`);
        }
        return `{${parts.join(", ")}}`;
    }

    function md5_lower(str) {
        return crypto.createHash("md5").update(str).digest("hex").toLowerCase();
    }

    function signStr(data, apikey = undefined) {
        const KEY = apikey;
        const filtered = {};
        for (const k in data) {
            if (k === "sign" || k === "sign_type") continue;
            if (data[k] === null || data[k] === undefined) continue;
            filtered[k] = data[k];
        }
        const sortedKeys = Object.keys(filtered).sort();
        const pairs = sortedKeys.map(key => {
            const value = filtered[key];
            if (typeof value === "object") {
                return `${key}=${toPythonDict(value)}`;
            }
            return `${key}=${value}`;
        });

        const str = pairs.join("&");
        console.log("String used for signing:", str);

        const sign = md5_lower(str + KEY);
        return sign;
    }

    let apikey = '42ba8e8f-7cbb-4bf9-ba2a-57904f3d9451';
    let data = {
        "data": {
            "pid": "1019",
            "type": "alipay",
            "out_trade_no": "ba799866dc2a4e089ca229a7b8fa471a",
            "notify_url": "https://pay.test.io/api/test_notify_url/",
            "money": 257.4,
            "clientip": "45.32.63.36",
            "name": "345345345345test",
            "param": "33"
        }
    };

    let sign_temp = signStr(data, apikey);
    console.log(sign_temp);
    //148518e0144b7c82ee336467c7560251

                    

Create Order

Create a new payment order and receive a QR code for payment.

POST /api/createorder Requires Auth

Request Parameters

Parameter	Type	Required	Description
`appid`	string	Required	Your application ID
`clientip`	string	Required	Your client IP address
`action`	string	Required	Must be `createorder`
`amount`	number	Required	Order amount (e.g., 100.00)
`currency`	string	Required	Currency code: `CNY` or `USD`
`paymentMethod`	string	Required	Payment method (see Payment Methods section)
`sign`	string	Required	MD5 signature (see Signature section)
`sign_type`	string	Optional	Signature type (default: `MD5`)
`description`	string	Optional	Order description
`customerName`	string	Optional	Customer name
`customerEmail`	string	Optional	Customer email
`customerPhone`	string	Optional	Customer phone number
`return_url`	string	Optional	Return URL after payment completion (will redirect automatically if provided). You can use `{paymentId}` placeholder in the URL, which will be automatically replaced with the actual payment ID when redirecting. Example: `https://example.com/success?paymentId={paymentId}`
`notify_url`	string	Optional	Callback notification URL for order status updates. If provided, this URL will be saved to the order and used for callback notifications. If not provided, the system will use the user's configured `callbackUrl`. Important: Only orders with a `notify_url` will receive callback notifications.
`clientOrderId`	string	Optional	Client's own order identifier. This will be saved to the database and returned in the response for your reference.

Important Notes:

IP Address Verification: The clientip parameter must match the actual request IP address, otherwise the request will be rejected (403 error).
Signature Verification: All requests must include a valid MD5 signature. Signature calculation errors will cause the request to fail (400 error).
Return URL Placeholder: You can use {paymentId} placeholder in return_url. The system will automatically replace it with the actual payment ID when redirecting after payment completion.
Callback URL Priority: If notify_url is provided, it will be saved to the order and used for callbacks. If not provided, the system will use the user's configured callbackUrl. Only orders with a notify_url will receive callback notifications.

Request Example

Success Response

Error Response

Signature Verification: This endpoint requires signature verification. The signature must be calculated using all parameters (except sign and sign_type) and your API key. See the Signature section for details.

GET /api/createorder Requires Auth

Create a new payment order and receive an HTML payment page. The page will automatically poll the order status every 4 seconds, timeout after 3 minutes, and automatically redirect to return_url when payment is completed.

Request Parameters

Note: All parameters are passed as query parameters (URL parameters). Parameters are the same as POST request above.

Parameter	Type	Required	Description
`appid`	string	Required	Your application ID
`clientip`	string	Required	Your client IP address
`action`	string	Required	Must be `createorder`
`amount`	number	Required	Order amount (e.g., 100.00)
`currency`	string	Required	Currency code: `CNY` or `USD`
`paymentMethod`	string	Required	Payment method (see Payment Methods section)
`sign`	string	Required	MD5 signature (see Signature section)
`sign_type`	string	Optional	Signature type (default: `MD5`)
`description`	string	Optional	Order description
`customerName`	string	Optional	Customer name
`customerEmail`	string	Optional	Customer email
`customerPhone`	string	Optional	Customer phone number
`return_url`	string	Optional	Return URL after payment completion (page will automatically redirect after 1 second if payment succeeds). You can use `{paymentId}` placeholder in the URL, which will be automatically replaced with the actual payment ID when redirecting. Example: `https://example.com/success?paymentId={paymentId}`
`notify_url`	string	Optional	Callback notification URL for order status updates. If provided, this URL will be used for callback notifications. If not provided, the system will use the user's configured `callbackUrl`. The callback will only be sent to orders that have a `notify_url`.
`clientOrderId`	string	Optional	Client's own order identifier. This will be saved to the database and returned in the response for your reference.

Request Example

GET /api/createorder?appid=YOUR_APPID&clientip=127.0.0.1&action=createorder&amount=100¤cy=CNY&paymentMethod=alipay&description=Test+order&clientOrderId=YOUR_ORDER_ID_123&return_url=https%3A%2F%2Fexample.com%2Fsuccess%3FpaymentId%3D%7BpaymentId%7D¬ify_url=https://example.com/api/notify&sign=CALCULATED_SIGNATURE&sign_type=MD5
                    

Important Notes:

IP Address Verification: The clientip parameter must match the actual request IP address, otherwise the request will be rejected (403 error).
Signature Verification: All requests must include a valid MD5 signature. Signature calculation errors will cause the request to fail (400 error).
Return URL Placeholder: You can use {paymentId} placeholder in return_url. The system will automatically replace it with the actual payment ID when redirecting after payment completion.
Callback URL Priority: If notify_url is provided, it will be saved to the order and used for callbacks. If not provided, the system will use the user's configured callbackUrl. Only orders with a notify_url will receive callback notifications.

Response

Returns an HTML payment page that includes:

Order information display
QR code for payment (if order is ready)
Automatic status polling (every 4 seconds)
3-minute countdown timer
Automatic redirect to return_url when payment is completed

Page Features:

Automatically polls order status every 4 seconds
Shows a 3-minute countdown timer
Automatically redirects to return_url when payment is completed (after 1 second delay)
Handles timeout after 3 minutes
Displays QR code for payment scanning

Signature Verification: This endpoint requires signature verification. The signature must be calculated using all parameters (except sign and sign_type) and your API key. See the Signature section for details.

Query Order

Query single order details or list multiple orders.

GET /api/order Requires Auth

Request Parameters

Parameter	Type	Required	Description
`appid`	string	Required	Your application ID
`key`	string	Required	Your key (UUID format, for query operations)
`action`	string	Required	`order` (single) or `orders` (list)
`paymentId`	string	Required if action=order	Payment ID to query
`page`	number	Optional	Page number (default: 1, only for action=orders)
`limit`	number	Optional	Items per page (max: 50, default: 10, only for action=orders)

Single Order Response

Order List Response

Callback Notification

When an order status changes to paid, the system will automatically send a callback notification to your specified URL.

Callback URL Configuration:

You can specify a callback URL using the notify_url parameter when creating an order
If notify_url is not provided, the system will use your account's default callbackUrl (configured in Settings)
Important: Only orders with a notify_url will receive callback notifications

Callback Request

The system sends a POST request to your callback URL with the following parameters:

Parameter	Type	Description
`paymentId`	string	Unique payment identifier
`amount`	string	Order amount (as string, e.g., "2.2")
`currency`	string	Currency code: `CNY` or `USD`
`status`	string	Order status code: `"2"` (paid)
`status_str`	string	Order status string: `"paid"`
`paymentMethod`	string	Payment method used: `alipay`, `wxpay`, `usdt`, or `payeer`
`description`	string	Order description (if provided)
`completedTime`	string	Payment completion time in ISO 8601 format (e.g., "2025-12-01T02:32:05.877Z")
`createdAt`	string	Order creation time in ISO 8601 format (e.g., "2025-12-01T02:31:43.997Z")
`clientOrderId`	string	Client order ID (if provided when creating the order)
`sign`	string	MD5 signature for verifying the callback authenticity
`sign_type`	string	Signature type: `MD5`

Callback Example

Signature Verification

You must verify the callback signature to ensure the request is authentic. The signature is calculated using the same algorithm as API requests:

Collect all parameters except sign and sign_type
Sort parameters alphabetically by key
Join parameters as key=value pairs with &
Append your API key to the string
Calculate MD5 hash (lowercase) of the resulting string
Compare the calculated signature with the sign parameter

Security: Always verify the callback signature before processing the payment. Do not trust callbacks without valid signatures.

Callback Response

Your callback endpoint must return a specific response to acknowledge successful receipt:

Success: Return HTTP 200 status code with response body containing the string "success" (case-insensitive). The response body must be exactly "success" (e.g., "success", "SUCCESS", or "Success"). Any other response will be considered a failure and trigger retry.
Failure: Return any non-200 status code, or return HTTP 200 with a response body that is not "success" (case-insensitive) will trigger retry

Important: The callback is only considered successful when:

HTTP status code is 200
Response body (trimmed and case-insensitive) equals "success"

Examples of successful responses:

"success" ✓
"SUCCESS" ✓
"Success" ✓

Examples of failed responses (will trigger retry):

{"code": 1, "message": "success"} ✗ (not the string "success")
"ok" ✗ (not "success")
"received" ✗ (not "success")
HTTP 500 or any non-200 status code ✗

Retry Mechanism

The system implements an automatic retry mechanism for failed callbacks:

Maximum attempts: 20 retries
Retry intervals: Exponential backoff (increasing delays between retries)
Retry conditions: Callbacks are retried if:
- Your server returns a non-200 status code
- Your server returns HTTP 200 but the response body is not "success" (case-insensitive)
- The request fails (network error, timeout, etc.)
Success: Once your server returns HTTP 200 with response body "success" (case-insensitive), no further callbacks will be sent for that order

Best Practices:

Implement idempotency: Check if the order has already been processed before processing again
Verify the signature before processing
Return HTTP 200 with response body "success" immediately after receiving and validating the callback, then process the order asynchronously if needed
Log all callback requests for debugging and auditing
Use HTTPS for callback URLs to ensure secure transmission
Important: Ensure your callback endpoint returns exactly the string "success" (case-insensitive) for successful processing

Order Status Codes

Orders have the following status values:

Code	String	Description
`0`	`pending`	Order created, saved locally
`1`	`ready`	Order sent to payment provider, QR code generated
`2`	`paid`	Payment completed successfully
`3`	`failed`	Payment failed
`4`	`cancelled`	Order cancelled

Payment Methods

Supported payment methods and their currency compatibility:

Method	Code	Supported Currencies	Description
Alipay	`alipay`	CNY, USD	Alipay mobile payment
WeChat Pay	`wxpay`	CNY, USD	WeChat mobile payment
USDT	`usdt`	USD	USDT cryptocurrency payment
PAYEER	`payeer`	USD	PAYEER payment system

Currency and Payment Method Compatibility:

CNY (Chinese Yuan): Supports alipay and wxpay only
USD (US Dollar): Supports alipay, wxpay, usdt, and payeer

Exchange Rate Conversion: When using USD with Alipay or WeChat Pay, the system automatically converts the amount to CNY using the configured exchange rate (default: 7.2). The converted amount is used for payment processing.

Payment Method Control: Super administrators can enable or disable payment methods in Advanced Settings. Disabled payment methods will not be available for order creation.

Error Codes

Common error codes and their meanings:

Code	Description
400	Bad Request - Invalid parameters or business logic error
401	Unauthorized - Invalid appid or apikey
403	Forbidden - User account is disabled
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error