If the paymentNotifyUrl field is specified in the pay API or configured in Antom Dashboard, you will receive the payment notification and be notified of the payment result. After receiving the payment notification, you must take the corresponding action to process the payment notification. The payment notification follows the notifyPayment SPI specification.

Receive the payment notification

You can provide the address for receiving the payment notification to Alipay in one of the following ways:

• Specify the paymentNotifyUrl field in the pay API.
• Edit Notification URL in the Notification URL section of Antom Dashboard.

If you use both ways to specify the paymentNotifyUrl, the value specified in the pay API takes precedence. After providing the payment notification URL to Alipay in any of the above-mentioned ways, Alipay sends the user's payment result to you according to the following rules:

• If the payment succeeds, the asynchronous notification is sent to the merchant immediately.
• If the payment fails or the user does not pay, the asynchronous notification is sent to the merchant after the one-minute Alipay payment expiration time at the latest.

If no notification is received within one minute after receiving the response of the payment request, it is suggested to call the inquiryPayment API to actively inquire about the payment status. Otherwise, it might occur that the user completes the payment but no payment result is received by the merchant.

The payment notification will be received if you specify the paymentNotifyUrl field in the pay request. The example below shows a payment notification body from Alipay, notifying a successful payment:

{
 "notifyType": "PAYMENT_RESULT",
 "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
 },
 "paymentRequestId": "pay_test_1106_0002", //The ID assigned by Merchant to identify the payment transaction
 "paymentId": "20200101234567890132", //The ID assigned by Alipay to identify the payment transaction
 "paymentAmount": { //The amount of the payment order, 80 EUR
    "value": "8000",
    "currency": "EUR"
 },
 "paymentCreateTime": "2020-01-01T12:01:00+08:30", //Time when the payment transaction is created
 "paymentTime": "2020-01-01T12:01:01+08:30" //Time when the payment is completed
}

The example below shows a payment notification body from Alipay, notifying a failed payment result:

{
 "notifyType":"PAYMENT_RESULT",
 "result": {
    "resultCode":"USER_BALANCE_NOT_ENOUGH",
    "resultStatus":"F",
    "resultMessage":"user balance not enough"
 },
 "paymentRequestId":"pay_test_1106_0002", 
 "paymentId":"20200101234567890132"
}

The following fields in the notifyPayment request need to be understood correctly:

• result.resultStatus: This field indicates the payment result. Possible values include:

• S: This indicates the payment succeeded.
• F: This indicates the payment failed. The failure reason is indicated in resultCode.

• paymentCreateTime: This field indicates the time that the payment was created.
• paymentTime: This field indicates the time that the payment was completed. If the payment was failed to be paid, this field is not returned.

Process the payment notification

After receiving the payment notification, you need to take the following actions:

1. Verify the signature: to check whether the payment notification is sent by Alipay.
2. Return a receipt acknowledgment message: to let Alipay know that you have already received the notification.

1. Verify the signature

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

To verify the signature by yourself, see Sign a request and validate the signature. To use Alipay SDK, specify the values for the corresponding parameters in the SignatureTool.verify method provided in SDKs for signature verification:

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:

"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 Alipay, you need to return a receipt acknowledgment message to Alipay to inform Alipay of a successful receipt of the payment notification. No digital signature is required for the process of returning a receipt acknowledge message.

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

"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 Alipay:

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}

If no such message is returned to Alipay due to operation or network issues, Alipay 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: 0sec, 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

Notes:

• If the server-side payment success results notification from Alipay is received, it indicates that the user completed the payment successfully. However, do not rely only on the payment result page to determine whether the payment is completed successfully because the page might be forged.
• For the repeatedly received payment notifications from Alipay for one payment request, record the processed notifications and handle the idempotency properly.