商户 API 对接文档

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;

public class PaySign {

    public static String createSign(Map<String, String> params, String key) {
        TreeMap<String, String> sorted = new TreeMap<>();
        for (Map.Entry<String, String> e : params.entrySet()) {
            if (!"pay_sign".equals(e.getKey()) && !"sign".equals(e.getKey())
                && e.getValue() != null && !e.getValue().isEmpty()) {
                sorted.put(e.getKey(), e.getValue());
            }
        }

        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> e : sorted.entrySet()) {
            if (sb.length() > 0) sb.append("&");
            sb.append(e.getKey()).append("=").append(e.getValue());
        }

        return hmacSha256(sb.toString(), key).toUpperCase();
    }

    private static String hmacSha256(String data, String key) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256"));
            byte[] bytes = mac.doFinal(data.getBytes("UTF-8"));
            StringBuilder sb = new StringBuilder();
            for (byte b : bytes) sb.append(String.format("%02x", b));
            return sb.toString();
        } catch (Exception e) { throw new RuntimeException(e); }
    }

    public static void main(String[] args) {
        Map<String, String> params = new HashMap<>();
        params.put("pay_memberid",    "100001");
        params.put("pay_orderid",     "20260404143000001");
        params.put("pay_applydate",   "2026-04-04 14:30:00");
        params.put("pay_notifyurl",   "https://merchant.com/notify");
        params.put("pay_callbackurl", "https://merchant.com/callback");
        params.put("pay_amount",      "500.00");

        params.put("pay_sign", createSign(params, "your_secret_key"));
    }
}

import hashlib, hmac, requests

def create_sign(params: dict, key: str) -> str:
    filtered = {k: v for k, v in params.items()
                if k not in ('pay_sign', 'sign') and v}
    sorted_keys = sorted(filtered.keys())
    string_a = '&'.join(f'{k}={filtered[k]}' for k in sorted_keys)

    return hmac.new(key.encode(), string_a.encode(), hashlib.sha256).hexdigest().upper()

params = {
    'pay_memberid':    '100001',
    'pay_orderid':     '20260404143000001',
    'pay_applydate':   '2026-04-04 14:30:00',
    'pay_notifyurl':   'https://merchant.com/notify',
    'pay_callbackurl': 'https://merchant.com/callback',
    'pay_amount':      '500.00',
}

params['pay_sign'] = create_sign(params, 'your_secret_key')
resp = requests.post('%%BASE_URL%%/api/v1/gateway/pay', data=params)
print(resp.json())

const crypto = require('crypto');
const axios = require('axios');

function createSign(params, key) {
    const filtered = Object.entries(params)
        .filter(([k, v]) => !['pay_sign', 'sign'].includes(k) && v !== '')
        .sort(([a], [b]) => a.localeCompare(b));

    const stringA = filtered.map(([k, v]) => `${k}=${v}`).join('&');

    return crypto.createHmac('sha256', key)
        .update(stringA, 'utf8').digest('hex').toUpperCase();
}

const params = {
    pay_memberid:    '100001',
    pay_orderid:     '20260404143000001',
    pay_applydate:   '2026-04-04 14:30:00',
    pay_notifyurl:   'https://merchant.com/notify',
    pay_callbackurl: 'https://merchant.com/callback',
    pay_amount:      '500.00',
};

params.pay_sign = createSign(params, 'your_secret_key');

axios.post('%%BASE_URL%%/api/v1/gateway/pay', new URLSearchParams(params))
    .then(res => console.log(res.data));

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"net/http"
	"net/url"
	"sort"
	"strings"
)

// CreateSign 生成签名
func CreateSign(params map[string]string, key string) string {
	// 1. 过滤空值和签名字段，按 key 排序
	keys := make([]string, 0)
	for k, v := range params {
		if k == "pay_sign" || k == "sign" || v == "" {
			continue
		}
		keys = append(keys, k)
	}
	sort.Strings(keys)

	// 2. 拼接参数
	pairs := make([]string, 0, len(keys))
	for _, k := range keys {
		pairs = append(pairs, k+"="+params[k])
	}
	stringA := strings.Join(pairs, "&")

	// 3. 计算签名
	mac := hmac.New(sha256.New, []byte(key))
	mac.Write([]byte(stringA))
	return strings.ToUpper(hex.EncodeToString(mac.Sum(nil)))
}

func main() {
	params := map[string]string{
		"pay_memberid":    "100001",
		"pay_orderid":     "20260404143000001",
		"pay_applydate":   "2026-04-04 14:30:00",
		"pay_notifyurl":   "https://merchant.com/notify",
		"pay_callbackurl": "https://merchant.com/callback",
		"pay_amount":      "500.00",
	}

	secretKey := "your_secret_key"
	params["pay_sign"] = CreateSign(params, secretKey)

	// 发送请求
	form := url.Values{}
	for k, v := range params {
		form.Set(k, v)
	}

	resp, err := http.PostForm("%%BASE_URL%%/api/v1/gateway/pay", form)
	if err != nil {
		fmt.Println("请求失败:", err)
		return
	}
	defer resp.Body.Close()

	buf := make([]byte, 4096)
	n, _ := resp.Body.Read(buf)
	fmt.Println("响应:", string(buf[:n]))
}

// 生产环境用 Redis 存储已处理的 nonce，TTL 24小时
const processedNonces = new Set();

app.post('/notify', async (req, res) => {
    const { sign, ...signParams } = req.body;

    // 1. 防重放：校验时间戳
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(signParams.timestamp)) > 300) {
        return res.send('FAIL');  // 超过5分钟，可能是重放
    }

    // 2. 防重复：校验 nonce
    if (processedNonces.has(signParams.nonce)) {
        return res.send('OK');   // 已处理过，直接返回OK
    }

    // 3. 验签
    const calculated = createSign(signParams, MERCHANT_KEY, 'HMAC-SHA256');
    if (calculated !== sign) {
        return res.send('FAIL'); // 签名不匹配
    }

    // 4. 验证交易状态
    if (signParams.returncode !== '00') {
        return res.send('FAIL');
    }

    // 5. 幂等：检查订单是否已处理
    const order = await getOrder(signParams.orderid);
    if (order.status === 'paid') {
        processedNonces.add(signParams.nonce);
        return res.send('OK');
    }

    // 6. 处理业务逻辑
    await updateOrderStatus(signParams.orderid, 'paid', {
        transactionId: signParams.transaction_id,
        amount: signParams.amount,
        paidAt: signParams.datetime,
    });

    // 7. 记录 nonce + 返回OK
    processedNonces.add(signParams.nonce);
    res.send('OK');
});