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

代收回调参数：

| 参数名 | 类型 | 说明 |
| :- | :- | :- |
| 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 次。

## 相关主题

* [HaiPay 接口说明与公共规则](https://doc.haipay.net/zh/get-started/api-conventions.md)
* [配置商户密钥与 RSA 签名规则](https://doc.haipay.net/zh/get-started/configuration-and-signatures.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.