代付回调接口

概述

代付回调接口用于接收代付订单状态变更通知。当代付订单状态发生变化时，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	失败（包含拒绝状态）

回调示例

付款成功回调

{
  "merchantId": "MERCHANT_001",
  "orderId": "FP202312010002",
  "merchantOrderId": "PAYOUT20231201001",
  "orderStatus": "SUCCESS",
  "amount": 500.00,
  "currency": "USD",
  "fee": 5.00,
  "errorCode": null,
  "errorMsg": null,
  "createDatetime": "2023-12-01 10:00:00",
  "completionDatetime": "2023-12-01 10:05:00"
}

付款失败回调

{
  "amount": 115.10,
  "completionDatetime": "2025-11-19 18:19:56",
  "createDatetime": "2025-11-19 18:14:47",
  "currency": "THB",
  "errorCode": "4005",
  "errorMsg": "Channel timeout, please retry later",
  "merchantId": "601091",
  "merchantOrderId": "Order86271446",
  "orderId": "PAYOUT1991087751074574336",
  "orderStatus": "FAILED"
}

回调响应

成功响应

商户必须返回 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 编码

业务处理

订单状态处理

商户需要根据不同的订单状态进行相应的业务处理：

• SUCCESS：更新订单状态为付款成功，记录到账时间
• FAILED：更新订单状态为付款失败，释放冻结资金

错误处理

常见错误

• 网络超时：回调请求超时
• 服务器错误：商户服务器返回 5xx 错误
• 业务错误：商户业务逻辑处理失败
• 签名错误：签名验证失败

错误处理建议

• 日志记录：记录所有回调请求和响应
• 异常处理：妥善处理各种异常情况
• 监控告警：设置监控告警机制
• 人工干预：对于无法自动处理的情况，提供人工干预机制

注意事项

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