苹果支付代收接口文档

苹果支付代收接口文档

简介

作者苹果支付
版本v1.0.0
hosthttps://api2.youmipay.sbs
接口格式JSON 请求，JSON 响应
字符集UTF-8

签名规则

签名算法MD5 小写
公共参数mchId、reqTime、sign
签名字段除 sign 外的非空字段按字段名 ASCII 升序拼接为 k=v&k2=v2，末尾追加 &key=商户密钥 后计算 MD5 小写。
请求时间reqTime 为毫秒级时间戳，默认允许与服务器时间相差 5 分钟。
密钥机器人或商户后台展示的“密钥”，不要参与请求明文字段，只用于生成签名。

代收下单接口

请求方式POST
接口地址https://api2.youmipay.sbs/api/pay/collect/create
Content-Typeapplication/json

请求参数

mchId商户号，必填
wayCode通道编码，必填
outTradeNo商户订单号，必填，同一商户唯一
amount订单金额，必填，单位分，例如 1000 表示 10.00 元
currencyCode币种，可选，默认 CNY
notifyUrl商户异步通知地址，必填
subject商品标题，可选
body商品描述，可选
clientIp客户端IP，可选
reqTime毫秒级时间戳，必填
sign签名，必填

请求示例

{
  "mchId": "85798673",
  "wayCode": "QIANHE_8002",
  "outTradeNo": "C202605040001",
  "amount": 1000,
  "currencyCode": "CNY",
  "notifyUrl": "https://merchant.example.com/pay/notify",
  "subject": "order",
  "body": "order",
  "clientIp": "127.0.0.1",
  "reqTime": 1777891200000,
  "sign": "签名值"
}

签名示例

amount=1000&body=order&clientIp=127.0.0.1¤cyCode=CNY&mchId=85798673¬ifyUrl=https://merchant.example.com/pay/notify&outTradeNo=C202605040001&reqTime=1777891200000&subject=order&wayCode=QIANHE_8002&key=商户密钥
sign = md5(上述字符串).toLowerCase()

响应示例

{
  "code": 0,
  "message": null,
  "data": {
    "duplicate": false,
    "id": 10001,
    "platformOrderNo": "C17778912001234",
    "orderStatus": 0,
    "payUrl": null,
    "channelErrorMessage": null
  },
  "sign": "响应签名"
}

代收查询接口

请求方式GET
接口地址https://api2.youmipay.sbs/api/pay/collect/query

请求参数

mchId商户号，必填
outTradeNo商户订单号，与 platform_order_no 二选一
platform_order_no平台订单号，与 outTradeNo 二选一
reqTime毫秒级时间戳，必填
sign签名，必填

请求示例

GET /api/pay/collect/query?mchId=85798673&outTradeNo=C202605040001&reqTime=1777891200000&sign=签名值

签名示例

mchId=85798673&outTradeNo=C202605040001&reqTime=1777891200000&key=商户密钥
sign = md5(上述字符串).toLowerCase()

响应示例

{
  "code": 0,
  "message": null,
  "data": {
    "platformOrderNo": "C17778912001234",
    "merchantOrderNo": "C202605040001",
    "amount": 10.000000,
    "currencyCode": "CNY",
    "orderStatus": 1,
    "payUrl": "https://pay.example.com/order/xxx"
  },
  "sign": "响应签名"
}

代收回调通知

通知方式POST
触发时机平台收到三方通道支付成功回调并将代收订单更新为成功后，异步请求该订单的商户回调地址。
通知地址代收下单时传入的 notifyUrl；如果订单未配置，则使用商户后台配置的默认回调地址。
Content-Typeapplication/json
业务签名通知 Body 内包含 sign 字段，商户按通知参数签名规则验签。
兼容签名头平台同时发送 X-Plat-Signature，用于兼容旧版按 HTTP Body 原文验签的接入。
成功响应HTTP 状态码为 200，响应 Body 包含 success、ok 或 OK。建议直接返回 OK。
重试规则通知失败会异步重试，最多通知 3 次；前两次失败后约 60 秒、300 秒后重试。
注意事项平台发送的是标准化订单通知，不透传三方通道原始回调参数；商户应按 platformOrderNo 或 merchantOrderNo 做幂等处理。

通知参数

bizType业务类型，代收固定为 collect
mchId商户号
platformOrderNo平台订单号
outTradeNo商户订单号，即下单时的 outTradeNo
merchantOrderNo商户订单号，与 outTradeNo 相同，兼容旧字段
transactionId通道交易流水号；如果通道未返回，则使用平台订单号
amount订单金额，单位分，例如 1000 表示 10.00 元
amountYuan订单金额，单位元，保留 2 位小数
currencyCode币种，例如 CNY
orderStatus订单状态：0 待支付，1 支付成功，2 支付失败，3 已关闭，4 已失效
tradeState交易状态，代收成功通知为 SUCCESS
returnCode业务结果码，00 表示成功
successTime订单成功时间，格式 yyyy-MM-dd HH:mm:ss
notifyTime本次通知发起时间，格式 yyyy-MM-dd HH:mm:ss
sign业务签名，不参与签名

通知示例

POST https://merchant.example.com/pay/notify
Content-Type: application/json
X-Plat-Signature: 2f4b6f0d0a0f0d0a0f0d0a0f0d0a0f0d

{
  "bizType": "collect",
  "mchId": "85798673",
  "platformOrderNo": "C17778912001234",
  "outTradeNo": "C202605040001",
  "merchantOrderNo": "C202605040001",
  "transactionId": "T202605040001",
  "amount": "1000",
  "amountYuan": "10.00",
  "currencyCode": "CNY",
  "orderStatus": "1",
  "tradeState": "SUCCESS",
  "returnCode": "00",
  "successTime": "2026-05-14 12:30:20",
  "notifyTime": "2026-05-14 12:30:21",
  "sign": "签名值"
}

通知签名规则

签名算法MD5 小写
签名字段除 sign 外的非空通知字段，按字段名 ASCII 升序拼接为 k=v&k2=v2。
密钥优先使用商户后台配置的回调密钥；未配置时使用商户 API 密钥。
验签方式在待签名字符串末尾追加 &key=密钥 后计算 MD5 小写，并与 Body 中 sign 比对。

验签示例

amount=1000&amountYuan=10.00&bizType=collect&currencyCode=CNY&mchId=85798673&merchantOrderNo=C202605040001&notifyTime=2026-05-14 12:30:21&orderStatus=1&outTradeNo=C202605040001&platformOrderNo=C17778912001234&returnCode=00&successTime=2026-05-14 12:30:20&tradeState=SUCCESS&transactionId=T202605040001&key=商户回调密钥
sign = md5(上述字符串).toLowerCase()

商户响应示例

OK