REST API

General Response Structure

All API interfaces return a unified response structure as follows:

{
  "code": "integer",
  "msg": "string",
  "data": "object",
  "systemTime": "long (system timestamp)"
}

Response Fields

code: Response status code
- 1: Success
- 0: General error
msg: Response message
data: Response data object
systemTime: Server timestamp in milliseconds

Signature Calculation Method

All requests requiring a signature follow these rules:

Sort all parameters by key name in alphabetical order.
Concatenate parameters in the format "key=value" joined by "&".
Append the secret key to the end of the string.
Compute the SHA-256 hash of the final string.

Example:

Parameters:

{
  "amount": "100.00",
  "nonce": "abc123",
  "timestamp": "1677123456789",
  "uid": "user123"
}

Sort and concatenate:
- "amount=100.00&nonce=abc123&timestamp=1677123456789&uid=user123"
Append the secret key:
- "amount=100.00&nonce=abc123&timestamp=1677123456789&uid=user123YourSecretKey"
Compute SHA-256:
- sign = SHA-256(concatenated_string)

# php version
public function sign($data, $app_secret) {
    ksort($data);
    $str = '';
    // join $data with $key=$value&$key=$value
    foreach ($data as $key => $value) {
        $str .= $key . '=' . $value . '&';
    }
    //remove the last &
    $str = substr($str, 0, -1);
    $str .= $app_secret;
    // sha256
    return hash('sha256', $str);
}

Map<String, Object> params = new TreeMap<>();
params.addAll(allParameters);
String base = MapUtil.join(params, "&", "=", true);
String _sign = DigestUtil.sha256Hex(base + System.getenv("PAYMENT_NOTIFY_SECRET"));

package main

import (
	"crypto/sha256"
	"encoding/hex"
	"sort"
	"strings"
)

func sign(data map[string]string, appSecret string) string {
	keys := make([]string, 0, len(data))
	for key := range data {
		keys = append(keys, key)
	}
	sort.Strings(keys)

	var sb strings.Builder
	for _, key := range keys {
		sb.WriteString(key)
		sb.WriteString("=")
		sb.WriteString(data[key])
		sb.WriteString("&")
	}

	str := sb.String()
	if len(str) > 0 {
		str = str[:len(str)-1]
	}

	str += appSecret

	hash := sha256.Sum256([]byte(str))
	return hex.EncodeToString(hash[:])
}

import hashlib

def sign(data, app_secret):
    sorted_keys = sorted(data.keys())

    str_to_sign = "&".join(f"{key}={data[key]}" for key in sorted_keys)
    str_to_sign += app_secret
    
    sha256_hash = hashlib.sha256(str_to_sign.encode('utf-8')).hexdigest()
    
    return sha256_hash

const crypto = require('crypto');

function sign(data, appSecret) {
    const sortedKeys = Object.keys(data).sort();
    let str = '';

    sortedKeys.forEach((key) => {
        str += `${key}=${data[key]}&`;
    });


    str = str.slice(0, -1);

    str += appSecret;

    return crypto.createHash('sha256').update(str).digest('hex');
}

// example
const data = {
    b: 'value2',
    a: 'value1',
    c: 'value3',
};
const appSecret = 'my_app_secret';

console.log(sign(data, appSecret));

import * as crypto from 'crypto';

function sign(data: Record<string, string | number>, appSecret: string): string {
    const sortedKeys = Object.keys(data).sort();
    let str = '';

    for (const key of sortedKeys) {
        str += `${key}=${data[key]}&`;
    }

    str = str.slice(0, -1);
    str += appSecret;
    return crypto.createHash('sha256').update(str).digest('hex');
}

// 示例用法
const data: Record<string, string | number> = {
    b: 'value2',
    a: 'value1',
    c: 123, // 支持 string 或 number 类型
};

const appSecret = 'my_app_secret';

console.log(sign(data, appSecret));

1. Retrieve Payment Address (Without Payment UI)

• Endpoint: GET /api/v1/address/{id}

• Description: Retrieve the payment address for a specific order.

• Parameters:

• id: Order ID (path variable)

Response:

• Success: Mapping of chain type to wallet address

• Failure: "Not found" (Order not found)

Example:

{
  "code": 1,
  "msg": "success",
  "data": {
    "EVM": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "TRON": "TRWBqiqoFZysoAeyR1J35ibuyc8EvhUAoY"
  },
  "systemTime": 1678234567890
}

2. Create Payment Order

• Endpoint: POST /api/v1/order

• Rate Limit: 60 requests per minute

• Request Body:

{
  "oid": "Merchant Order Number",
  "uid": "User ID",
  "amount": "Amount",
  "memo": "Remark",
  "expiredAt": "Expiration Time",
  "timestamp": "Timestamp",
  "nonce": "Random String",
  "sign": "Signature",
  "mchId": "Merchant ID",
  "notifyUrl": "Callback URL for payment result notifications",
  "redirectUrl": "Redirect URL after payment completion",
  "logo": "Logo URL displayed on the payment page"
}

Validation:

• Timestamp must be within 5 minutes.

• Signature must be valid.

• Nonce must be unique.

Response:

• Success: Payment order details and wallet addresses

• Failure: Error message with details

Example (Success):

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": "202403151234567890",
    "oid": "merchant_order_123",
    "uid": "user123",
    "amount": "100.00",
    "status": "PENDING_PAY",
    "expiredAt": 1678234567890,
    "addresses": {
      "EVM": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "TRON": "TRWBqiqoFZysoAeyR1J35ibuyc8EvhUAoY"
    }
  },
  "systemTime": 1678234567890
}

3. Check Order Status

• Endpoint: GET /api/v1/order/{id}/status

• Description: Retrieve the current status of a payment order.

• Parameters:

• id: Order ID (path variable)

Response:

• Success: Current order status (e.g., Pending Payment, Paid, Expired)

• Failure: "Order not found"

Example:

{
  "code": 1,
  "msg": "success",
  "data": "PAID",
  "systemTime": 1678234567890
}

4. Refund Order

• Endpoint: POST /api/v1/refund

• Request Body:

{
  "id": "Payment System Order ID",
  "oid": "Merchant Order Number",
  "amount": "Refund Amount",
  "remark": "Reason or Remark",
  "timestamp": "Timestamp",
  "nonce": "Random String",
  "sign": "Signature"
}

Validation:

• Either id or oid must be provided.

• Refund amount must be positive and not exceed the original payment.

• Order status must be Paid.

• Signature must be valid.

Response:

Example (Success):

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": "202403151234567890",
    "oid": "merchant_order_123",
    "amount": "50.00",
    "status": "REFUNDED",
    "remark": "Customer requested refund",
    "refundTime": 1678234567890
  },
  "systemTime": 1678234567890
}

Example (Failure):

{
  "code": 0,
  "msg": "Order status is not Paid",
  "data": null,
  "systemTime": 1678234567890
}

Additional APIs (Withdrawal Apply, Confirm, Reject) can be translated if needed. Let me know if you’d like the rest!

PreviousCreate the first order NextReceive Result Notification

Last updated 5 months ago