API接入文档

import hashlib, time, random, requests

API_KEY    = "你的API_KEY"
API_SECRET = "你的API_SECRET"
API_URL    = "https://平台地址/api/"

def make_sign(params, secret):
    filtered = {k: v for k, v in params.items() if v != '' and k != 'sign'}
    sign_str = '&'.join(f'{k}={v}' for k, v in sorted(filtered.items()))
    sign_str += f'&secret={secret}'
    return hashlib.md5(sign_str.encode()).hexdigest()

params = {
    'api_key': API_KEY,
    'timestamp': str(int(time.time())),
    'channel': 'kpay',
    'order_no': f'ORD{int(time.time())}{random.randint(1000,9999)}',
    'amount': '100.00',
    'currency': 'HKD',
    'pay_method': 'alipay_scan',
    'subject': '商品购买',
    'notify_url': 'https://www.example.com/notify',
    'return_url': 'https://www.example.com/return',
}
params['sign'] = make_sign(params, API_SECRET)

resp = requests.post(API_URL + 'pay.php', data=params, verify=False)
result = resp.json()

if result['code'] == 0:
    pay_url = result['data']['pay_url']
    # 将 pay_url 返回给前端

import java.security.MessageDigest;
import java.util.*;
import java.net.http.*;
import java.net.URI;

public class PayClient {

    static String API_KEY    = "你的API_KEY";
    static String API_SECRET = "你的API_SECRET";
    static String API_URL    = "https://平台地址/api/";

    public static String sign(Map<String, String> params, String secret) {
        TreeMap<String, String> sorted = new TreeMap<>(params);
        sorted.remove("sign");
        StringBuilder sb = new StringBuilder();
        for (var e : sorted.entrySet()) {
            if (e.getValue() != null && !e.getValue().isEmpty())
                sb.append(e.getKey()).append("=").append(e.getValue()).append("&");
        }
        sb.append("secret=").append(secret);
        return md5(sb.toString());
    }

    static String md5(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] hash = md.digest(input.getBytes("UTF-8"));
            StringBuilder hex = new StringBuilder();
            for (byte b : hash) hex.append(String.format("%02x", b));
            return hex.toString();
        } catch (Exception e) { throw new RuntimeException(e); }
    }

    public static void main(String[] args) throws Exception {
        Map<String, String> params = new HashMap<>();
        params.put("api_key", API_KEY);
        params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
        params.put("channel", "kpay");
        params.put("order_no", "ORD" + System.currentTimeMillis());
        params.put("amount", "100.00");
        params.put("currency", "HKD");
        params.put("pay_method", "alipay_scan");
        params.put("subject", "商品购买");
        params.put("notify_url", "https://www.example.com/notify");
        params.put("sign", sign(params, API_SECRET));

        // 拼接 form body 并发送 POST
        StringBuilder body = new StringBuilder();
        params.forEach((k, v) -> {
            if (body.length() > 0) body.append("&");
            body.append(k).append("=").append(java.net.URLEncoder.encode(v, java.nio.charset.StandardCharsets.UTF_8));
        });
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(API_URL + "pay.php"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body.toString()))
            .build();
        HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body());
    }
}

const crypto = require('crypto');
const https = require('https');
const querystring = require('querystring');

const API_KEY    = '你的API_KEY';
const API_SECRET = '你的API_SECRET';
const API_URL    = 'https://平台地址/api/';

function makeSign(params, secret) {
    const keys = Object.keys(params).filter(k => k !== 'sign' && params[k] !== '').sort();
    let str = keys.map(k => k + '=' + params[k]).join('&');
    str += '&secret=' + secret;
    return crypto.createHash('md5').update(str).digest('hex');
}

const params = {
    api_key: API_KEY,
    timestamp: String(Math.floor(Date.now() / 1000)),
    channel: 'kpay',
    order_no: 'ORD' + Date.now() + Math.floor(Math.random() * 10000),
    amount: '100.00',
    currency: 'HKD',
    pay_method: 'alipay_scan',
    subject: '商品购买',
    notify_url: 'https://www.example.com/notify',
    return_url: 'https://www.example.com/return',
};
params.sign = makeSign(params, API_SECRET);

const postData = querystring.stringify(params);
const url = new URL(API_URL + 'pay.php');
const req = https.request({
    hostname: url.hostname, path: url.pathname,
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
}, (res) => {
    let body = '';
    res.on('data', d => body += d);
    res.on('end', () => {
        const result = JSON.parse(body);
        if (result.code === 0) {
            console.log('pay_url:', result.data.pay_url);
        }
    });
});
req.write(postData);
req.end();

# Flask 示例 - 商户后端查询接口

from flask import Flask, request, jsonify

@app.route('/check_order')
def check_order():
    order_no = request.args.get('order_no', '')
    if not order_no:
        return jsonify({'status': -1})

    params = {
        'api_key': API_KEY,
        'timestamp': str(int(time.time())),
        'order_no': order_no,
    }
    params['sign'] = make_sign(params, API_SECRET)

    resp = requests.post(API_URL + 'query.php', data=params, verify=False)
    result = resp.json()

    return jsonify({
        'status': result.get('data', {}).get('status', 0),
        'paid_at': result.get('data', {}).get('paid_at', ''),
    })

// Spring Boot 示例 - 商户后端查询接口

@GetMapping("/check_order")
public Map<String, Object> checkOrder(@RequestParam String order_no) {
    Map<String, String> params = new HashMap<>();
    params.put("api_key", API_KEY);
    params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
    params.put("order_no", order_no);
    params.put("sign", sign(params, API_SECRET));

    // 发送 POST 到平台查询接口
    String response = httpPost(API_URL + "query.php", params);
    JSONObject result = new JSONObject(response);
    JSONObject data = result.optJSONObject("data");

    Map<String, Object> ret = new HashMap<>();
    ret.put("status", data != null ? data.optInt("status", 0) : 0);
    ret.put("paid_at", data != null ? data.optString("paid_at", "") : "");
    return ret;
}

// Express 示例 - 商户后端查询接口

app.get('/check_order', async (req, res) => {
    const { order_no } = req.query;
    if (!order_no) return res.json({ status: -1 });

    const params = {
        api_key: API_KEY,
        timestamp: String(Math.floor(Date.now() / 1000)),
        order_no,
    };
    params.sign = makeSign(params, API_SECRET);

    const resp = await fetch(API_URL + 'query.php', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams(params),
    });
    const result = await resp.json();
    const data = result.data || {};

    res.json({
        status: data.status || 0,
        paid_at: data.paid_at || '',
    });
});

params = {
    'api_key': API_KEY,
    'timestamp': str(int(time.time())),
    'order_no': '20260301143000123456',
    'refund_amount': '100.00',
}
params['sign'] = make_sign(params, API_SECRET)

resp = requests.post(API_URL + 'refund.php', data=params, verify=False)
result = resp.json()
if result['code'] == 0:
    print('退款成功', result['data'])

Map<String, String> params = new HashMap<>();
params.put("api_key", API_KEY);
params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
params.put("order_no", "20260301143000123456");
params.put("refund_amount", "100.00");
params.put("sign", sign(params, API_SECRET));

String response = httpPost(API_URL + "refund.php", params);

const params = {
    api_key: API_KEY,
    timestamp: String(Math.floor(Date.now() / 1000)),
    order_no: '20260301143000123456',
    refund_amount: '100.00',
};
params.sign = makeSign(params, API_SECRET);

const resp = await fetch(API_URL + 'refund.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams(params),
});
const result = await resp.json();

# Flask 示例
from flask import Flask, request
import hashlib

@app.route('/notify', methods=['POST'])
def notify():
    params = dict(request.form)
    sign = params.pop('sign', '')

    # 1. 验签
    filtered = {k: v for k, v in sorted(params.items()) if v != ''}
    sign_str = '&'.join(f'{k}={v}' for k, v in filtered.items())
    sign_str += f'&secret={API_SECRET}'

    if hashlib.md5(sign_str.encode()).hexdigest() != sign:
        return 'sign error', 200

    # 2. 根据 trade_status 分别处理
    trade_status = params['trade_status']
    order_no = params['merchant_order_no']

    if trade_status == 'PAID':
        # 发货/充值等
        pass
    elif trade_status == 'REFUNDED':
        # 退款：更新订单状态
        pass
    elif trade_status == 'CLOSED':
        # 订单关闭
        pass
    elif trade_status == 'FAIL':
        # 支付失败
        pass

    return 'success', 200

// Spring Boot 示例
@PostMapping("/notify")
public String notify(@RequestParam Map<String, String> params) {
    String sign = params.remove("sign");

    // 1. 验签
    String expected = sign(new HashMap<>(params), API_SECRET);
    if (!expected.equals(sign)) {
        return "sign error";
    }

    // 2. 根据 trade_status 分别处理
    String tradeStatus = params.get("trade_status");
    String orderNo = params.get("merchant_order_no");

    switch (tradeStatus) {
        case "PAID":
            // 发货/充值等
            break;
        case "REFUNDED":
            // 退款处理
            break;
        case "CLOSED":
            // 订单关闭
            break;
        case "FAIL":
            // 支付失败
            break;
    }

    return "success";
}

// Express 示例
const express = require('express');
app.use(express.urlencoded({ extended: true }));

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

    // 1. 验签
    const expected = makeSign(params, API_SECRET);
    if (expected !== sign) {
        return res.send('sign error');
    }

    // 2. 根据 trade_status 分别处理
    const { trade_status, merchant_order_no } = params;

    switch (trade_status) {
        case 'PAID':
            // 发货/充值等
            break;
        case 'REFUNDED':
            // 退款处理
            break;
        case 'CLOSED':
            // 订单关闭
            break;
        case 'FAIL':
            // 支付失败
            break;
    }

    res.send('success');
});