notifyPayment
Alipay uses notifyPayment to send the payment result to the merchant when the payment processing reaches a final state of success or failure. Merchants promote merchant-side transactions based on the payment result.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is 20, set it as "20".
- If the data type of a field is Boolean and its value is true, set it as "true".
Request parameters
notifyType String REQUIRED
Type of the payment status notification. The valid value is:
PAYMENT_RESULT: Indicates that the notification is about the payment result.PAYMENT_PENDING: Indicates that the user has completed the payment. The merchant needs to wait for the final payment result.
result Result object REQUIRED
Details about the payment result, such as payment status, result code, and result message.
paymentRequestId String REQUIRED
The unique ID that is assigned by a merchant to identify a payment request.
More information about this field
- Maximum length: 64 characters
paymentId String REQUIRED
The unique ID that is assigned by Alipay to identify a payment. A one-to-one correspondence between paymentId and paymentRequestId exists.
More information about this field
- Maximum length: 64 characters
paymentAmount Amount object REQUIRED
The payment amount that the merchant requests to receive in the order currency.
paymentCreateTime Datetime REQUIRED
The date and time when the payment is created.
More information about this field
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
paymentTime Datetime
The date and time when the payment reaches a final state of success.
Note: This field is returned only when the payment reaches a final state of success (the value of result.resultStatus is S).
More information about this field
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
pspCustomerInfo PspCustomerInfo object
Information about the customer of Alipay+ Mobile Payment Provider (Alipay+ MPP).
Note: This field is returned when the Alipay+ MPP can provide the related information.
customsDeclarationAmount Amount object
The total amount for customs declaration.
Note: This field is returned only when the payment succeeds and the wallet is AlipayCN.
grossSettlementAmount Amount object
The value of this field equals to transaction amount multiplied by the value of settlementQuote. This field is returned when the currency exchange is predetermined and the exchange rate is locked at the time of transaction.
settlementQuote Quote object
The exchange rate between the settlement currency and payment currency. This field is returned when grossSettlementAmount is returned.
Response parameters
result Result object REQUIRED
A fixed value, which is sent to Alipay to acknowledge that the notification is received.
Request
Response
More information
This section provides additional information about the key parameter. See the following parameter for details:
- paymentTime: The successful execution time of this payment by Alipay, that is, the date and time when the payment reaches a final state of success. This value is used as the start time of the subsequent cancellable and refundable time. For example, if the refundable time is 6 months, the final time to accept the refund is paymentTime plus 6 months.
Result process logic
Send the following message with fixed values to Alipay after receiving the notification, to acknowledge that the notification from Alipay is received:
If no such message is returned to Alipay due to operation issues or network issues, Alipay will send the notification again and again until the required message is returned by the merchant. Resending of the notification will be performed within 24 hours after the first notification is sent. The notification will be resent up to eight times, with an interval of 0s, 2m, 10m, 10m, 1h, 2h, 6h, and 15h.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | The payment is successful, no further action is needed. |
| ACCESS_DENIED | F | Access is denied. | Contact Alipay Technical Support for detailed reasons. |
| API_INVALID | F | The API name or API call format is used incorrectly. | Check whether the API name, HTTP method, or request format is correct when sending the request. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Contact Alipay Technical Support for detailed reasons. |
| INVALID_ACCESS_TOKEN | F | The access token is expired, revoked, or does not exist. | Check whether the accessToken is expired, revoked, or does not exist. Re-sign the contract and re-initiate the authorization signing process. |
| INVALID_CONTRACT | F | The parameter values in the contract do not match those in the current transaction. | Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Alipay Technical Support to troubleshoot the issue. |
| INVALID_MERCHANT_STATUS | F | The merchant status is abnormal because restrictions exist. | Contact Alipay Technical Support for detailed reasons. |
| INVALID_SIGNATURE | F | The signature is not validated. The private key used to sign a request does not match the public key of Alipay Developer Center. | Check whether the private key used to sign a request matches the public key of Alipay Developer Center. The following signature references are useful:
|
| KEY_NOT_FOUND | F | The private key or public key of Alipay or the merchant is not found. | Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center. |
| MERCHANT_KYB_NOT_QUALIFIED | F | The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction. | Contact Alipay Technical Support for detailed reasons. |
| MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration interface. Contact Alipay Technical Support if failed to call the registration interface. |
| NO_INTERFACE_DEF | F | API is not defined. | Check whether the URL is correct. Please refer to the endpoint in the API documentation. |
| NO_PAY_OPTIONS | F | The currency is not supported for the transaction. | Check whether the currency is supported by the wallet, or check whether the wallet and currency are consistent with the contract. Contact Alipay Technical Support for detailed reasons. |
| ORDER_IS_CLOSED | F | The request you initiated has the same paymentRequestId as that of the existed transaction, which is closed. | Use a new paymentRequestId to initiate the payment again. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount is greater than the maximum amount allowed by the contract or wallet. | Check whether the payment amount exceeds the limit or use a lower amount and try again. Contact Alipay technical support to know the specific limitation. |
| PAYMENT_COUNT_EXCEED_LIMIT | F | The maximum number of payments exceeds the limit that is specified by the wallet. | Contact Alipay Technical Support to know the specific limitation. |
| PAYMENT_NOT_QUALIFIED | F | The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Auto Debit payment, or is forbidden to make a payment. | Contact Alipay Technical Support for detailed reasons. |
| PROCESS_FAIL | F | A general business failure occurred. | Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue. |
| RISK_REJECT | F | The request is rejected because of the risk control. | Prompt the user that the request is rejected because the risk control failed. |
| SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Alipay Technical Support for more details. |
| USER_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the user payment limit. | Create a new payment by using an amount less than or equal to the account's available balance, or contact Alipay Technical Support. |
| USER_BALANCE_NOT_ENOUGH | F | The payment cannot be completed because the user balance in the corresponding payment method is not enough. | Please top up the account or choose other payment methods. |
| USER_KYC_NOT_QUALIFIED | F | The payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information). | Complete the KYC verification first. |
| USER_PAYMENT_VERIFICATION_FAILED | F | The user is restricted from payment on the wallet side. | Contact Alipay Technical Support to know the specific reasons. |
| USER_STATUS_ABNORMAL | F | The user status is abnormal on the wallet side. | Contact Alipay Technical Support to know the specific reasons. |