创建订单接口
通过支付FM 接口为您的业务系统创建一笔支付订单,返回支付链接供顾客扫码 / 跳转完成支付。
1 接口说明
免签和签约类型支付方式统一使用此接口,仅「支付方式 payType」参数不同。接口返回支付链接后,由您的业务系统负责跳转或展示二维码。
https://api.zhifux.com。所有请求必须走 POST,参数通过 URL Query 传递(application/x-www-form-urlencoded)。
2 请求参数
以下为 V2 版本完整参数。V1 版本字段名完全一致,仅 sign_type / timestamp 可选。
| 参数 | 必须 | 类型 | 示例 | 说明 |
|---|---|---|---|---|
merchant_id | 必填 | string | 88888888 |
商户号。在支付FM 商户后台【用户中心】处查看,不是登录用户名。 |
orderNo | 必填 | string | N001 |
商户订单号。仅允许字母或数字,建议不超过 32 字符,不能有中文。唯一 |
amount | 必填 | number | 100.00 |
订单金额,单位:元。最多小数点后 2 位,不能小于 0.01;免签类型订单金额不能小于 1 元。 |
payType | 必填 | string | alipay |
支付方式。需在商户后台配置对应收款号。可选值:alipay / wxpaynative / aloop / tloop / bloop 等,详见文末「payType 选值说明」。 |
notifyUrl | 必填 | string | https://demo.com/success |
异步通知地址(200 字符以内,http(s) 开头)。支付成功后平台会向此地址发送 POST 回调,必须公网可访问,收到后原样返回 success 即可。 |
returnUrl | 可选 | string | https://demo.com/paid |
同步跳转地址。支付完成后浏览器跳转到此页面,仅作为用户界面展示,不能用于订单已支付校验。请勿与 notifyUrl 相同。 |
attach | 可选 | string | order-ref-42 |
附加信息,回调时原样回传。用于在您的业务系统里关联订单或透传标记。 |
subject | 可选 | string | 会员充值 |
商品标题,100 字符以内。签约类型会原样透传到支付平台。 |
body | 可选 | string | 300元额度包 |
商品描述,200 字符以内。 |
payDuration | 可选 | integer | 5 |
订单支付有效期(分钟),默认 5,最大 15。 |
payee | 可选 | string | sj1 |
指定收款号。值为商户后台设置的免签类型手机编号,或签约类型微信系的账号标识 / 支付宝系的支付宝账号。不传则由轮循池自动分配。 |
returnType | 可选 | string | json |
接口返回方式:json(默认)返回支付链接;page 直接重定向到支付页。非页面环境(APP 后端)建议用 json。 |
apiMode | 可选 | string | post_form |
回调请求方式。默认 GET;传 post_form 改为 POST 表单。 |
timestamp | V2必填 | string | 1730900000 |
10 位秒级时间戳。用于防重放,与平台服务器时间相差超过 ±5 分钟 将验签失败。参与签名。 |
sign_type | 可选 | string | RSA2 |
签名类型。请求 /v2/startOrder 时可省略,平台强制 RSA2 验签;请求 /startOrder 时传 RSA2 则切换到 V2 验签。不参与签名。 |
sign | 必填 | string | Base64 串 | V2 签名结果。使用商户 RSA 私钥对 全部请求参数(剔除 sign / sign_type / _input_charset)按 key 升序拼接后的字符串执行 SHA256WithRSA,结果 Base64 编码。 |
3 请求示例
# 替换 YOUR_BASE_URL / YOUR_MERCHANT_ID / YOUR_PRIVATE_KEY / YOUR_PAY_TYPE curl -X POST "https://YOUR_BASE_URL/api/v2/startOrder\ ?merchant_id=YOUR_MERCHANT_ID\ &orderNo=N001\ &amount=100.00\ &payType=alipay\ ¬ifyUrl=https%3A%2F%2Fdemo.com%2Fsuccess\ ×tamp=1730900000\ &sign=BASE64_SIGNATURE"
<?php // V2 RSA2 签名下单完整示例 $apiUrl = 'https://YOUR_BASE_URL/api/v2/startOrder'; $merchantId = 'YOUR_MERCHANT_ID'; $privateKey = '-----BEGIN PRIVATE KEY----- ... 你的 RSA 私钥 ... -----END PRIVATE KEY-----'; // 1. 组参数(sign_type / sign 先不放) $params = [ 'merchant_id' => $merchantId, 'orderNo' => 'N001', 'amount' => '100.00', 'payType' => 'alipay', 'notifyUrl' => 'https://demo.com/success', 'attach' => 'order-ref-42', 'timestamp' => (string)time(), ]; // 2. 签名:按参数名升序拼 k=v&k=v,剔除空值 ksort($params, SORT_STRING); $parts = []; foreach ($params as $k => $v) { if ($v !== null && $v !== '') $parts[] = $k . '=' . $v; } $signStr = implode('&', $parts); // 3. RSA 私钥签名 → Base64 $pkey = openssl_pkey_get_private($privateKey); $signature = ''; openssl_sign($signStr, $signature, $pkey, OPENSSL_ALGO_SHA256); $params['sign'] = base64_encode($signature); // 4. POST 发起 $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => $apiUrl . '?' . http_build_query($params), CURLOPT_POST => 1, CURLOPT_RETURNTRANSFER => 1, CURLOPT_SSL_VERIFYPEER => false, CURLOPT_TIMEOUT => 15, ]); $resp = curl_exec($ch); curl_close($ch); $data = json_decode($resp, true); if ($data['success']) { header('Location: ' . $data['data']['payUrl']); } else { echo '创建失败:' . $data['msg']; } // 返回示例见下方「返回结果」章节 ?>
// Java 11+ 示例,使用 java.net.http.HttpClient import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.security.*; import java.security.spec.PKCS8EncodedKeySpec; import java.util.*; import java.util.stream.Collectors; public class PayDemo { public static void main(String[] args) throws Exception { String baseUrl = "https://YOUR_BASE_URL"; String merchantId = "YOUR_MERCHANT_ID"; String privateKeyPem = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"; // 1. 组参数 Mapparams = new LinkedHashMap(); params.put("merchant_id", merchantId); params.put("orderNo", "N001"); params.put("amount", "100.00"); params.put("payType", "alipay"); params.put("notifyUrl", "https://demo.com/success"); params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000)); // 2. 按 key 升序拼 k=v&k=v(剔除空值) String signStr = params.entrySet().stream() .filter(e -> e.getValue() != null && !e.getValue().isEmpty()) .sorted(Map.Entry.comparingByKey()) .map(e -> e.getKey() + "=" + e.getValue()) .collect(Collectors.joining("&")); // 3. RSA 签名 → Base64 String sign = rsa2Sign(privateKeyPem, signStr); params.put("sign", sign); // 4. POST String query = params.entrySet().stream() .map(e -> URLEncoder.encode(e.getKey(), "UTF-8") + "=" + URLEncoder.encode(e.getValue(), "UTF-8")) .collect(Collectors.joining("&")); HttpRequest req = HttpRequest.newBuilder() .uri(URI.create(baseUrl + "/api/v2/startOrder?" + query)) .POST(HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse resp = HttpClient.newHttpClient() .send(req, HttpResponse.BodyHandlers.ofString()); System.out.println(resp.body()); } // RSA2 签名辅助方法 static String rsa2Sign(String pem, String content) throws Exception { byte[] der = Base64.getDecoder().decode( pem.replaceAll("-----BEGIN PRIVATE KEY-----|-----END PRIVATE KEY-----|\\s+", "")); PrivateKey key = KeyFactory.getInstance("RSA") .generatePrivate(new PKCS8EncodedKeySpec(der)); Signature s = Signature.getInstance("SHA256WithRSA"); s.initSign(key); s.update(content.getBytes()); return Base64.getEncoder().encodeToString(s.sign()); } }
# Python 3.8+ 示例,requests + cryptography import requests import time from cryptography.hazmat.primitives import hashes, serialization from cryptography.hazmat.primitives.asymmetric import padding import base64 BASE_URL = "https://YOUR_BASE_URL" MERCHANT_ID = "YOUR_MERCHANT_ID" PRIVATE_KEY_PEM = """-----BEGIN PRIVATE KEY----- ... 你的 RSA 私钥 ... -----END PRIVATE KEY-----""" # 1. 组参数 params = { "merchant_id": MERCHANT_ID, "orderNo": "N001", "amount": "100.00", "payType": "alipay", "notifyUrl": "https://demo.com/success", "timestamp": str(int(time.time())), } # 2. 按 key 升序拼 k=v&k=v(剔除空值) sign_str = "&".join( f"{k}={v}" for k, v in sorted(params.items()) if v is not None and v != "" ) # 3. RSA 签名 → Base64 private_key = serialization.load_pem_private_key( PRIVATE_KEY_PEM.encode(), password=None) signature = private_key.sign( sign_str.encode(), padding.PKCS1v15(), hashes.SHA256(), ) params["sign"] = base64.b64encode(signature).decode() # 4. POST resp = requests.post( f"{BASE_URL}/api/v2/startOrder", params=params, timeout=15, ) print(resp.json())
// Node.js 18+ 示例,内置 fetch + crypto const crypto = require('crypto'); const BASE_URL = 'https://YOUR_BASE_URL'; const MERCHANT_ID = 'YOUR_MERCHANT_ID'; const PRIVATE_KEY = `-----BEGIN PRIVATE KEY----- ... 你的 RSA 私钥 ... -----END PRIVATE KEY-----`; async function startOrder() { // 1. 组参数 const params = { merchant_id: MERCHANT_ID, orderNo: 'N001', amount: '100.00', payType: 'alipay', notifyUrl: 'https://demo.com/success', timestamp: Math.floor(Date.now() / 1000).toString(), }; // 2. 按 key 升序拼 k=v&k=v const signStr = Object.keys(params) .sort() .filter(k => params[k]) .map(k => k + '=' + params[k]) .join('&'); // 3. RSA 签名 → Base64 const sign = crypto.createSign('RSA-SHA256') .update(signStr) .sign(PRIVATE_KEY, 'base64'); params.sign = sign; // 4. POST const qs = new URLSearchParams(params); const resp = await fetch(BASE_URL + '/api/v2/startOrder?' + qs, { method: 'POST', }); return await resp.json(); } startOrder().then(console.log).catch(console.error);
4 返回结果
HTTP 状态码统一 200;业务成功 / 失败通过响应体 success 字段区分。返回格式固定:
{ "success": true, "code": 200, "msg": "success", "timestamp": 1730900000123, "data": { "id": "1408103748495998976", "payUrl": "https://pay.zhifux.com/pay?orderNo=1408103748495998976" } }
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 请求是否成功。true 时 data 有值,false 时请查看 msg |
code | number | 业务状态码,200 表示成功。不要和 HTTP 状态码混淆。 |
msg | string | 描述信息,成功时为 success,失败时为错误原因。 |
timestamp | number | 毫秒级时间戳。 |
data.id | string | 平台订单号,用于后续查询。 |
data.payUrl | string | 支付链接。顾客访问此链接完成支付。 |
5 签名规则
| 版本 | 待签名字符串 |
|---|---|
| V2 | 剔除 sign / sign_type / _input_charset / sign_v2 / sign_type_v2 与空值后,按参数名 ASCII 升序拼成 k=v&k=v(值 不做 URL 编码),再用商户 RSA 私钥执行 SHA256WithRSA,结果 Base64 编码。 |
签名串构造步骤(V2)
- 取全部请求参数的 原始值(未做 URL 编码),剔除
sign/sign_type/_input_charset以及值为空的参数。 - 按参数名 ASCII 升序排序(
merchant_id<orderNo<timestamp< ...)。 - 用
k=v拼接,参数之间用&连接。 - 对拼接结果执行
SHA256WithRSA(RSA 私钥签名),结果 Base64 编码,作为sign参数传入。
timestamp 参数必须参与签名,且与平台服务器时间差需在 ±5 分钟内,否则验签失败。
6 常见错误码
500500500amount 必须是标准数值且满足对应类型下限。500500payType 值不正确,或后台未配置对应收款号。5004008merchant_id 与旧名同时出现),保留一个即可。XXX: must not be blank 通常是请求方式 / 参数名不对——确认请求是 POST、参数走 URL Query(不是 JSON Body)、字段名与文档一致。
附 附录
在线调试
接口在线调试与请求示例代码(Apifox):https://zpq496vyjp.apifox.cn/334335379e0
payType 选值说明
支付方式(通道)的收款号配置在支付FM 平台的【免签类型】和【签约类型】功能菜单下,调用接口前请确保已配置对应的收款账号。
免签类型:收款手机需要安装监控 APP 挂机;签约类型:需要开通对应的签约商户和支付产品。
支付方式实际体验效果:https://docs.zhifux.com/read/zhifufm/paytype
轮循池传值枚举(轮循池可混合多支付方式轮循收款,池中预设支付方式按权重分配,后台可查看轮循池详细介绍):
| 值 | 类型 | 说明 | 收款号类型 | 适用端口 |
|---|---|---|---|---|
aloop | string | 支付宝轮循池(推荐) | 自由设置 | PC / WAP |
tloop | string | 微信轮循池(推荐) | 自由设置 | PC / WAP |
bloop | string | 网银系轮循池(推荐) | 自由设置 | PC / WAP |
returnUrl 保留参数说明
订单为已支付状态时,系统会按传入的 returnUrl 重定向跳转,以下参数为跳转时系统默认携带,请勿自行携带传入。携带参数仅用于配合业务系统的页面展示,请勿用于订单已支付校验;回调通知参数接收请参考同目录《支付成功回调》。
| 参数 | 说明 |
|---|---|
orderNo | 商户订单号 |
mchOrderNo | 商户订单号 |
platformOrderNo | 平台订单号 |
orderState | 跳转状态值 |
amount | 商户订单金额 |
actualPayAmount | 实际支付金额 |
AI 开发提示词(V2)
以下为使用 AI 编写系统调用创建订单接口的参考提示词,可补充具体开发语言、入库操作等要求后使用:
1.我需要按支付FM的 V2(RSA2)规范开发创建订单接口,请按以下要求实现。 2.接口地址:`【接口根地址】/v2/startOrder`,请求方式 POST,参数走 URL Query,Content-Type: application/x-www-form-urlencoded。 3.请求参数:merchant_id、orderNo、amount、notifyUrl、payType、returnUrl、attach、subject、body 等。 4.必传参数 timestamp:10 位秒级时间戳(当前毫秒/1000),必须参与签名,且与服务器时间差需在 ±5 分钟内。 5.签名规则:取全部请求参数(含 timestamp),剔除 sign、sign_type、_input_charset 以及空值,按参数名 ASCII 升序拼成 k=v&k=v(值不做 URL 编码),用商户 RSA 私钥执行 SHA256WithRSA 签名,结果 Base64 编码后作为 sign 提交。 6.密钥配置:提供配置入口分别保存【接口根地址】【商户号】【商户私钥(PKCS#8 PEM)】;私钥不得硬编码、不得提交到代码仓库。 7.回调验签:回调参数中除 V1 的 sign 外还有 sign_v2、sign_type_v2、timestamp;验签时剔除 sign、sign_type、_input_charset、sign_v2、sign_type_v2 及空值,按 key 升序拼串(timestamp 参与),用平台公钥(GET 【接口根地址】/platformRsaPublicKey 获取,建议缓存 1 小时)执行 SHA256WithRSA 验证 sign_v2。 8.验签失败必须拒绝处理业务并记录日志;验签通过后仍需在响应体返回纯文本 success。 9.请给出完整可运行代码,并加中文注释。
MD5 签名示例(V1 调试用)
支付 DEMO 中有完整说明和建议使用的工具包,以下只是签名示例(Java),其他语言可以用示例参数签名,签名结果一致表示签名函数可用。
供技术调试对比 MD5 算法:abc123456 的 MD5 加密串——大写 0659C7992E268962384EB17FAFE88364,小写 0659c7992e268962384eb17fafe88364。
package ltd.nnt.zhifu.test;
import java.math.BigInteger;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
public class MD5Utils {
/**
* 使用md5的算法进行加密
*/
public static String md5(String plainText) {
byte[] secretBytes = null;
try {
// 必须与平台一致使用 UTF-8,否则含中文的 attach 等参数签名结果会不一致
secretBytes = MessageDigest.getInstance("md5").digest(
plainText.getBytes(java.nio.charset.StandardCharsets.UTF_8));
} catch (NoSuchAlgorithmException e) {
throw new RuntimeException("没有md5这个算法!");
}
String md5code = new BigInteger(1, secretBytes).toString(16);// 16进制数字
// 如果生成数字未满32位,需要前面补0
for (int i = 0; i < 32 - md5code.length(); i++) {
md5code = "0" + md5code;
}
return md5code;
}
public static void main(String[] args) {
System.out.println(md5("abc123456"));
}
}
