把支付，接入你的业务。

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

GET {BASE}/api/gateway/orders?appKey=YOUR_APP_KEY&merchantOrderNo=SHOP001&amount=10000&subject=TEST&notifyUrl=https%3A%2F%2Fshop.example.com%2Fnotify&signType=HMAC-SHA256-V2&timestamp=CURRENT_UNIX_SECONDS&nonce=NEW_RANDOM_NONCE&sign=CALCULATED_SIGNATURE

{"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": "用户申请退款"
}

{
  "code": 1,
  "msg": "下单成功",
  "trade_no": "X202609200001",
  "payurl": "{BASE}/pay/X202609200001",
  "qrcode": "",
  "urlscheme": "",
  "img": ""
}

{
  "code": 1,
  "msg": "查询订单号成功！",
  "trade_no": "X202609200001",
  "out_trade_no": "SHOP202609200001",
  "type": "wxpay",
  "pid": "10001",
  "addtime": "2026-09-20 12:00:00",
  "name": "测试商品",
  "money": "1.23",
  "endtime": "2026-09-20 12:01:00",
  "status": 1,
  "sign": "实际响应签名",
  "sign_type": "MD5"
}

<?php
function epaySign(array $params, string $secret): string {
    unset($params['sign'], $params['sign_type']);
    $params = array_filter($params, static function ($value) {
        return trim((string)$value) !== '';
    });
    ksort($params, SORT_STRING);
    $pairs = [];
    foreach ($params as $key => $value) {
        $pairs[] = $key . '=' . (string)$value;
    }
    return md5(implode('&', $pairs) . $secret);
}

// 仅用于 MD5；$fields 是根据上文表格提取的查询或通知业务字段。
function epayVerifyMD5(array $fields, array $response, string $secret): bool {
    return strtoupper((string)($response['sign_type'] ?? '')) === 'MD5'
        && hash_equals(epaySign($fields, $secret),
            strtolower((string)($response['sign'] ?? '')));
}

// 发送前：$params 为已保存的业务订单参数，$secret 从服务端配置读取。
// $params['sign'] = epaySign($params, $secret);
// $params['sign_type'] = 'MD5';
// $body = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
// 用 HTTP 客户端 POST $body 至本站 /mapi.php，并设置表单 Content-Type。

import hashlib, hmac, json, os, urllib.parse, urllib.request

BASE = '{BASE}'
PID = os.environ['PAYMENT_EPAY_PID']
SECRET = os.environ['PAYMENT_APP_SECRET']
QUERY_FIELDS = ('trade_no', 'out_trade_no', 'type', 'pid', 'name', 'money', 'status')
NOTIFY_FIELDS = ('pid', 'type', 'name', 'money', 'trade_no', 'out_trade_no', 'trade_status')

def epay_sign(params, secret):
    parts = [f'{k}={params[k]}' for k in sorted(params)
             if k not in ('sign', 'sign_type') and str(params[k]).strip() != '']
    return hashlib.md5(('&'.join(parts) + secret).encode('utf-8')).hexdigest()

def epay_verify(data, fields):
    if str(data.get('sign_type', '')).upper() != 'MD5':
        raise ValueError('当前示例仅支持 MD5，请按商户配置使用正确算法')
    selected = {k: str(data[k]) for k in fields}
    if not hmac.compare_digest(epay_sign(selected, SECRET), str(data.get('sign', '')).lower()):
        raise ValueError('响应验签失败')
    return selected

def epay_post(path, fields):
    params = {k: str(v) for k, v in fields.items()}
    params['pid'] = PID
    params['sign'] = epay_sign(params, SECRET)
    params['sign_type'] = 'MD5'
    request = urllib.request.Request(BASE + path,
        data=urllib.parse.urlencode(params).encode('utf-8'),
        headers={'Content-Type': 'application/x-www-form-urlencoded'})
    with urllib.request.urlopen(request, timeout=20) as response:
        result = json.load(response)
    if result.get('code') != 1:
        raise RuntimeError(result.get('msg', '接口请求失败'))
    return result

def epay_create(order_id, name, money, notify_url, return_url=''):
    return epay_post('/mapi.php', {
        'out_trade_no': order_id, 'type': 'wxpay', 'name': name, 'money': money,
        'notify_url': notify_url, 'return_url': return_url})

def epay_query(order_id):
    result = epay_post('/api.php', {'out_trade_no': order_id})
    fields = epay_verify(result, QUERY_FIELDS)
    if fields['pid'] != PID or fields['out_trade_no'] != order_id:
        raise ValueError('商户或订单号不匹配')
    return result  # 调用方继续核对本地金额、status，再执行幂等业务处理

# created = epay_create(ORDER_ID, '测试商品', '1.23',
#     'https://shop.example.com/payment/notify',
#     'https://shop.example.com/payment/return')
# 使用 created['payurl'] 打开收银台，不能此时标记已付款。
# result = epay_query(ORDER_ID)
# 通知处理：从 HTTP GET 查询参数取单个字符串值，拒绝重复字段，
# 调用 epay_verify(params, NOTIFY_FIELDS)，再完成前述业务核对和事务。
# 网络异常交由业务记录待核对状态；保留原订单号查单，不自动换单重试。

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

BASE = '{BASE}'
APP_KEY = os.environ['PAYMENT_APP_KEY']
SECRET = os.environ['PAYMENT_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 payment_request(string $path, array $business): array {
    $base = '{BASE}';
    $appKey = getenv('PAYMENT_APP_KEY');
    $secret = getenv('PAYMENT_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'];
}
// payment_request('/api/gateway/orders/query', ['merchantOrderNo' => $persistedOrderNo]);
// 下单/退款替换 path 和业务参数；amount/refundAmount 使用 PHP 整数。

const crypto = require('node:crypto');
const BASE = '{BASE}';
async function paymentRequest(path, business) {
  const appKey = process.env.PAYMENT_APP_KEY, secret = process.env.PAYMENT_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 paymentRequest('/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。
# 本函数仅验签，不能替代业务金额核对、持久化和防重复发货。