notifyPayment

2021-07-20 17:12

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.

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 ResultOptional

The payment result

resultCode String(64)Required

Result code

resultStatus StringRequired

Result status. Possible values are:

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

resultMessage String(256)Optional

Result message

paymentRequestId String(64)Required

The unique ID that is assigned by a merchant to identify a payment request. Special characters are not supported.

paymentId String(64)Optional

The unique ID that is assigned by Alipay to identify a payment. A one-to-one correspondence between paymentId and paymentRequestId exists.

paymentAmount AmountRequired

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

currency String(3)Required

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

value String(16)Required

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.

paymentCreateTime DatetimeOptional

The date and time when the payment is created, which follows the ISO 8601 standard.

paymentTime DatetimeOptional

The date and time when the payment reaches a final state of success or failure, which follows the ISO 8601 standard.

pspCustomerInfo PspCustomerInfoOptional

Information about the customer of payment method provider (PMP).

Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

pspName String(64)Optional

The name of PSP.

Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

pspCustomerId String(64)Optional

The customer ID of PMP.

Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

displayCustomerId String(64)Optional

The customer ID used for display. For example, loginId

grossSettlementAmount AmountOptional

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

Note:

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

currency String(3)Required

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

value String(16)Required

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.

settlementQuote QuoteOptional

The exchange rate between the settlement currency and transaction currency at the time of 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.

quoteId String(64)Optional

The unique ID to identify a quote.

quoteCurrencyPair String(16)Required

Pair of currency exchange rate

quotePrice Decimal(20)Required

Rate quotation, decimal point that follows market quotation

quoteStartTime DatetimeOptional

Effective time of the exchange rate, which follows the ISO 8601 standard

quoteExpiryTime DatetimeOptional

Expiration time of the exchange rate, which follows the ISO 8601 standard

guaranteed BooleanOptional

Guaranteed exchange rate is available for payment

Response parameters

result ResultRequired

The request result, which contains information related to the request result, such as status and error codes.

resultCode String(64)Required

Result code

resultStatus StringRequired

Result status. Possible values are:

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

resultMessage String(256)Optional

Result message

More information

This section provides additional information about certain 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 actions.

Result/Error codes

Code	Value	Message
SUCCESS	S	Success
UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.
USER_KYC_NOT_QUALIFIED	F	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).

Request/Response Code

Request Body (Alipay to merchant)

Request parameters

Response Body (merchant to Alipay)

Body content