代收接口（Collection）

接口概览

代收接口用于商户向用户发起收款请求。支持菲律宾（PHP）的 GCash、Bank、Maya、QRPH 等支付方式。

接口	方法	路径	说明
代收下单	POST	/api/alliesPay/order	创建代收订单，返回支付链接
订单查询	POST	/api/alliesPay/query	根据商户订单号查询订单状态
余额查询	POST	/api/alliesPay/queryBalance	查询商户钱包余额
回调通知	POST	商户配置的 notifyUrl	支付成功后服务端主动通知商户

请求格式

• Content-Type: application/json
• 请求方式: POST
• 请求体: JSON 格式

签名机制

支持两种签名方式，通过请求参数 signType 指定，默认 RSA。

重要

• sign 和 signType 两个字段本身 不参与签名计算
• 不传 signType 时默认使用 RSA
• 响应签名方式与请求一致

RSA 签名（默认）

1. 提取除 sign、signType 外的所有非空参数
2. 按参数名 ASCII 字典序 排序
3. 拼接成 key1=value1&key2=value2... 格式（不拼接 &key=secretKey）
4. 使用 RSA 私钥（SHA256WithRSA）签名
5. Base64 编码后作为 sign 字段值

MD5 签名

1. 提取除 sign、signType 外的所有非空参数
2. 按参数名 ASCII 字典序 排序
3. 拼接成 key1=value1&key2=value2... 格式
4. 末尾拼接 &key=secretKey
   • 其中 secretKey = MD5(alliesCode + ":" + alliesSecret)
5. MD5 加密后转大写

PHP 签名示例

<?php
// 生成 secretKey（仅 MD5 签名需要）
function calcSecretKey($alliesCode, $alliesSecret) {
    return strtoupper(md5($alliesCode . ':' . $alliesSecret));
}

// 构建待签名字符串
function buildSignContent($params) {
    // 移除 sign 和 signType
    unset($params['sign'], $params['signType']);
    // 移除空值
    $params = array_filter($params, function($v) {
        return $v !== null && $v !== '';
    });
    // 按键名字典序排序
    ksort($params);
    // 拼接
    $pairs = [];
    foreach ($params as $k => $v) {
        $pairs[] = $k . '=' . $v;
    }
    return implode('&', $pairs);
}

// RSA 签名（默认）
function rsaSign($params, $rsaPrivateKey) {
    $content = buildSignContent($params);
    openssl_sign($content, $signature, $rsaPrivateKey, OPENSSL_ALGO_SHA256);
    return base64_encode($signature);
}

// MD5 签名
function md5Sign($params, $alliesCode, $alliesSecret) {
    $content = buildSignContent($params);
    $secretKey = calcSecretKey($alliesCode, $alliesSecret);
    return strtoupper(md5($content . '&key=' . $secretKey));
}

Java 签名示例

// 构建待签名字符串（sign/signType 不参与）
public static String buildSignContent(Map<String, String> params) {
    Map<String, String> treeMap = new TreeMap<>();
    for (Map.Entry<String, String> entry : params.entrySet()) {
        String key = entry.getKey();
        if ("sign".equalsIgnoreCase(key) || "signType".equalsIgnoreCase(key)) continue;
        if (entry.getValue() == null || entry.getValue().isEmpty()) continue;
        treeMap.put(key, entry.getValue());
    }
    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, String> entry : treeMap.entrySet()) {
        if (sb.length() > 0) sb.append("&");
        sb.append(entry.getKey()).append("=").append(entry.getValue());
    }
    return sb.toString();
}

// RSA 签名（默认）
public static String rsaSign(Map<String, String> params, String privateKeyBase64) throws Exception {
    String content = buildSignContent(params);
    byte[] keyBytes = Base64.decodeBase64(privateKeyBase64);
    PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
    KeyFactory kf = KeyFactory.getInstance("RSA");
    PrivateKey priKey = kf.generatePrivate(spec);
    Signature signature = Signature.getInstance("SHA256WithRSA");
    signature.initSign(priKey);
    signature.update(content.getBytes(StandardCharsets.UTF_8));
    return Base64.encodeBase64String(signature.sign());
}

// MD5 签名
public static String md5Sign(Map<String, String> params, String alliesCode, String alliesSecret) {
    String content = buildSignContent(params);
    String secretKey = MD5.getMD5(alliesCode + ":" + alliesSecret, "utf-8").toUpperCase();
    return MD5.getMD5(content + "&key=" + secretKey, "utf-8").toUpperCase();
}

支付方式（paymentMethod）

paymentMethod 参数传递的是 tradeType 的数字值：

菲律宾（PHP）

tradeType	说明
31	GCash 电子钱包
32	银行卡转账
33	PayMaya 电子钱包
34	QRPH 扫码支付

泰国（THB）

tradeType	说明
1001	Your泰 通道

TIP

paymentMethod 也可以用 tradeType 字段名传递，效果相同。

接口流程

sequenceDiagram
    participant M as 商户
    participant API as API服务端
    participant CH as 支付通道

    M->>API: POST /api/alliesPay/order
    Note over M,API: JSON + 签名（RSA默认/MD5）
    API->>API: 验签 + 参数校验
    API->>CH: 调用通道下单
    CH-->>API: 返回支付链接
    API-->>M: 返回 payUrl + sign

    Note over M: 用户完成支付

    CH->>API: 支付结果回调
    API->>M: POST notifyUrl（含 sign + rsaSign）
    M-->>API: 返回 SUCCESS

    M->>API: POST /api/alliesPay/query
    API-->>M: 返回订单状态 + sign

错误码

错误码	说明
10000	成功
1001	商户不存在
1002	商户未开启支付
1003	金额超限（低于最小/高于最大限额）
1004	通道限额不满足
1005	不支持该产品ID
1007	钱包信息不存在
1008	IP不在白名单
1010	请求参数为空
1011	签名参数sign为空
1012	签名验证失败
2004	商户不存在
2005	金额为空
2006	订单号为空
2007	回调地址为空
2008	订单号已存在
2009	支付方式为空
2011	订单创建失败
2012	订单号错误
2014	签名为空
2017	通道未授权
9999	系统错误