商户 API 对接文档

1. 快速接入

1. 向平台运营获取商户号、商户密钥和已开通的产品编码。
2. 校准商户服务器时间，生成 Unix 秒级时间戳和每次唯一的 Nonce。
3. 按本文规则签名，先调用费率接口验证认证是否正确。
4. 创建订单，保存平台返回的 system_no，将客户跳转至 payment_url。
5. 实现并公网开放 notify_url，验签、幂等处理通知并返回约定成功应答。

2. 请求认证与签名

创建订单、查询订单和查询费率都必须携带签名请求头。登录账号和登录密码不参与 API 认证。

签名原文

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + RAW_BODY

创建订单签名原文示例

POST
/openapi/v1/orders
1792236170
43531248c0494b9aa2950230849f326b
{"merchant_order_no":"T10001","product_code":"203","amount":"100.00","client_device":"pc","notify_url":"https://merchant.example/callback"}

signature = hex_lowercase(HMAC_SHA256(商户密钥, UTF8(签名原文)))

3. 可直接参考的签名代码

Java 11+

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.HexFormat;
import java.util.UUID;

String merchantNo = "平台分配的商户号";
String secret = "平台分配的商户密钥";
String path = "/openapi/v1/orders";
String body = "{\"merchant_order_no\":\"T10001\",\"product_code\":\"203\",\"amount\":\"100.00\",\"client_device\":\"pc\",\"notify_url\":\"https://merchant.example/callback\"}";
String timestamp = String.valueOf(Instant.now().getEpochSecond());
String nonce = UUID.randomUUID().toString().replace("-", "");
String text = "POST\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + body;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = HexFormat.of().formatHex(mac.doFinal(text.getBytes(StandardCharsets.UTF_8)));
HttpRequest req = HttpRequest.newBuilder(URI.create("https://weiyi9991weiyipay.xyz" + path))
 .header("Content-Type","application/json; charset=UTF-8")
 .header("X-Merchant-No",merchantNo).header("X-Timestamp",timestamp)
 .header("X-Nonce",nonce).header("X-Signature",signature)
 .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)).build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());

const crypto = require('crypto');
const path = '/openapi/v1/orders';
const body = JSON.stringify(order);
const timestamp = Math.floor(Date.now()/1000).toString();
const nonce = crypto.randomUUID().replaceAll('-','');
const text = `POST\n${path}\n${timestamp}\n${nonce}\n${body}`;
const signature = crypto.createHmac('sha256', secret)
 .update(text,'utf8').digest('hex');

$path = '/openapi/v1/orders';
$body = json_encode($order, JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$text = "POST\n{$path}\n{$timestamp}\n{$nonce}\n{$body}";
$signature = hash_hmac('sha256', $text, $secret);

4. 创建订单

请求正文

{
  "merchant_order_no": "T202610170001",
  "product_code": "203",
  "amount": "100.00",
  "client_device": "android",
  "notify_url": "https://merchant.example.com/payment/callback"
}

成功响应（HTTP 200）

{
  "code": 0,
  "message": "success",
  "data": {
    "system_no": "WEIYI202610170001...",
    "merchant_order_no": "T202610170001",
    "status": "pending",
    "payment_url": "https://..."
  }
}

商户必须保存 system_no，并将付款客户跳转到 payment_url。HTTP 超时或连接中断时，先查单确认，不要直接换订单号重复下单。

5. 查询订单与费率

签名 PATH 必须替换成真实系统单号路径；GET 请求体为空。

{"code":0,"message":"success","data":{"system_no":"WEIYI...","merchant_order_no":"T...","amount":"100.00","status":"paid","created_at":"2026-10-17T09:30:00+00:00"}}

使用相同签名请求头，只返回该商户已开通且启用的产品。

{"code":0,"message":"success","data":[{"code":"203","name":"产品名称","fee_rate":"13.000"}]}

fee_rate 单位是百分比，13.000 表示 13%。

6. 支付结果与冲正异步回调

平台向订单 notify_url 发送 POST application/json。同一事件可能重试，商户必须以 event_id 幂等；同一订单可能先收到 paid，之后收到独立的 reversed。

支付成功事件

{"event_id":"uuid","system_no":"WEIYI...","merchant_order_no":"T...","amount":"100.00","status":"paid","confirmation_source":"upstream_callback","paid_at":"2026-10-17T11:26:45+00:00"}

冲正事件

{"event_id":"另一个uuid","system_no":"WEIYI...","merchant_order_no":"T...","amount":"100.00","status":"reversed","confirmation_source":"reversal","paid_at":"2026-10-17T11:26:45+00:00"}

1. 读取原始请求体字节，不要解析后重新序列化再验签。
2. 用商户密钥计算 HMAC-SHA256，与 X-Signature 安全比较。
3. 核对商户号、事件 ID、订单号、金额和状态。
4. 以 event_id 建唯一约束；重复事件直接返回成功，不重复入账或扣账。
5. paid 执行成功入账；reversed 撤销此前成功入账。
6. 本地事务提交成功后再返回成功应答。

平台认可的成功应答

HTTP 200
success

HTTP 200
ok

也支持：

{"success":true}
{"code":0}
{"code":200}

7. HTTP 状态码与常见问题

上线前自检

• 程序接口域名是 weiyi9991weiyipay.xyz。
• 服务器已通过 NTP 校时。
• Nonce 至少 12 位且每次不同。
• 签名使用小写十六进制 HMAC-SHA256。
• 签名 JSON 与实际发送 JSON 完全相同。
• 回调地址公网可访问，并允许来源 IP 148.66.16.74。
• 回调支持 paid 和 reversed，以 event_id 幂等。
• 成功后明确返回 success、ok 或标准成功 JSON。
• 日志不得记录完整商户密钥。