> ## 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.

# Asynchronous Notification

> Callback notification parameters for collection, payout, and collection link orders.

**Brief Description:**

* **When the customer's collection is successful or failed, we will push the order status. If the first notification fails, it will retry every 5 minutes, up to 5 times.**

**URL:** `Your provided URL`, **Please configure it in HaiPay's backend or pass it in the request parameters.**

<Tip>
  Strongly Recommended

  > To ensure the extensibility and compatibility of the interface, please follow the callback parameters reception method outlined below:
  >
  > 1. **Do not** declare a specific POJO object to receive callback parameters.
  > 2. **Must** use a generic data structure (like JSONObject, Map, etc.) to parse parameters.
  > 3. This design ensures that if we later extend the callback fields, it will not affect your signature verification logic.
  >
  > **Reason**: Keeping a loosely coupled design can prevent signature verification failures due to the addition or removal of fields.
</Tip>

**Collection Callback Parameters:**

| Parameter        | Type    | Description                                                                                                                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| appId            | Long    | Business ID                                                                                                                                                                                      |
| currency         | String  | Currency                                                                                                                                                                                         |
| orderId          | String  | Merchant order ID                                                                                                                                                                                |
| orderNo          | String  | Platform order ID                                                                                                                                                                                |
| amount           | String  | Amount collected this time                                                                                                                                                                       |
| fee              | String  | Fee amount                                                                                                                                                                                       |
| status           | Integer | Status (2: Success(Final), 3: Failure(Final), 4: Partial Collection(Final), 5: Excess Collection(Final)).                                                                                        |
| payTime          | String  | Payment success time (present when status=2, 4, 5) (Local time), format: yyyy-MM-dd HH:mm:ss                                                                                                     |
| errorMsg         | String  | Payment failure reason (present when status=3)                                                                                                                                                   |
| originalCurrency | String  | Original order currency, may be empty, only present when currency conversion is involved                                                                                                         |
| originalAmount   | String  | Original order amount, may be empty, only present when currency conversion is involved                                                                                                           |
| inBankCode       | String  | Payment method used by the user, refer to each region's documentation, may be empty                                                                                                              |
| bankNo           | String  | Receiving account, may be empty                                                                                                                                                                  |
| description      | String  | Payment note, may be empty                                                                                                                                                                       |
| cardNo           | String  | Payment card number, credit card payments typically display the first six and last four digits, while ApplePay and GooglePay show only the last four digits, which may be blank                  |
| tokenID          | String  | Payment token, for MIT mode transactions, may be empty                                                                                                                                           |
| name             | String  | User name, may be empty                                                                                                                                                                          |
| email            | String  | User email, present for MIT mode transactions                                                                                                                                                    |
| expMonth         | String  | Payment card expiration month, may be empty                                                                                                                                                      |
| expYear          | String  | Payment card expiration year, may be empty                                                                                                                                                       |
| ip               | String  | User IP, may be empty                                                                                                                                                                            |
| is3DS            | String  | Whether 3DS payment is required, true indicates yes, false indicates no, but it only represents whether the bank recommends 3DS payment, not whether 3DS payment was actually used, may be empty |
| sign             | String  | Signature, <font color="red"> (Must use the business secret key for the currency for verification)</font>                                                                                        |

**Payout Callback Parameters:**

| Parameter | Type    | Description                                                                                           |
| --------- | ------- | ----------------------------------------------------------------------------------------------------- |
| appId     | Long    | Business ID                                                                                           |
| currency  | String  | Currency                                                                                              |
| orderId   | String  | Merchant order ID                                                                                     |
| orderNo   | String  | Platform order ID                                                                                     |
| amount    | String  | Amount collected this time                                                                            |
| fee       | String  | Fee amount                                                                                            |
| status    | Integer | Status (2: Success(Final), 3: Failure(Final))                                                         |
| payTime   | String  | Payment success time (present when status=2)(Local time), format: yyyy-MM-dd HH:mm:ss                 |
| errorMsg  | String  | Payment failure reason (present when status=3)                                                        |
| hash      | String  | Transaction hash                                                                                      |
| sign      | String  | Signature, <font color="red"> (Must use the business secret for the currency for verification)</font> |

**Collection Link Order Callback Parameters:**

| Parameter        | Type    | Description                                                                                               |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| appId            | Long    | Business ID                                                                                               |
| currency         | String  | Currency                                                                                                  |
| orderId          | String  | Merchant order ID                                                                                         |
| orderNo          | String  | Platform order ID                                                                                         |
| amount           | String  | Amount collected this time                                                                                |
| fee              | String  | Fee amount                                                                                                |
| status           | Integer | Status (2: Success(Final), 3: Failure(Final), 4: Partial Collection(Final), 5: Excess Collection(Final)). |
| payTime          | String  | Payment success time (present when status=2, 4, 5), format: yyyy-MM-dd HH:mm:ss                           |
| errorMsg         | String  | Payment failure reason (present when status=3)                                                            |
| originalCurrency | String  | Original order currency, may be empty, only present when currency conversion is involved                  |
| originalAmount   | String  | Original order amount, may be empty, only present when currency conversion is involved                    |
| inBankCode       | String  | Payment method used by the user, refer to each region's documentation, may be empty                       |
| bankNo           | String  | Receiving account, may be empty                                                                           |
| description      | String  | Payment note, may be empty                                                                                |
| cardNo           | String  | Last four digits of the payment card number , may be empty                                                |
| createTime       | String  | Order creation time (Local time), format: yyyy-MM-dd HH:mm:ss                                             |
| linkNo           | String  | Collection link number                                                                                    |
| linkName         | String  | Collection link name                                                                                      |
| agentId          | Long    | Agent ID (empty if there's no agent)                                                                      |
| email            | String  | Payer's email (from the collection link page, random email if not filled)                                 |
| name             | String  | Payer's nickname (from the collection link page)                                                          |
| subject          | String  | Note (filled in the collection link page, randomly generated if not filled)                               |
| sign             | String  | Signature, <font color="red"> (Must use the business secret for the currency for verification)</font>     |

**Note:**

After receiving the webhook event, please return HTTP Status Code 200 when the business process succeeds to indicate that the notification was received successfully. Otherwise, the system will consider the notification failed and retry up to 5 times.

## Related Topics

* [Common API Overview](/docs/en/api/version2/CommonApi)
* [HaiPay API Description and Common Rules](/docs/en/guide/api_description_guide)