# Receive payment notification

Alipay+ calls the [**notifyPayment**](../api_acq_tile/notify_payment) API to notify the Acquiring Service Provider(ACQP) of the payment result when a payment reaches a final state of success or failure.

After receiving the payment notification, the ACQP needs to notify the merchant of the result and send a response to Alipay+ synchronously.

The following steps illustrate how you (the ACQP) receive the payment notification from Alipay+ and handle the notification.

# Step 1: Receive the payment notification

## 1\. Provide the notification URL

To receive the payment notification from Alipay+, you need to provide the URL for receiving the notification in one of the following ways:

-   Specify the _paymentNotifyUrl_ parameter in the **pay** API.
-   Edit the Notification URL in the **Applications > Settings** section in [Alipay+ Developer Center](https://developers.alipayplus.com/open/console/developer/app/list?_route=SG), as shown in the image below.

![image](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1755742331805-e087df3a-a249-4291-adda-3b5bd005a5bc.webp)

Figure 1. Configure the payment notification URL in Alipay+ Developer Center

> **Note**:If you specify the payment notification URL in both ways, the value specified in the **pay** API takes precedence.

## 2\. Receive the notification

After specifying the notification URL, you can receive payment notifications from Alipay+. Once the transaction reaches a final state of success or failure, Alipay+ instantly sends you an asynchronous request with the payment result.

When receiving the notification, you need to take the following things into consideration:

-   The request is sent in raw JSON, with the _Content-Type_ request header specified as `application/json`. Ensure that you can access the HTTP body accordingly.
-   When waiting for the payment notification, you need to call the [**inquiryPayment**](../api_acq_tile/inquiry_payment) API to inquire about the payment result simultaneously. This is to ensure you get the payment result if the notification is not returned timely because of network or system problems. For more information about the collaboration between these two APIs, see [Collaboration between the notifyPayment and inquiryPayment APIs](https://docs.alipayplus.com/alipayplus/alipayplus/integration_auto_debit_acq_tile/obtain_payment_results.md#zNHTs).

### Sample

The following sample shows the request header and request body of the payment notification from Alipay+.

**Request from Alipay+ to the ACQP**

-   Request header that contains the signature added by Alipay+:

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

-   Request body that indicates a successful payment:

```plaintext
{
 "acquirerId": "1111088000000000002",
 "pspId":"1022172000000000001",
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentRequestId":"pay_1089760038715669_102775745075669",
 "paymentId":"20200101234567890134567",
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "customerId":"1235678",
 "walletBrandName":"KAKAOPAY"
}
```

-   Request body that indicates a failed payment:

```plaintext
{
"acquirerId":"1022165000000000001",
"customerId":"210220900020254424845",
"paymentAmount": {
"currency":"THB",
"value":"565900"
 },
"paymentId":"2021032919074101000220016046283",
"paymentRequestId":"2021032989031300002162325476274",
"paymentResult": {
"resultCode":"PROCESS_FAIL",
"resultMessage":"General business failure. No retry.",
"resultStatus":"F"
 },
"paymentTime":"2021-03-29T11:00:52+08:00",
"pspId":"2021226300000000"
}
```

# Step 2: Handle the payment notification

After receiving a payment notification from Alipay+, you need to complete the following steps:

1.  **Verify the notification request**: to check whether the payment notification is sent by Alipay+.
2.  **Acknowledge the notification with the response**: to let Alipay+ know that you have already received the notification.

## 1\. Verify the notification request

The notification request that Alipay+ sends to you is signed. You need to verify the request in terms of the signature and the request content:

1.  Validate the signature that is contained in the notification request header to confirm whether the notification is sent by Alipay+. For more information about how to validate a signature, see [Handle a request](https://docs.alipayplus.com/alipayplus/alipayplus/api_acq_tile/signature.md#ms1aG).
2.  Verify whether the values of the _paymentAmount_ and _paymentRequestId_ parameters in the notification are correct. For example, whether the value of the _paymentAmount_ parameter equals the payment amount that you have calculated for this order.

## 2\. Acknowledge the notification with the required response

After verifying the signature and confirming that the notification is fromAlipay+, regardless of the payment status, you need to send a response to Alipay+ to acknowledge the notification.

When constructing the response, you need to ensure the following things are completed:

-   Specify the parameter _result.resultStatus_ as `S` and the parameter result.resultCode as `SUCCESS` to indicate that you have received the notification request successfully.
-   Sign the response by following the steps illustrated in [Sign a response](https://docs.alipayplus.com/alipayplus/alipayplus/api_acq_tile/signature.md#quhBD).

If Alipay+ does not receive the required response (_result.resultStatus_ = `S` and _result_._resultCode_ \= `SUCCESS`), Alipay+ will resend the asynchronous notifications within 24 hours 22 minutes for up to 7 times until the correct response is received. The sending intervals are 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

> **Note**: Your response to the **notifyPayment** API request can only indicate whether you have received the payment result notification, and cannot change the order status. If the payment fails due to some business reasons (such as risk control validation failure), you must first accept the payment notification by returning `S` to Alipay+, and then call the [**cancelPayment**](../api_acq_tile/cancel_payment) API to cancel the payment.

### Sample

The following sample shows the response header and response body that you need to return to Alipay+.

**Response from the ACQP to Alipay+**

-   Response header that contains the signature generated by the ACQP:

```plaintext
"Content-Type": "application/json",
"response-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%2f4B65"
```

-   Response body that indicates the ACQP has successfully received Alipay+ notification:

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

# Related links

For more information about how to use the **notifiyPayment** API (such as the field description), see the [**notifyPayment**](../api_acq_tile/notify_payment) API.