代收回调接口

概述

代收回调接口用于接收代收订单状态变更通知。当代收订单状态发生变化时，Veloraya 会通过此接口向商户发送异步通知，确保商户能够及时了解订单状态。

测试环境如何测试回调

提供单号联系运营手动操作

回调机制

回调触发条件

• 支付成功时

回调重试机制

项目	说明
重试次数	最多重试 11 次（包含首次推送）
重试间隔	30 秒（前 6 次）
重试间隔	3 分钟（后 5 次）
超时时间	30 秒
重试条件	HTTP 状态码非 200、业务响应码非 10000、或网络异常
成功判定	HTTP 状态码 200 且 业务响应 {"code": 10000, "message": "Success"}

回调请求

请求方式

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

请求头

参数名	类型	必选	说明
Content-Type	string	Y	application/json
Timestamp	string	Y	时间戳（毫秒）
Nonce	string	Y	随机字符串（UUID，去除横线）
Signature	string	Y	签名，使用 Veloraya 私钥生成，用于验证回调的合法性

回调参数（请求体）

参数名	类型	必选	说明
merchantId	string	Y	商户 ID
orderId	string	Y	平台订单号
merchantOrderId	string	Y	商户订单号
orderStatus	string	Y	订单状态，见订单状态枚举
amount	BigDecimal	Y	订单金额
currency	string	Y	货币代码
fee	BigDecimal	Y	手续费
errorCode	string	N	错误码（失败时返回）
errorMsg	string	N	错误信息（失败时返回）
createDatetime	string	Y	订单创建时间，格式：yyyy-MM-dd HH:mm:ss
completionDatetime	string	N	订单完成时间，格式：yyyy-MM-dd HH:mm:ss

订单状态枚举

值	说明
SUCCESS	成功
FAILED	失败

回调示例

支付成功回调

{
  "amount": 500.00,
  "completionDatetime": "2025-11-19 18:04:55",
  "createDatetime": "2025-11-19 17:59:54",
  "currency": "THB",
  "fee": 55.00,
  "merchantId": "601091",
  "merchantOrderId": "ORDER5187977827671717",
  "orderId": "PAYIN1991084006458683392",
  "orderStatus": "SUCCESS",
  "accountNumber": "123476595445",
  "accountName": "ชาคริต อุปมา",
  "bankCode": "GSB",
  "orderType": "NORMAL",
  "originalOrderId": null
}

回调响应

成功响应

商户必须返回 HTTP 200 状态码，且业务响应码为 10000 表示接收成功：

{
  "code": 10000,
  "message": "Success"
}

失败响应

如果处理失败，可以返回相应的错误信息（系统会继续重试）：

{
  "code": 40001,
  "message": "处理失败"
}

注意

只有返回 {"code": 10000, "message": "Success"} 时，系统才会停止重试。其他任何响应（包括 HTTP 非 200 状态码）都会触发重试机制。

签名验证

验签步骤

1. 提取签名：从请求头中获取 Signature 字段
2. 构建签名内容：按照格式构建签名内容 timestamp={时间戳},nonce={随机数},body={请求体JSON字符串}
   • 注意：签名内容不包含 merchantId，只包含 timestamp、nonce 和 body
3. 使用 Veloraya 公钥验签：使用 Veloraya 提供的公钥验证签名
4. 参考统一验签指引：推荐直接复用 API签名规范 中的"回调验签指南"及附录 B 示例代码，实现统一的回调验签逻辑

密钥说明

• Veloraya 公钥：由 Veloraya 提供，用于验证回调通知的签名
• 签名算法：SHA256withRSA
• 编码格式：UTF-8 编码 + Base64 编码

注意事项

• 回调地址配置：回调地址需要商户在上线前主动提供给 Veloraya 负责人员，并确保地址可访问且稳定
• 签名验证：必须验证回调签名的合法性，建议直接按照 API签名规范 中的"回调验签指南"实现统一的回调验签逻辑
• 幂等性：实现幂等性处理避免重复处理，建议根据 orderId 或 merchantOrderId 进行去重
• 响应格式：必须返回 {"code": 10000, "message": "Success"} 才能停止重试，其他响应都会触发重试
• 日志记录：记录所有回调处理日志，包括请求体、响应结果、处理时间等