> ## Documentation Index
> Fetch the complete documentation index at: https://doc.haipay.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 异步通知

> 代收、代付、收款链接的异步回调通知参数说明。

**简要描述：**

* **当客户代收成功或失败，我方会推送订单状态，若首次通知失败，则每隔5分钟回调一次，持续5次**

**URL：`贵方提供`**，**请配置在HaiPay后台或在请求参数中传递**

<Tip title={"强烈建议"}>
  > 为保障接口的扩展性和兼容性，请遵循以下回调参数接收方式：
  >
  > 1. **禁止**声明具体POJO对象接收回调参数
  > 2. **必须**使用通用数据结构（如JSONObject、Map等）进行参数解析
  > 3. 此设计可确保后续我方扩展回调字段时，不会影响贵方的验签逻辑
  >
  > **原因**：保持松耦合设计可避免因字段增减导致的验签失败问题。
</Tip>

代收回调参数：

| 参数名              | 类型      | 说明                                                              |
| :--------------- | :------ | :-------------------------------------------------------------- |
| appId            | Long    | 业务ID                                                            |
| currency         | String  | 币种                                                              |
| orderId          | String  | 商户订单号                                                           |
| orderNo          | String  | 平台订单号                                                           |
| amount           | String  | 本次收款金额                                                          |
| fee              | String  | 手续费金额                                                           |
| status           | Integer | 状态(2成功（终态），3失败（终态），4部分收款（终态），5超额收款（终态）)；                        |
| payTime          | String  | 支付成功时间（当status=2，4，5时有值）(本地时间), 格式: yyyy-MM-dd HH:mm:ss         |
| errorMsg         | String  | 支付失败原因（当status=3时有值）                                            |
| originalCurrency | String  | 订单原始币种，可能为空，涉及汇率转换时有值                                           |
| originalAmount   | String  | 订单原始金额，可能为空，涉及汇率转换时有值                                           |
| inBankCode       | String  | 用户支付方式，可以参考每个地区的接口文档，与下单一致,可能为空                                 |
| bankNo           | String  | 收款账号，可能为空                                                       |
| description      | String  | 收款备注，可能为空                                                       |
| cardNo           | String  | 支付卡号，信用卡支付一般为前六后四，ApplePay和GooglePay只有后四位，可能为空                  |
| tokenID          | String  | 支付令牌，用于MIT模式交易，可能为空                                             |
| name             | String  | 用户姓名，可能为空                                                       |
| email            | String  | 用户邮箱，MIT模式交易时有值，可能为空                                            |
| expMonth         | String  | 支付卡号有效期月份，可能为空                                                  |
| expYear          | String  | 支付卡号有效期年份，可能为空                                                  |
| ip               | String  | 用户IP，可能为空                                                       |
| is3DS            | String  | 是否3DS支付，true表示是，false表示否，但只代表建议银行是否要求3DS支付，不表示是否实际使用了3DS支付，可能为空 |
| sign             | String  | 签名，<font color="red">（需要使用币种对应的业务密钥信息进行验签）</font>               |

代付回调参数：

| 参数名      | 类型      | 说明                                                  |
| :------- | :------ | :-------------------------------------------------- |
| appId    | Long    | 业务ID                                                |
| currency | String  | 币种                                                  |
| orderId  | String  | 商户订单号                                               |
| orderNo  | String  | 平台订单号                                               |
| amount   | String  | 本次收款金额                                              |
| fee      | String  | 手续费金额                                               |
| status   | Integer | 状态(2成功（终态），3失败（终态）)                                 |
| payTime  | String  | 支付成功时间（当status=2时有值）(本地时间), 格式: yyyy-MM-dd HH:mm:ss |
| errorMsg | String  | 支付失败原因（当status=3时有值）                                |
| hash     | String  | 交易hash                                              |
| sign     | String  | 签名，<font color="red">（需要使用币种对应的业务密钥信息进行验签）</font>   |

收款链接订单回调参数：

| 参数名              | 类型      | 说明                                                      |
| :--------------- | :------ | :------------------------------------------------------ |
| appId            | Long    | 业务ID                                                    |
| currency         | String  | 币种                                                      |
| orderId          | String  | 商户订单号                                                   |
| orderNo          | String  | 平台订单号                                                   |
| amount           | String  | 本次收款金额                                                  |
| fee              | String  | 手续费金额                                                   |
| status           | Integer | 状态(2成功（终态），3失败（终态），4部分收款（终态），5超额收款（终态）)；                |
| payTime          | String  | 支付成功时间（当status=2，4，5时有值）(本地时间), 格式: yyyy-MM-dd HH:mm:ss |
| errorMsg         | String  | 支付失败原因（当status=3时有值）                                    |
| originalCurrency | String  | 订单原始币种，可能为空，涉及汇率转换时有值                                   |
| originalAmount   | String  | 订单原始金额，可能为空，涉及汇率转换时有值                                   |
| inBankCode       | String  | 用户支付方式，可以参考每个地区的接口文档，与下单一致,可能为空                         |
| bankNo           | String  | 收款账号,可能为空                                               |
| description      | String  | 收款备注,可能为空                                               |
| cardNo           | String  | 支付卡号后四位,可能为空                                            |
| createTime       | String  | 订单创建时间(本地时间), 格式: yyyy-MM-dd HH:mm:ss                   |
| linkNo           | String  | 收款链接编号                                                  |
| linkName         | String  | 收款链接名称                                                  |
| agentId          | Long    | 代理商ID(如无代理商则为空)                                         |
| email            | String  | 付款用户邮箱(收款链接页面填写,未填写为随机邮箱)                               |
| name             | String  | 付款用户昵称(收款链接页面填写)                                        |
| subject          | String  | 备注(收款链接页面填写，未填写为随机生成)                                   |
| sign             | String  | 签名，<font color="red">（需要使用币种对应的业务密钥信息进行验签）</font>       |

说明

收到回调通知后，请在业务处理成功时返回 HTTP Status Code 200，表示通知接收成功。否则系统将认为通知失败，并最多重试通知 5 次。

## 相关主题

* [公共接口概览](/docs/zh/api/version2/CommonApi)
* [HaiPay 接口说明与公共规则](/docs/zh/guide/api_description_guide)