# Notifications

> Learn about how to integrate notification APIs provided by APO.

Learn about how to integrate notification APIs provided by APO.

## Features

The supported products and description of these notifications are shown in the following table:

| **Notification APIs** | **One-time Payments** | **User-presented Mode Payment** | **Order Code Payment** | **Entry Code Payment** | **Description** |
| --- | --- | --- | --- | --- | --- |
| [**notifyPayment**](paymentrn_online) | ✔️ | ✔️ | ✔️ | ✔️ | Send the payment result to you when the payment processing reaches a final state of success or failure. The parameter _result.resultStatus_ indicates the payment result. - `S`: Indicates the payment is successful when _notifyType_ is `PAYMENT_RESULT`; indicates the payment is being processed when _notifyType_ is `PAYMENT_PENDING`. - `F`: Indicates the payment is failed. |
| [**notifyCapture**](notify_capture) | ✔️ | ❌ | ❌ | ❌ | Send the capture result to you when the capture processing reaches a final state of success or failure. The parameter _result.resultStatus_ indicates the capture result. - `S`: indicates a successful capture. - `F`: indicates a failed capture. |
| [**notifyVaulting**](notify_vaulting) | ❌ | ❌ | ❌ | ❌ | Send the asset vaulting result information to you when asset binding reaches the final state of success or failure. The _result.resultStatus_ parameter indicates the result of vaulting: - `S`: indicates a successful asset binding. - `F`: indicates a failed asset binding. |
| [**notifyDispute**](https://docs.antom.com/ac/apo/notify_dispute.md) | ✔️ | ❌ | ❌ | ❌ | APO uses this API to send the dispute notifications to you. The _disputeNotificationType_ parameter indicates the types of dispute notifications. - `DISPUTE_CREATED`: indicates that a dispute occurs. - `DISPUTE_JUDGED`: indicates that the dispute is judged. |
| [**notifyRefund**](https://docs.antom.com/ac/apo/notify_refund.md) | ✔️ | ❌ | ❌ | ❌ | APO uses this API to send the refund result to the merchant when the refund processing reaches a final state of success or failure. The _refundStatus_ parameter indicates the result of refund: - `SUCCESS`: Indicates that the refund succeeded. - `FAIL`: Indicates that the refund failed. |

Table 1. Capabilities of notifications

## Configure receiving address

You can configure the receiving address of each notification via an interface or in Antom Developer Center. If you use both ways to specify the address, the URL configured in the API takes precedence.

| **Notification APIs** | **Configure in API** | **Configure in APO Dashboard** | **Others** |
| --- | --- | --- | --- |
| [**notifyPayment**](paymentrn_online) | Specify the _paymentNotifyUrl_ field in the [**pay**](https://docs.antom.com/ac/apo/pay.md) or [**createPaymentSession**](https://docs.antom.com/ac/apo/payment_session.md) API. | Set the webhook URL on [APO Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify) through **Developer > Notification Address** | N/A. |
| [**notifyCapture**](notify_capture) | Specify the _paymentNotifyUrl_ field in the [**pay**](https://docs.antom.com/ac/apo/pay.md) or [**createPaymentSession**](https://docs.antom.com/ac/apo/payment_session.md) API. | Set the webhook URL on [APO Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify) through **Developer > Notification Address** | If you set the capture notification URL both in the API and APO Dashboard, the one set in APO Dashboard takes precedence. |
| [**notifyValuting**](notify_vaulting) | Specify the _vaultingNotificationUrl_ field in the [**create****Valuting****Session**](https://docs.antom.com/ac/apo/vaulting_session.md) API. | Set the webhook URL on [APO Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify) through **Developer > Notification Address** | N/A. |
| [**notifyDispute**](https://docs.antom.com/ac/apo_zh-cn/notify_dispute.md) | N/A. | Set the webhook URL on [APO Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify) through **Developer > Notification Address** | N/A. |
| [**notifyRefund**](https://docs.antom.com/ac/apo_zh-cn/notify_refund.md) | Specify the _paymentNotifyUrl_ field in the [**refund**](https://docs.antom.com/ac/apo/refund_online.md) API**.** | Set the webhook URL on [APO Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify) through **Developer > Notification Address** | N/A. |

Table 2. Receiving address configuration

## Process the notification

### 1\. Verify the signature

The result notification from APO is signed by APO. It is recommended to verify the signature and check whether the notification is sent by APO. You can verify the signature by yourself or by using APO SDK.

To verify the signature by yourself, see [Sign a request and validate the signature](https://docs.antom.com/ac/ams/digital_signature.md#x6Le8). To use APO SDK, specify the values for the corresponding parameters in the _SignatureTool.verify_ method provided in [SDKs](https://docs.antom.com/ac/sdks/server_sdks.md):

```java
boolean isSuccess = SignatureTool.verify(httpMethod, path, clientId, rspTimeStr, rspBody, signature, alipayPublicKey);
```

The value of _signature_ is from the notification header. The following example shows a notification header:

```json
"Content-Type": "application/json", "Request-Time": "2019-07-12T12:08:56+05:30", "client-id": "T_111222333", "Signature": "algorithm=RSA256,keyVersion=1,signature=jTOHqknjk%2fnDjEn8lfg%2beNODdoh2eHGJV%2blvrKaDwP782WxJ7ro49giqUu23MUM8sFVVNvhg32qHS3sd4O6uf5kAVLqztqNOPJFZcjw141EVi1vrs%2bIB4vU0%2fK%2f8z2GyWUByh2lHOWFsp%2b5QKCclXp%2bjacYqWYUur5IVbuebR1LoD5IiJ7u7J9qYriFxodkxmIAJYJyJs7mks2FWHh2YePLj3K%2f4B65idy7RBKqY1NN1XcvqnbQmlfCH8CIv75bg%2fr9sGmPE5a%2bYgL8N9Q41buGwMSq1IcNsbceMbyPhw5Z5HnJ7tPz12fvdSi0cEicPikDthQ2EQFmtpntXcAc%2fHA%3d%3d"
```

### 2\. Return a receipt acknowledgment message

After verifying the signature and confirming that the notification is from APO, you need to return a receipt acknowledgment message to APO to inform APO of a successful receipt of the notification. **No digital signature is required for the process of returning a receipt acknowledgment message.**

The example below shows the header of the message you send to APO:

```json
"Content-Type": "application/json", "response-time": "2019-07-12T12:08:56+05:30", "client-id": "T_111222333",
```

The example below shows the body of the message you send to APO:

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}
```

If no such message is returned to APO due to operation or network issues, APO will automatically resend the asynchronous notification within 24 hours for up to seven times or until the correct response is received. The sending intervals are as follows: 0 sec, 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

> **Note**: Record the processed notifications received from APO for a payment request, and properly handle the idempotency to avoid processing a single request multiple times.