Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

notifyPayment

Alipay uses the notifyPayment API to send the payment result to the merchant when the payment processing reaches a final state of success. 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

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 Result object 

The payment result

Show child parameters

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.

Show child parameters

paymentCreateTime Datetime  

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 or failure. 

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 the 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. 

Show child parameters

grossSettlementAmount Amount object 

The total settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote.

Note: This field is empty when the settlement currency is the same as the transaction currency.

Show child parameters

settlementQuote Quote object 

The exchange rate between the settlement currency and transaction currency at the time of the transaction, which is provided only in the locked-in rate case. 

Note: This field is empty when the settlement currency is the same as the transaction currency.

Show child parameters

Response parameters

result Result object REQUIRED

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

Show child parameters
API Explorer

Request

Request Body (Alipay to merchant)

Response

Response Body (merchant to Alipay)

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 succeeds.
  • 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

If the value of result.resultStatus is S, the payment result notification succeeds. Alipay doesn't take any further action.

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.