Receive payment notification
Alipay+ calls the notifyPayment API to notify the Acquiring Partner(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 accordingly.
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 Integration Settings section in Alipay+ Developer Center, as shown in the image below.
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 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.
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+:
- Request body that indicates a successful payment:
- Request body that indicates a failed payment:
Step 2: Handle the payment notification
After receiving a payment notification from Alipay+, you need to complete the following steps:
- Verify the notification request: to check whether the payment notification is sent by Alipay+.
- 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:
- 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.
- 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 from Alipay+, 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
Sand the parameter result.resultCode as
SUCCESSto indicate that you have received the notification request successfully.
- Sign the response by following the steps illustrated in Sign a response.
If the required response is not received,Alipay+ resends 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: The notifyPayment API cannot accept the failure that is caused by business reasons, for example, risk control validation failure. Therefore, returning
Fto Alipay+ cannot change the order status, and Alipay+ will only resend the notification requests. If the payment fails due to some business reasons, you first need to accept the payment notification by returning
Sto Alipay+, and then call the cancelPayment API to cancel the payment.
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:
- Response body that indicates the ACQP has successfully received Alipay+ notification:
For more information about how to use the notifiyPayment API (such as the field description), see notifyPayment.