Alipay+ DocsAlipay+ Docs

Notify payment result

It is recommended that the  Mobile Payment Provider (MPP) call the notifyPayment API to notify Alipay+ of the payment result when the payment processing reaches a final status of success or failure.

The following figure shows the payment result notification flow of a transaction.

image

Figure 1. The payment result notification flow of a transaction

To notify Alipay+ of the final payment result, you (the MPP) need to complete the following steps:

Step 1: Send the payment notification to Alipay+

Step 2: Receive the acknowledgment response from Alipay+

Step 1: Send the payment notification

When a payment reaches a final state of success or failure, you need to send the notification to the URL provided by Alipay+ through the notifyPayment API.

1. Receive the notification URL

You first need to receive the notification URL provided by Alipay+. This fixed URL is specified in the parameter paymentNotifyUrl in the request of the pay API.

2. Send the payment notification request

When the payment processing reaches a final status of success or failure, you must send the payment result notification to Alipay+ and pay attention to the rules below.

  • If the payment succeeds, return a paymentResult.resultStatus of S and paymentResult.resultCode of SUCCESS.
  • If the payment fails, return a paymentResult.resultStatus of F and an error code that is corresponding to a specific reason.
    • Required: If the balance of the user account is not enough, return a paymentResult.resultCode of USER_BALANCE_NOT_ENOUGH.
    • Recommended: If the user does not exist, or the user status is abnormal, return a paymentResult.resultCode of USER_NOT_EXISTor USER_STATUS_ABNORMAL.
    • Recommended: If the payment is declined for risk reasons, return a paymentResult.resultCode of RISK_REJECT.
    • Recommended: If the user's payment methods that are linked to the MPP are unavailable, return a paymentResult.resultCode of UNAVAILABLE_PAYMENT_METHOD.
    • Recommended: If the user verification fails, return a paymentResult.resultCode of USER_PAYMENT_VERIFICATION_FAILED.
    • Recommended: If the merchant verification fails, return a paymentResult.resultCode of MERCHANT_NOT_REGISTERED.
  • If the payment is cancelled, return a paymentResult.resultStatus of F and a paymentResult.resultCode of ORDER_IS_CLOSED.

Sample

Request from the MPP to Alipay+

The MPP sends a payment notification request that indicates a successful payment:

copy
{
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentRequestId":"2020010123456789****", 
 "paymentId":"202001012345678901322222", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 }, 
 "customerId":"1234567"
}

Step 2: Receive the acknowledgment response

After receiving the payment notification from the MPP, Alipay+ returns an acknowledgment response to the MPP. It is recommended that you are able to detect whether Alipay+ fails to return the response with the parameter result.resultStatus of Sand handle the response according to the instructions below.

result.resultStatus

result.resultCode

Notification status

Actions

S

SUCCESS

Notification succeeds.

N/A

F

...

Notification fails.

Take actions according to the result code (specified in the result.resultCode parameter). For more information, see Result code in the API reference for notifyPayment.

U

...

Unknown

Retry the same request as below.

  • Retry 1~2 times within 5 seconds.
  • The subsequent intervals increase consecutively. For example, 30s, 1m, 2m, ...
  • A total of 15 retries are suggested.

No result received

Unknown

Retry the same request as below.

  • Retry 1~2 times within 5 seconds.
  • The subsequent intervals increase consecutively. For example, 30s, 1m, 2m, ...
  • A total of 15 retries are suggested.

Sample

Response from Alipay+ to the MPP

The MPP receives a response that indicates Alipay+ has successfully received the 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.