notifyPayment

Alipay uses the notifyPayment API 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 StringRequired

Payment status notification type. Valid values are:  

  • PAYMENT_RESULT: Indicates that the notification is a payment result.
  • OFFLINE_PAYMENT_CODE: Indicates that the notification is an offline payment code.
result ResultRequired

The payment result

resultCode StringRequired

Result code. Valid values are:   

  • SUCCESS: Indicates that the payment succeeded.
  • RPOCESS_FAIL: Indicates that a general business failure occurred.
  • USER_KYC_NOT_QUALIFIED: Indicates that 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). 

More information about this field:

  • Maximum length: 64 characters
resultStatus StringRequired

Result status. Valid values are:   

  • S: Indicates that the result status is successful. 
  • F: Indicates that the result status failed. 
  • U: Indicates that the result status is unknown. 
resultMessage StringOptional

Result message

More information about this field:

  • Maximum length: 256 characters
paymentRequestId StringRequired

The unique ID that is assigned by a merchant to identify a payment request. 

More information about this field:

  • Maximum length: 64 characters
paymentId StringOptional

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 AmountRequired

The payment amount that the merchant requests to receive in the order currency.

currency StringRequired

The 3-letter currency code that follows the ISO 4217 standard.

More information about this field:

  • Maximum length: 3 characters
value IntegerRequired

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

Notes: For more information about the smallest currency unit, see Currency codes for details.

More information about this field:

  • Value range: 0 - unlimited
paymentCreateTime DatetimeOptional

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:30".
paymentTime DatetimeOptional

The date and time when the payment reaches a final state of success or failure. 

More information about this field:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
pspCustomerInfo PspCustomerInfoOptional

Information about the customer of Alipay+ Mobile Payment Partner (Alipay+ MPP).

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

pspName StringOptional

The name of Alipay+ MPP.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

More information about this field:

  • Maximum length: 64 characters
pspCustomerId StringOptional

The customer ID of Alipay+ MPP.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

More information about this field:

  • Maximum length: 64 characters
displayCustomerId StringOptional

The customer ID used for display. For example, loginId.

More information about this field:

  • Maximum length: 64 characters
customsDeclarationAmount AmountOptional

The total amount for customs declaration. This field is returned only when the wallet is Alipay CN.

currency StringRequired

The 3-letter currency code that follows the ISO 4217 standard. 

More information about this field:

  • Maximum length: 3 characters
value IntegerRequired

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

Notes: For more information about the smallest currency unit, see Currency codes for details. 

More information about this field:

  • Value range: 0 - unlimited

Response parameters

result ResultRequired

The request result contains information such as status and error codes.

resultCode StringRequired

Result code

More information about this field:

  • Maximum length: 64 characters
resultStatus StringRequired

Result status. Valid values are:

  • S: Indicates that the result status is successful. 
  • F: Indicates that the result status failed. 
  • U: Indicates that the result status is unknown.
resultMessage StringOptional

Result message

More information about this field:

  • Maximum length: 256 characters

More information 

This section provides additional information about key parameters. See the following parameters for details:

  • result (in the notification request sent by Alipay)
    Payment result. If the value of result.resultStatus is S, then the payment succeeded. If the value is F, the payment failed. The value of result.resultStatus will not be U for the payment result notification.
  • paymentTime
    This field is returned only when the value of result.resultStatus is S. 
  • paymentActionForm: 
    In the in-store payment scenario, paymentCode is passed in through this field, and merchants can display the code to the customer. 

Result process logic

The merchant needs to send SUCCESS to Alipay after receiving the notification. If no asynchronous notification is returned to Alipay as required or due to network issues, Alipay will retry the notification request within 24 hours until SUCCESS is returned by the merchant. The notification request is called up to eight times, with an interval of 0s, 2m, 10m, 10m, 1h, 2h, 6h, and 15h.

Error codes

Error codes are usually classified into the following categories:

  • Common error codes: common for all online and in-store payment APIs.
  • API-specific error codes: listed in the following table.  

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The payment is successful, no further action is needed.

Request/Response Code
Request Body (Alipay to merchant)
Request parameters
A successful payment result
A failed payment result
Response Body (merchant to Alipay)
Body content