Receive payment notification

Alipay+ calls the notifyPayment API to notify the ACQP about the payment result when the payment reaches a final state of success or failure. After that, the ACQP needs to notify the merchant of the result accordingly.

Step 1: Receive the notification

For a successful payment transaction, an HTTP POST is fired once the transaction is successfully completed. The HTTP request is sent in the raw JSON, of which the Content-Type request header is specified as application/json. Ensure that your server side can access the HTTP body accordingly.

For more information about what the request header, the successful payment notification request body, and the failed payment notification body look like, see the samples below.

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+:

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: Verify the signature

The notification request that Alipay+ sends to the ACQP is signed. The merchant needs to verify the signature to confirm whether the notification is sent from Alipay+. For how to validate a signature, see Validate a signature.

After the notification is delivered successfully, verify whether the values of the paymentAmount and paymentRequestId parameters are as you expect (for example, the amount that you have calculated for the order that you are going to ship).

Step 3: Acknowledge the notification with the required response

After receiving the notification, no matter whether the order processing succeeds or fails, your server side must return a receipt acknowledgment message to Alipay+. Meanwhile, the required response must also be signed.

For more information about what the header and body of the response look like, see the samples below.

Note: The notifyPayment API cannot accept the failure that is caused by business reasons, for example, risk control validation failure. If the payment fails due to some business reasons, the ACQP must firstly accept the payment notification and return SUCCESS to Alipay+, and then call the cancelPayment API to perform refunds.

Retrial mechanism

After receiving the notification, your server side must respond with an HTTP status code of 200 and send an acknowledgement with result.resultStatus of S to indicate that your server side received and processed the call. If your server side responds with other status code, or acknowledge with other values, Alipay+ takes the notification delivery as unsuccessful. Therefore, Alipay+ will retry the notification sending.

The interval between two adjacent times is: 2m, 10m, 10m, 1h, 2h, 6h, 15h.
7 times - up to 24 hours 22 minutes

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"
 }
}

More information

For more information about how to use the notifiyPayment API (such as the field description), see notifyPayment.