Callback 通知

订单有结果时，ST Pay 会向该订单建单时传入的 callback_url 发送 POST 请求。

发送时机

事件status是否发送
代收成功success发送
代收被拒绝（ST Pay 人工拒绝，或 30 分钟到期被系统拒绝）rejected发送
代收超时入账late_credited不发送，请通过查单确认，见订单状态
代付已出款paid发送
代付被拒绝rejected发送

Callback 地址

  • 每次建单（代收、代付）时通过 callback_url 传入，无需事先提供给 ST Pay。每笔订单可以不同，例如测试与生产环境各用自己的地址。
  • 建单后不能更改。自动发送与 ST Pay 手动重发都发往该订单建单时的地址。若您之后更换地址，旧订单的通知仍发往旧地址；旧地址收不到时，请通过查单确认旧订单的结果。
  • 最多 500 个字符，按原样保存，不做任何转换。
  • http 与 https 都可以，建议用 https：http 会以明文传送订单号与金额。不论哪一种，都务必验证 sign，才能防止伪造或篡改的通知。
  • 使用 https 时，网站的 HTTPS 证书（SSL/TLS 证书）必须由公开的证书颁发机构签发、在有效期内、名称与网址中的主机名相符，并且服务器要发送完整的证书链（含中间证书）。自签名证书、过期、名称不符或缺少中间证书都视为送达失败，不会重试。
  • 不能包含账号密码（user:pass@）、#、空白或非 ASCII 字符；中文域名请转换为 punycode（以 xn-- 开头）。可以带 path 与 query。
  • 主机名只能包含字母、数字、.、-（不能有下划线 _），或以 [ ] 包住的 IPv6；写了端口号时须为 1 至 65535（不能只写 :）。
  • path 与 query 中不能直接出现 |、{、}、^、"、<、>、\、反引号，% 后面必须是两位十六进制数字；这些字符请先做 URL 编码（例如 % 写成 %25）。
  • 未传、空字符串或全是空白返回 missing_parameter。
  • 不能是本机或内网地址，测试与生产环境都一样：
    • localhost，以及以 .localhost、.local、.localdomain、.internal、.intranet、.lan、.corp、.home.arpa、.private 结尾的域名，或不含「.」的主机名。
    • 私有、回环、链路本地、CGNAT、保留与文档用途、组播的 IP，例如 10.x.x.x、172.16.x.x–172.31.x.x、192.168.x.x、127.x.x.x、169.254.x.x、100.64.x.x；IPv6 只接受全球单播地址（2000::/3），其中 Teredo 2001::/32、文档用途 2001:db8::/32、6to4 2002::/16 也不接受。
    • 纯数字、十六进制、八进制或省略段数的 IP 写法，例如 2130706433、0x7f.0.0.1、0177.0.0.1、127.1。
    • 公网 IP 可以直接填写。
  • 不符合以上规则时，建单返回 invalid_callback_url（格式错误、超过 500 个字符则返回 invalid_parameter），不会建单。
  • ST Pay 每次发送前（包括手动重发）都会重新解析域名；解析失败，或解析出的任何一个地址不是公网地址，本次就不发送，视为送达失败。请确认域名可从公网解析，并且只指向公网 IP。

请求格式

  • 方法为 POST，Content-Type: application/json，请求体为 JSON 对象，所有值都是字符串。
  • 包含 sign，签名规则与 API 请求相同，使用您的 API 验证密钥（见更换密钥）。Callback 不包含 api_identity 与 timestamp。
  • ST Pay 建立连接最多等待 5 秒、等待响应最多 10 秒，且不跟随重定向（3xx）：收到 3xx 视为送达失败。请直接填写最终地址，例如 http 跳转 https、缺少末尾的 / 都可能导致重定向。
  • Callback 内容不包含 callback_url。
  • 请求头固定带 User-Agent: QPay-Callback/1.0 与 Accept: */*。Callback 地址在 Cloudflare、WAF 或其他防火墙后面时，请放行这个 User-Agent 与 POST 请求，否则可能被拦截为 403 而送达失败。

您需要返回的响应

返回 HTTP 2xx，且响应体为纯文本 ok（首尾空白字符会被忽略）。其他任何响应，包括超时、非 2xx、响应体不是 ok，都视为送达失败。

HTTP/1.1 200 OK
Content-Type: text/plain

ok

Callback 不会自动重试

每笔订单只会自动发送一次。送达失败时，只有 ST Pay 工作人员能手动重发，重发时一律发往该订单建单时传入的 callback_url。因此：

  • 请不要只依赖 Callback。对于长时间没有结果的订单，请定期查单确认。
  • 同一笔订单可能收到多次 Callback（手动重发），请以 order_no 加 status 做幂等处理，已处理过的通知直接返回 ok。
  • Callback 送达失败不影响交易结果，订单状态与余额不会因此回滚。

字段

字段代收成功代收拒绝代付已出款代付拒绝说明
order_no✓✓✓✓ST Pay 订单号
merchant_order_no✓✓✓✓商户单号
statussuccessrejectedpaidrejected订单状态
received_amount✓实收金额
fee✓✓手续费
settlement_amount✓结算金额
payable_amount✓订单金额（含尾数）
amount✓✓代付金额
finished_at✓✓✓✓完成时间
sign✓✓✓✓签名

Callback 不包含拒绝原因，如有需要请通过查单获取。

代收与代付若传入同一个 callback_url，两者的 status 都可能是 rejected，而且代收单与代付单的商户单号可以相同。请以建单时获取的 order_no 匹配订单；如果要用商户单号匹配，请让代收与代付使用不会重复的单号，例如添加不同的前缀。

处理建议

  1. 解析 JSON，用收到的全部字段（sign 除外）重新计算签名并比对。不要只挑选本文档列出的字段，日后可能会新增字段。
  2. 签名不一致则丢弃，不要更新订单。
  3. 以 order_no 找到您的订单；已处理过相同结果时直接返回 ok。
  4. 更新订单后返回 ok。耗时的后续处理（发货、通知会员等）请放到后台异步执行，避免超过 10 秒。
  5. 代收成功请以 received_amount（实收金额，或扣除手续费后的 settlement_amount）入账，不要用建单时的金额。实收金额与您预期的金额不同时，请转人工确认，不要自动入账。
  6. 订单已是终态（success、paid、rejected）后，又收到较晚到达、状态不同的通知时，不要回退订单状态；请记录下来转人工，有疑义以查单结果为准。

示例

以下签名均是用示例密钥计算的实际值。

代收成功
{
  "order_no": "C202610131000051230000",
  "merchant_order_no": "MO20261013-0001",
  "status": "success",
  "received_amount": "1000.37",
  "fee": "25.00",
  "settlement_amount": "975.37",
  "finished_at": "2026-10-13 10:12:30",
  "sign": "49d9d35c3b3a97a55fe60976a331d36913b0d3cd9b82e840e0315c445653d207"
}

代收成功示例的待签名字符串：

fee=25.00&finished_at=2026-10-13 10:12:30&merchant_order_no=MO20261013-0001&order_no=C202610131000051230000&received_amount=1000.37&settlement_amount=975.37&status=success