Alipay+ DocsAlipay+ Docs

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.

image.png

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+:
copy
"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:
copy
{
 "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:
copy
{
"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.
    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 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 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.

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, returningFto 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 returningSto Alipay+, and then call the cancelPayment 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:
copy
"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:
copy
{
 "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 notifyPayment.