创建订单

创建订单接口

通过支付FM 接口为您的业务系统创建一笔支付订单,返回支付链接供顾客扫码 / 跳转完成支付。

POST /api/v2/startOrder V2 推荐

1 接口说明

免签和签约类型支付方式统一使用此接口,仅「支付方式 payType」参数不同。接口返回支付链接后,由您的业务系统负责跳转或展示二维码。

Base URL:接口根地址在商户后台【用户中心 → API开发信息】处查看,形如 https://api.zhifux.com。所有请求必须走 POST,参数通过 URL Query 传递(application/x-www-form-urlencoded)。

2 请求参数

以下为 V2 版本完整参数。V1 版本字段名完全一致,仅 sign_type / timestamp 可选。

参数必须类型示例说明
merchant_id必填string88888888 商户号。在支付FM 商户后台【用户中心】处查看,不是登录用户名。
orderNo必填stringN001 商户订单号。仅允许字母或数字,建议不超过 32 字符,不能有中文。唯一
amount必填number100.00 订单金额,单位:元。最多小数点后 2 位,不能小于 0.01;免签类型订单金额不能小于 1 元。
payType必填stringalipay 支付方式。需在商户后台配置对应收款号。可选值:alipay / wxpaynative / aloop / tloop / bloop 等,详见文末「payType 选值说明」。
notifyUrl必填stringhttps://demo.com/success 异步通知地址(200 字符以内,http(s) 开头)。支付成功后平台会向此地址发送 POST 回调,必须公网可访问,收到后原样返回 success 即可。
returnUrl可选stringhttps://demo.com/paid 同步跳转地址。支付完成后浏览器跳转到此页面,仅作为用户界面展示,不能用于订单已支付校验。请勿与 notifyUrl 相同。
attach可选stringorder-ref-42 附加信息,回调时原样回传。用于在您的业务系统里关联订单或透传标记。
subject可选string会员充值 商品标题,100 字符以内。签约类型会原样透传到支付平台。
body可选string300元额度包 商品描述,200 字符以内。
payDuration可选integer5 订单支付有效期(分钟),默认 5,最大 15。
payee可选stringsj1 指定收款号。值为商户后台设置的免签类型手机编号,或签约类型微信系的账号标识 / 支付宝系的支付宝账号。不传则由轮循池自动分配。
returnType可选stringjson 接口返回方式:json(默认)返回支付链接;page 直接重定向到支付页。非页面环境(APP 后端)建议用 json。
apiMode可选stringpost_form 回调请求方式。默认 GET;传 post_form 改为 POST 表单。
timestampV2必填string1730900000 10 位秒级时间戳。用于防重放,与平台服务器时间相差超过 ±5 分钟 将验签失败。参与签名。
sign_type可选stringRSA2 签名类型。请求 /v2/startOrder 时可省略,平台强制 RSA2 验签;请求 /startOrder 时传 RSA2 则切换到 V2 验签。不参与签名。
sign必填stringBase64 串 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\
  &notifyUrl=https%3A%2F%2Fdemo.com%2Fsuccess\
  &timestamp=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. 组参数
        Map params = 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"
  }
}
字段类型说明
successboolean请求是否成功。true 时 data 有值,false 时请查看 msg
codenumber业务状态码,200 表示成功。不要和 HTTP 状态码混淆。
msgstring描述信息,成功时为 success,失败时为错误原因。
timestampnumber毫秒级时间戳。
data.idstring平台订单号,用于后续查询。
data.payUrlstring支付链接。顾客访问此链接完成支付。

5 签名规则

V2 核心差异:不是把 V1 的 MD5 换成 RSA 就行——拼串方式从"固定顺序"改成了"参数名升序",签名函数必须重写。密钥生成与配置、回调验签等完整说明见同目录《签名规则与密钥总览》。
版本待签名字符串
V2 剔除 sign / sign_type / _input_charset / sign_v2 / sign_type_v2 与空值后,按参数名 ASCII 升序拼成 k=v&k=v(值 不做 URL 编码),再用商户 RSA 私钥执行 SHA256WithRSA,结果 Base64 编码。

签名串构造步骤(V2)

  1. 取全部请求参数的 原始值(未做 URL 编码),剔除 sign / sign_type / _input_charset 以及值为空的参数。
  2. 按参数名 ASCII 升序排序(merchant_id < orderNo < timestamp < ...)。
  3. 用 k=v 拼接,参数之间用 & 连接。
  4. 对拼接结果执行 SHA256WithRSA(RSA 私钥签名),结果 Base64 编码,作为 sign 参数传入。
防重放:timestamp 参数必须参与签名,且与平台服务器时间差需在 ±5 分钟内,否则验签失败。

6 常见错误码

500
签名不正确:检查签名算法、拼串顺序、UTF-8 编码、RSA 公钥是否已正确配置到商户后台。
500
merchant_id 不存在 / 用户账号无权限使用:商户号不正确或账号已被限制使用。
500
金额格式不正确 / 金额不能小于或等于0 / 免签类型订单金额不能小于1元:amount 必须是标准数值且满足对应类型下限。
500
商户接口额度不足,请充值:登录商户后台充值接口额度。
500
发起订单失败,类型不存在:payType 值不正确,或后台未配置对应收款号。
500
无可用收款方式的收款账号:payType 对应的收款号后台未配置或已全部占用。
4008
参数名新旧版本冲突:同一参数传了两个名字且值不同(如 merchant_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

轮循池传值枚举(轮循池可混合多支付方式轮循收款,池中预设支付方式按权重分配,后台可查看轮循池详细介绍):

值类型说明收款号类型适用端口
aloopstring支付宝轮循池(推荐)自由设置PC / WAP
tloopstring微信轮循池(推荐)自由设置PC / WAP
bloopstring网银系轮循池(推荐)自由设置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"));
    }
}