聚合支付统一下单

聚合支付统一下单接口是支付流程的核心接口，用于创建支付订单。支持微信支付、支付宝、银联等多种支付渠道。

接口信息

• 接口地址：

  /zro/pay/unify-pay

• 请求方式：POST
• Content-Type：application/json

请求参数

公共参数

参数名	类型	必填	长度	描述
merchantNo	String	是	32	商户号
sign	String	是	32	签名

业务参数

参数名	类型	必填	描述	示例值
orderId	String	必填	商户订单号，需保证在商户端不重复	ORDER20231119001
orderAmount	Number	必填	订单总金额，单位：元，精确到小数点后两位	100.00
goodsName	String	必填	商品名称，用于展示在收银台页面或支付明细中	旺仔牛奶
payWay	String	必填	支付方式，详见支付方式说明	SDK_PAY
channel	String	必填	支付渠道，详见支付渠道说明	WECHAT
userIp	String	必填	用户真实 IP 地址	123.123.123.123
fundProcessType	String	否	分账订单标记，详见分账订单标记说明	DELAY_SETTLE
returnSchema	String	条件必填	返回 APP 的 Schema，支付宝且 SDK_PAY 时必传	alipays://...
notifyUrl	String	否	异步通知地址	https://...
returnUrl	String	否	微信 H5 支付方式页面回跳地址	https://...
expiredTime	String	否	订单失效时间，默认 30 分钟	2023-11-19 15:30

请求示例

{
  "merchantNo": "your_merchant_no",
  "orderId": "ORDER20231119001",
  "orderAmount": "100.00",
  "goodsName": "嗖付商城-iPhone手机壳",
  "payWay": "H5_PAY",
  "channel": "WECHAT",
  "userIp": "192.168.1.100",
  "returnSchema": "your_return_schema",
  "notifyUrl": "https://your-domain.com/notify",
  "returnUrl": "https://your-domain.com/return",
  "expiredTime": "2023-11-19 15:30:00",
  "sign": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
}

响应参数

成功响应

参数名	类型	描述
code	Number	响应码，6000 表示成功
message	String	响应信息
result	Object	响应数据
request_id	String	请求 ID
timestamp	String	响应时间

响应示例

成功响应

{
  "code": 6000,
  "message": "预付订单创建成功",
  "result": {
    "appId": "wxxc3xxcd4axxxe4d1",
    "timeStamp": "1766641816",
    "nonceStr": "f9e7axxaa9148a9866942319851d46d",
    "package": "prepay_id=wx25xxx3813b459xxxxxx9a20000",
    "signType": "RSA",
    "paySign": "dkU1MPGaJQMadXGtJhbbGdGg473nL7FCB..."
  },
  "request_id": "61a27b04-a1xx6-44c5-a6cc-43cae44943e3",
  "timestamp": "2023-09-25 13:50:16"
}

错误响应

{
  "code": 6015,
  "message": "下单失败"
}

支付渠道说明（channel）

渠道值	说明
WECHAT	微信
ALIPAY	支付宝
UNIONPAY	银联云闪付

支付方式说明（payWay）

方式值	说明
SDK_PAY	SDK 支付
H5_PAY	H5 支付
MINI_PROGRAM	小程序支付

分账订单标记说明（fundProcessType）

标记值	说明
DELAY_SETTLE	需要分账
REAL_TIME	不需要分账

分账说明

#

开启订单分账标记后，系统自动匹配后台分账设置中已经打开的分账商户，按照设置的
(比例/金额) * 订单进行分账

代码示例

Java 示例

import com.sofu.pay.SofuPayClient;
import com.sofu.pay.model.UnifiedOrderRequest;
import com.sofu.pay.model.UnifiedOrderResponse;

public class PaymentExample {

    private SofuPayClient client = new SofuPayClient("your_merchant_no", "your_api_key");

    public void createOrder(String userIp) {
        UnifiedOrderRequest request = new UnifiedOrderRequest();
        request.setOrderId("ORDER" + System.currentTimeMillis());
        request.setOrderAmount("100.00");
        request.setGoodsName("测试订单");
        request.setBody("订单描述");
        request.setPayWay("H5_PAY");
        request.setChannel("WECHAT");
        request.setUserIp(userIp);
        request.setNotifyUrl("https://your-domain.com/notify");
        request.setReturnUrl("https://your-domain.com/return");

        try {
            UnifiedOrderResponse response = client.unifiedOrder(request);
            if (response.getCode() == 6000) {
                System.out.println("支付链接：" + response.getResult().getPayUrl());
                System.out.println("二维码：" + response.getResult().getQrCode());
            } else {
                System.out.println("创建订单失败：" + response.getMessage());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

PHP 示例

<?php
require_once 'vendor/autoload.php';

use Sofu\Pay\SofuPayClient;

$client = new SofuPayClient('your_merchant_no', 'your_api_key');

$params = [
    'orderId' => 'ORDER' . time(),
    'orderAmount' => '100.00',
    'goodsName' => '测试订单',
    'body' => '订单描述',
    'payWay' => 'H5_PAY',
    'channel' => 'ALIPAY',
    'userIp' => $_SERVER['REMOTE_ADDR'],
    'notifyUrl' => 'https://your-domain.com/notify',
    'returnUrl' => 'https://your-domain.com/return'
];

try {
    $response = $client->unifiedOrder($params);
    if ($response['code'] === 6000) {
        echo "支付链接：" . $response['result']['payUrl'] . "\n";
        echo "二维码：" . $response['result']['qrCode'] . "\n";
    } else {
        echo "创建订单失败：" . $response['message'] . "\n";
    }
} catch (Exception $e) {
    echo "异常：" . $e->getMessage() . "\n";
}
?>

注意事项

重要提醒

1. 订单号唯一性：商户订单号必须在商户端保持唯一，重复的订单号会返回已存在的订单信息
2. 金额格式：订单金额必须为正数，格式为字符串，精确到小数点后两位
3. 异步通知：必须正确处理异步通知，确保订单状态的准确性
4. 订单有效期：订单创建后默认 30 分钟有效，过期后需重新创建
5. 回调地址：notify_url 必须为外网可访问的 HTTP/HTTPS 地址

相关接口

• 订单查询 - 查询订单支付状态
• 申请退款 - 对已支付订单发起退款
• 退款查询 - 查询退款状态