商户代收代付接口文档

版本：v1.0
适用对象：商户系统对接代收、代付、订单查询、余额查询、异步通知。

1. 接入说明

1.1 请求地址

pay-1 当前接口域名：

https://aspay-api.sdrgs.eu.cc

接口均使用 POST 请求，参数以 application/x-www-form-urlencoded 或 multipart/form-data 提交。

1.2 商户参数

1.3 签名规则

所有商户接口均使用 MD5 签名。

签名步骤：

1. 取所有参与签名的请求参数，排除 sign。
2. 排除值为空的字段，例如 ""、null、None。
3. 按参数名 ASCII 升序排序。
4. 拼接为 key=value&key=value。
5. 末尾追加 &key={mc_key}。
6. 对最终字符串做 MD5，并转为大写 32 位字符串。

示例：

amount=100.00&callback=https://merchant.example.com/return&gateway=1001&mer_id=10001&notify=https://merchant.example.com/notify&order_id=M202607020001&key=YOUR_MC_KEY

签名结果：

sign = MD5(上面字符串).upper()

Python 示例：

import hashlib

def make_sign(params: dict, mc_key: str) -> str:
    items = []
    for key in sorted(params.keys()):
        if key == "sign":
            continue
        value = params[key]
        if value is None or value == "":
            continue
        items.append(f"{key}={value}")
    sign_str = "&".join(items) + f"&key={mc_key.strip()}"
    return hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()

1.4 通用响应格式

成功或失败均返回 JSON。

{
  "code": 0,
  "data": null,
  "message": ""
}

code = 0 表示请求受理成功。业务最终结果以订单查询或异步通知为准。

2. 代收下单

2.1 接口

POST https://aspay-api.sdrgs.eu.cc/pay

2.2 请求参数

注意：remark、realname、player_ip、user_id 不参与代收下单签名。

2.3 请求示例

curl -X POST "https://aspay-api.sdrgs.eu.cc/pay" \
  -d "mer_id=10001" \
  -d "gateway=1001" \
  -d "amount=100.00" \
  -d "callback=https://merchant.example.com/return" \
  -d "notify=https://merchant.example.com/notify/ds" \
  -d "order_id=M202607020001" \
  -d "sign=SIGN_VALUE"

2.4 成功响应

{
  "code": 0,
  "data": "https://pay.example.com/order/xxxxx",
  "message": "下单成功",
  "upi": "example@upi",
  "amount": "100.00",
  "token": "xxxxx",
  "order_code": "S20260702000001"
}

字段说明：

3. 代付下单

3.1 接口

POST https://aspay-api.sdrgs.eu.cc/pay/df

3.2 请求参数

注意：

• 代付接口会校验商户代付 IP 白名单。
• amount 不允许非 0 小数，例如 100.50 会失败。
• 商户余额需大于等于 amount + 手续费。

3.3 请求示例

curl -X POST "https://aspay-api.sdrgs.eu.cc/pay/df" \
  -d "mer_id=10001" \
  -d "order_id=DF202607020001" \
  -d "gateway=2001" \
  -d "amount=1000" \
  -d "account=1234567890" \
  -d "user=RAHUL SHARMA" \
  -d "bank_code=HDFC0000001" \
  -d "bank=HDFC BANK" \
  -d "notify=https://merchant.example.com/notify/df" \
  -d "sign=SIGN_VALUE"

3.4 成功响应

{
  "code": 0,
  "massage": "下单成功",
  "order_code": "F20260702000001",
  "amount": "1000"
}

说明：字段名实际返回为 massage，不是 message。

4. 代收订单查询

4.1 接口

POST https://aspay-api.sdrgs.eu.cc/status/ds

4.2 请求参数

4.3 成功响应

{
  "code": 0,
  "message": "",
  "data": {
    "order_id": "M202607020001",
    "order_code": "S20260702000001",
    "amount": "100.00",
    "realpay": "98.00",
    "utr": "123456789012",
    "upi": "example@upi",
    "time_create": "2026-07-02 12:00:00",
    "time_finish": "2026-07-02 12:03:00",
    "status": 0
  }
}

商户侧状态：

5. 代付订单查询

5.1 接口

POST https://aspay-api.sdrgs.eu.cc/status/df

5.2 请求参数

5.3 成功响应

{
  "code": 0,
  "message": "",
  "data": {
    "order_id": "DF202607020001",
    "order_code": "F20260702000001",
    "amount": "1000.00",
    "realpay": "1010.00",
    "utr": "123456789012",
    "time_create": "2026-07-02 12:00:00",
    "time_finish": "2026-07-02 12:05:00",
    "status": 0,
    "user": "RAHUL SHARMA",
    "account": "1234567890",
    "bank": "HDFC BANK"
  }
}

商户侧状态：

6. 余额查询

6.1 接口

POST https://aspay-api.sdrgs.eu.cc/balance

6.2 请求参数

6.3 成功响应

{
  "code": 0,
  "message": "",
  "data": {
    "available": "10000.00",
    "frozen": "500.00",
    "balance": "10500.00"
  }
}

字段说明：

7. 代收 UTR 补单

该接口用于商户主动提交代收订单的 UTR。提交成功并匹配到账单后，平台会完成代收订单并触发代收异步通知。

7.1 接口

POST https://aspay-api.sdrgs.eu.cc/pay/ds/utr

7.2 请求参数

签名字段包含 mer_id、order_id、utr，按通用签名规则生成。

7.3 请求示例

curl -X POST "https://aspay-api.sdrgs.eu.cc/pay/ds/utr" \
  -d "mer_id=10001" \
  -d "order_id=M202607020001" \
  -d "utr=123456789012" \
  -d "sign=SIGN_VALUE"

7.4 响应说明

8. 异步通知

平台会向商户传入的 notify 地址发起 POST 表单通知。

商户收到通知后，必须直接响应小写：

ok

若未返回 ok，平台会在订单更新时间后的约 5 分钟内重试通知。

8.1 代收成功通知

POST 商户代收 notify 地址

通知参数：

代收通知签名字段默认包含：

amount, mer_id, order_id, realpay, status

remark 和 utr 在当前通知实现中追加于签名之后，不参与默认签名。

8.2 代付结果通知

POST 商户代付 notify 地址

通知参数：

代付通知签名字段默认包含：

amount, mer_id, order_id, realpay, reason, status

utr 在当前通知实现中追加于签名之后，不参与默认签名。

8.3 通知验签示例

商户收到通知后，按同样的 MD5 规则验签。

示例：

notify_params = {
    "mer_id": "10001",
    "order_id": "M202607020001",
    "status": "ok",
    "amount": "100.00",
    "realpay": "98.00",
    "sign": "SIGN_FROM_PLATFORM",
}

assert make_sign(notify_params, "YOUR_MC_KEY") == notify_params["sign"]

9. 错误码

10. 对接建议

• 商户订单号 order_id 必须全局唯一，避免重复下单。
• 下单成功只代表平台已受理，最终状态以异步通知或查询接口为准。
• 商户通知接口需保证幂等，同一订单可能收到多次通知。
• 商户通知接口成功处理后必须返回纯文本 ok，不要返回 JSON。
• 金额字段建议按字符串处理，避免浮点精度问题。
• 商户应保存平台订单号 order_code，方便排查和人工对账。