支付 API 接入文档

Content-Type: application/json
X-App-Key: 你的AppKey

{"code": 0, "message": "ok", "data": {}}

原文 = "fourpay-gateway-v2\n"
     + frame("POST") + frame("/api/gateway/orders") + frame(AppKey)
     + 按字段名排序追加 frame(字段名) + frame(字段值)
sign = Base64URL无填充(HMAC-SHA256(AppSecret, 原文))

POST {BASE}/api/gateway/orders

{
  "merchantOrderNo": "SHOP202609140001",
  "amount": 1000,
  "subject": "测试商品",
  "notifyUrl": "https://shop.example.com/payment/notify",
  "returnUrl": "https://shop.example.com/payment/return",
  "payMethod": "alipay",
  "expireMinutes": 30,
  "signType": "HMAC-SHA256-V2",
  "timestamp": "发送时的Unix秒级时间戳",
  "nonce": "每次请求新生成的随机字符串",
  "sign": "计算得到的签名"
}

{
  "code": 0,
  "message": "ok",
  "data": {
    "orderNo": "Pxxxxxxxx",
    "merchantOrderNo": "SHOP202609140001",
    "cashierUrl": "{BASE}/pay/Pxxxxxxxx"
  }
}

POST {BASE}/api/gateway/orders/query

{"merchantOrderNo": "SHOP202609140001"}

{
  "code": 0,
  "message": "ok",
  "data": {
    "orderNo": "Pxxxxxxxx",
    "merchantOrderNo": "SHOP202609140001",
    "amount": 1000,
    "fee": 0,
    "actualAmount": 1000,
    "refundedAmount": 0,
    "status": "SUCCESS",
    "channelCode": "实际通道编码",
    "payMethod": "alipay",
    "createdAt": "2026-09-14T02:00:00Z",
    "paidAt": "2026-09-14T02:01:00Z"
  }
}

{
  "orderNo": "Pxxxxxxxx",
  "merchantOrderNo": "SHOP202609140001",
  "amount": "1000",
  "status": "SUCCESS",
  "channelCode": "实际通道编码",
  "payTime": "2026-09-14T02:01:00Z",
  "sign": "平台生成的MD5大写签名"
}

HTTP/1.1 200 OK
Content-Type: text/plain

SUCCESS

POST {BASE}/api/gateway/refunds

{
  "merchantOrderNo": "SHOP202609140001",
  "merchantRefundNo": "REFUND202609140001",
  "refundAmount": 1000,
  "reason": "用户申请退款"
}

sign = MD5小写(排序后的参数原文 + AppSecret)
sign_type = MD5

import base64, hashlib, hmac, json, os, secrets, time, urllib.request

BASE = '{BASE}'
APP_KEY = os.environ['FOURPAY_APP_KEY']
SECRET = os.environ['FOURPAY_APP_SECRET']

def frame(value):
    data = str(value).encode('utf-8')
    return str(len(data)).encode('ascii') + b':' + data

def sign_v2(params, path):
    raw = b'fourpay-gateway-v2\n' + frame('POST') + frame(path) + frame(APP_KEY)
    for key in sorted(k for k in params if k != 'sign'):
        raw += frame(key) + frame(params[key])
    digest = hmac.new(SECRET.encode('utf-8'), raw, hashlib.sha256).digest()
    return base64.urlsafe_b64encode(digest).decode('ascii').rstrip('=')

def request(path, business):
    params = dict(business)
    params.update(signType='HMAC-SHA256-V2',
                  timestamp=str(int(time.time())), nonce=secrets.token_hex(16))
    params['sign'] = sign_v2(params, path)
    req = urllib.request.Request(BASE + path,
        data=json.dumps(params, ensure_ascii=False).encode('utf-8'),
        headers={'Content-Type': 'application/json', 'X-App-Key': APP_KEY},
        method='POST')
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if result.get('code') != 0:
        raise RuntimeError(result.get('message', '网关请求失败；请核对订单状态'))
    return result['data']

# 以下调用放入你的服务端业务处理函数，不要反复执行固定示例订单。
# data = request('/api/gateway/orders', {
#     'merchantOrderNo': persisted_order_no, 'amount': 1000, 'subject': '测试商品',
#     'notifyUrl': 'https://shop.example.com/payment/notify', 'payMethod': 'alipay'})
# 保存 data['orderNo']，跳转 data['cashierUrl']。
# result = request('/api/gateway/orders/query', {'merchantOrderNo': persisted_order_no})
# refund = request('/api/gateway/refunds', {
#     'merchantOrderNo': persisted_order_no, 'merchantRefundNo': persisted_refund_no,
#     'refundAmount': 1000, 'reason': '用户申请退款'})
# 超时/异常时保留原业务编号，先核对状态，不能换退款编号重试。

<?php
function fourpay_request(string $path, array $business): array {
    $base = '{BASE}';
    $appKey = getenv('FOURPAY_APP_KEY');
    $secret = getenv('FOURPAY_APP_SECRET');
    if (!$appKey || !$secret) throw new RuntimeException('请配置商户凭据');
    $p = $business;
    unset($p['sign']);
    $p['signType'] = 'HMAC-SHA256-V2';
    $p['timestamp'] = (string) time();
    $p['nonce'] = bin2hex(random_bytes(16));
    $frame = static function ($v): string {
        $s = (string) $v;
        return strlen($s) . ':' . $s; // PHP 字符串使用 UTF-8 字节
    };
    ksort($p, SORT_STRING);
    $raw = "fourpay-gateway-v2\n" . $frame('POST') . $frame($path) . $frame($appKey);
    foreach ($p as $k => $v) $raw .= $frame($k) . $frame($v);
    $p['sign'] = rtrim(strtr(base64_encode(hash_hmac('sha256', $raw, $secret, true)), '+/', '-_'), '=');
    $ch = curl_init($base . $path);
    curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [
            'Content-Type: application/json', 'X-App-Key: ' . $appKey],
        CURLOPT_POSTFIELDS => json_encode($p, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR)]);
    $body = curl_exec($ch);
    $error = curl_error($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($body === false || $status !== 200) throw new RuntimeException('请求结果未知，请查单：' . $error);
    $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if (($result['code'] ?? -1) !== 0) throw new RuntimeException($result['message'] ?? '请求失败');
    return $result['data'];
}
// fourpay_request('/api/gateway/orders/query', ['merchantOrderNo' => $persistedOrderNo]);
// 下单/退款替换 path 和业务参数；amount/refundAmount 使用 PHP 整数。

const crypto = require('node:crypto');
const BASE = '{BASE}';
async function fourpayRequest(path, business) {
  const appKey = process.env.FOURPAY_APP_KEY, secret = process.env.FOURPAY_APP_SECRET;
  if (!appKey || !secret) throw new Error('请配置商户凭据');
  const p = { ...business, signType: 'HMAC-SHA256-V2',
    timestamp: String(Math.floor(Date.now() / 1000)), nonce: crypto.randomBytes(16).toString('hex') };
  delete p.sign;
  const frame = v => { const s = String(v); return Buffer.byteLength(s, 'utf8') + ':' + s; };
  let raw = 'fourpay-gateway-v2\n' + frame('POST') + frame(path) + frame(appKey);
  for (const k of Object.keys(p).sort()) raw += frame(k) + frame(p[k]);
  p.sign = crypto.createHmac('sha256', secret).update(raw, 'utf8').digest('base64url');
  const response = await fetch(BASE + path, { method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-App-Key': appKey },
    body: JSON.stringify(p), signal: AbortSignal.timeout(30000) });
  if (!response.ok) throw new Error('请求结果未知，请查单：HTTP ' + response.status);
  const result = await response.json();
  if (result.code !== 0) throw new Error(result.message || '网关请求失败');
  return result.data;
}
// await fourpayRequest('/api/gateway/orders/query', { merchantOrderNo: persistedOrderNo });
// 在 async 业务函数内调用。amount/refundAmount 使用安全范围内的整数，extra 使用 JSON.stringify。

import hashlib, hmac

def verify_notify(payload, secret):
    if not isinstance(payload, dict):
        return False
    received = payload.get('sign')
    if not isinstance(received, str) or len(received) != 32 or not received.isascii():
        return False
    # 当前平台通知字段都是字符串，拒绝异常类型。
    if any(not isinstance(v, str) for v in payload.values()):
        return False
    items = sorted((k, v) for k, v in payload.items() if k != 'sign' and v != '')
    raw = '&'.join(k + '=' + v for k, v in items) + '&key=' + secret
    expected = hashlib.md5(raw.encode('utf-8')).hexdigest().upper()
    return hmac.compare_digest(expected, received)

# payload = 框架解析的请求JSON
# 验签通过后，必须查本地订单并核对 orderNo、merchantOrderNo、amount、status。
# 事务内去重，保存支付结果和可靠发货任务，提交成功后返回 HTTP 200 / SUCCESS。
# 本函数仅验签，不能替代业务金额核对、持久化和防重复发货。