快速开始

欢迎使用嗖付聚合支付 API！本指南将帮助您快速完成 API 接入，开始使用我们的聚合支付服务。

接入准备

1. 获取 API 密钥

在接入 API 之前，您需要：

1. 联系嗖付商务人员开通商户账号
2. 获取以下关键信息：
   • 商户号 (merchantNo)：您的唯一商户标识
   • 应用标识 (appKey)：您的应用标识
   • 商户密钥 (secretKey)：用于签名验证的密钥
   • 接口地址：API 服务器地址

注意

请妥善保管您的 API 密钥，切勿泄露给第三方。建议定期更换密钥以确保安全。

2. 配置白名单

为了确保接口调用的安全性，需要将您的服务器 IP 地址添加到白名单：

1. 提供您的服务器公网 IP 地址
2. 联系技术支持人员配置 IP 白名单
3. 配置完成后即可正常调用 API 接口

请求格式

请求方式

• HTTP 方法：POST
• Content-Type：application/json
• 字符编码：UTF-8

认证与请求头

所有 API 请求必须在 HTTP Header 中携带以下认证信息：

Header 名称	是否必填	描述
X-App-Key	是	应用标识 appKey
X-Secret-Key	是	商户密钥 secretKey，用于签名和身份校验

提示

为了保证安全性，请仅在服务端使用并妥善保管 X-Secret-Key，不要在前端或公开环境中暴露。

签名规则

所有接口在发送前必须根据请求体中的参数计算签名，并将结果放在请求 body 的 sign 字段中一同提交。建议按照以下步骤生成签名：

1. 将本次请求的所有业务参数和公共参数（不包含 sign 字段本身）放入同一个参数集合中。
2. 按参数名升序（字典序）对参数集合进行排序。
3. 使用 key1=value1&key2=value2... 的形式拼接成字符串（等价于后端的 URL 查询字符串拼接，需使用 UTF-8 编码）。
4. 以商户密钥 secretKey 作为密钥，对上一步得到的字符串执行 HMAC-SHA256 运算。
5. 将计算结果的十六进制字符串作为 sign 字段的值，放入请求 body 中，随其它参数一并发送。

服务端会使用相同的规则对请求体参数重新计算签名，并与传入的 sign 字段进行比对，以完成请求合法性校验。

请求示例

curl -X POST \
  https://api.sofu.com/api/order/unified-order \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your_app_key" \
  -H "X-Secret-Key: your_secret_key" \
  -d '{
    "mch_id": "your_mch_id",
    "out_trade_no": "20231119001",
    "total_amount": "100.00",
    "subject": "测试订单",
    "timestamp": "1700380800",
    "nonce_str": "1234567890",
    "sign": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
  }'

{
  "mch_id": "your_mch_id",
  "out_trade_no": "20231119001",
  "total_amount": "100.00",
  "subject": "测试订单",
  "timestamp": "1700380800",
  "nonce_str": "1234567890",
  "sign": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
}

上述示例中的 sign 字段即为按照“签名规则”小节计算得到的签名字符串，每次调用接口都必须在请求体中携带该字段。

响应格式

成功响应

{
  "code": 6000,
  "message": "预付订单创建成功",
  "result": {
    // 具体业务数据，如预支付信息等
  }
}

错误响应

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

状态码说明

状态码	说明
6060	缺少密钥或应用程序标识
6061	身份验证失败
6062	商户被冻结或未注册
403	禁止访问/未设置白名单
6006	参数缺失
6012	参数不合法
6000	返回成功
6015	操作失败，请联系客服处理

SDK 下载

为了简化接入流程，我们提供了多种语言的 SDK：

Java SDK

<dependency>
    <groupId>com.sofu</groupId>
    <artifactId>sofu-pay-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

使用示例：

SofuPayClient client = new SofuPayClient("your_mch_id", "your_api_key");
UnifiedOrderRequest request = new UnifiedOrderRequest();
request.setOutTradeNo("20231119001");
request.setTotalAmount("100.00");
request.setSubject("测试订单");

UnifiedOrderResponse response = client.unifiedOrder(request);

PHP SDK

composer require sofu/pay-sdk

使用示例：

use Sofu\Pay\SofuPayClient;

$client = new SofuPayClient('your_mch_id', 'your_api_key');
$response = $client->unifiedOrder([
    'out_trade_no' => '20231119001',
    'total_amount' => '100.00',
    'subject' => '测试订单'
]);

Node.js SDK

npm install @sofu/pay-sdk

使用示例：

const SofuPay = require("@sofu/pay-sdk");

const client = new SofuPay({
  mchId: "your_mch_id",
  apiKey: "your_api_key",
});

const result = await client.unifiedOrder({
  outTradeNo: "20231119001",
  totalAmount: "100.00",
  subject: "测试订单",
});

Python SDK

pip install sofu-pay-sdk

使用示例：

from sofu_pay import SofuPayClient

client = SofuPayClient('your_mch_id', 'your_api_key')
response = client.unified_order({
    'out_trade_no': '20231119001',
    'total_amount': '100.00',
    'subject': '测试订单'
})

环境配置

沙箱环境

在正式接入前，建议先在沙箱环境进行测试：

• 沙箱地址：https://sandbox-api.sofu.com
• 测试商户号：test_mch_001
• 测试密钥：test_api_key_123456

生产环境

• 生产地址：https://api.sofu.com
• 正式商户号：由商务人员提供
• 正式密钥：由商务人员提供

常见问题

Q: 签名验证失败怎么办？

A: 请检查以下几点：

1. 参数是否按照字典序排序
2. 空值参数是否已过滤
3. API 密钥是否正确
4. 字符编码是否为 UTF-8

Q: 调用接口提示 IP 不在白名单？

A: 请联系技术支持，提供您的服务器公网 IP 地址进行白名单配置。

Q: 订单重复提交怎么处理？

A: 使用相同的out_trade_no调用统一下单接口，系统会返回已存在的订单信息，不会重复创建订单。

技术支持

如果您在接入过程中遇到任何问题，可以通过以下方式联系我们：

• 技术支持热线：400-000-0000
• 技术支持邮箱：tech-support@sofu.com
• 工作时间：7x24 小时
• QQ 技术群：123456789

下一步

完成基础配置后，建议按以下顺序进行：

1. 查看 API 总览 - 浏览所有可用接口
2. 配置异步通知 - 设置异步通知处理
3. 测试支付流程 - 在沙箱环境测试完整支付流程
4. 集成到生产 - 切换到生产环境进行上线

推荐阅读顺序

1. API 接口总览 - 了解所有可用接口
2. 聚合支付统一下单 - 核心支付接口
3. 异步通知处理 - 支付结果处理
4. 订单查询 - 订单状态确认