payAlipay+ → MPP

In the User-presented Mode Payment and Auto Debit scenarios, the pay API is used by Alipay+ to send a request to the Mobile Payment Provider (MPP) to deduct funds from the user's MPP account.

Note:

In the following sections, Mobile Payment Provider (MPP) is also known as Payment Service Provider (PSP). For example, the pspId parameter specifies the ID that identifies an MPP.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Note:

1. Set the data type of each parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:

If the data type of a parameter is Integer and its value is 20, set it as "20".
If the data type of a parameter is Boolean and its value is true, set it as "true".

2. For optional parameters that are not required in your case, you can take one of the following actions:

Exclude the parameters from the request body.
Set the parameter values as null (without the double quotation marks).

Do NOT leave the optional parameters empty by setting their values as ""; otherwise, an error might occur.

Request parameters

acquirerId String REQUIRED

The unique ID that is assigned by Alipay+ to identify an ACQP.

More information:

Maximum length: 64 characters

pspId String REQUIRED

The unique ID that is assigned by Alipay+ to identify an MPP.

More information:

Maximum length: 64 characters

order Order object REQUIRED

The order details that are agreed upon by the buyer and the merchant, including the information about the buyer, the merchant, the goods, the initial order amount, and so on. The order details are displayed in purchase records and used for risk and regulatory reporting.

For different payment scenarios, the following optional child parameters are also specified by Alipay+ apart from the required child parameters:

For the User-presented Mode Payment scenario, order.merchant.store is specified.

Show child parameters

paymentRequestId String REQUIRED

The unique ID that is assigned by Alipay+ to identify a payment order.

More information:

This field is an API idempotency field.For requests that are initiated with the same paymentRequestId, the MPP must regard the requests as repeated and process the requests only once. The MPP is recommended to check the consistency of the following key request parameters: paymentAmount, payToAmount, surchargeInfo, paymentMethod, and paymentPromoInfo. If any of their values is different from that in the previous request, the MPP needs to return the REPEAT_REQ_INCONSISTENT result code.
Maximum length: 64 characters

paymentAmount Amount object REQUIRED

The amount that Alipay+ requests to receive from the MPP. The currency of the amount is the one that Alipay+ uses to create the payment order. If a promotion exists, this amount does not include the promotion amount.

For more information about how Alipay+ calculates the different amounts involved in a payment order, see How are the different amounts calculated in the More information section of this topic.

Show child parameters

payToAmount Amount object REQUIRED

The amount that the MPP settles to Alipay+. The currency of the amount is the MPP's currency.

For more information about how Alipay+ calculates the different amounts involved in a payment order, see How are the different amounts calculated in the More information section of this topic.

Show child parameters

paymentQuote Quote object

The exchange rate between paymentAmount.currency and payToAmount.currency.

This parameter is specified by Alipay+ if payToAmount.currency is different from paymentAmount.currency.

Show child parameters

surchargeInfo SurchargeInfo object

The information about the surcharge that Alipay+ collects on behalf of the MPP after authorization by the MPP. This is a value-added service provided by Alipay+.

For more information about how Alipay+ calculates the different amounts involved in a payment order, see How are the different amounts calculated in the More information section of this topic.

This parameter is specified by Alipay+ if the value of paymentFactor.needSurcharge is true.

Show child parameters

paymentMethod PaymentMethod object REQUIRED

The payment method that is used to collect the payment.

For different payment scenarios, the following optional child parameters are also specified by Alipay+ apart from the required child parameters:

For the User-presented Mode Payment scenario,

paymentMethod.paymentMethodId is specified as the payment code that is presented by the user in the MPP app.
paymentMethod.paymentMethodMetaData.paymentCodeRegion is specified if the value of the region parameter in the getPaymentCode API is specified.

For the Auto Debit scenario, paymentMethod.paymentMethodId is specified as the access token.

Show child parameters

paymentFactor PaymentFactor object REQUIRED

Factors that impact payment-related items such as the quote price, fee, and regulatory reporting.

The MPP can identify the payment scenario based on the following child parameters:

isInStorePayment
isAgreementPayment
isPaymentEvaluation

For more information, see How to identify the payment scenarios in the More information section of this topic.

Show child parameters

paymentExpiryTime Datetime

The time after which the payment order is expired. If the payment order is not completed before the time that is specified for this parameter, Alipay+ closes the order.

This parameter is specified by Alipay+ in all payment scenarios except for when the value of the paymentFactor.isPaymentEvaluation parameter is true.

More information:

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

paymentNotifyUrl URL

The URL that is used to receive payment result notifications from the MPP.

Important: The MPP must send payment result notifications to the URL that is specified on the paymentNotifyUrl parameter.

More information:

Maximum length: 2048 characters

paymentRedirectUrl URL

The URL where the user is redirected to after the payment order is completed.

This parameter is specified by Alipay+ if the user needs to be redirected from the MPP's payment result page to a predetermined page, for example, the merchant result page.

More information:

Maximum length: 2048 characters

paymentPromoInfo PaymentPromoInfo object

The information about the promotion that is applied to the payment order, including the promotion ID, promotion type, and the saved amount after the promotion is applied.

This parameter is specified by Alipay+ if a promotion is applied to the payment order.

Show child parameters

authorizationInfo AuthorizationInfo object

The authorization information.

This parameter is specified by Alipay+ if the value of paymentFactor.isAuthorizationAndPay is true.

Show child parameters

otpVerification OtpVerification object

The information about the One-Time Password (OTP) verification.

This parameter is specified by Alipay+ in the Auto Debit scenario if OTP verification is required.

Show child parameters

passThroughInfo String

The information that is passed through by Alipay+ to the MPP. The value of this parameter is in a set of key-value pairs.

This parameter is specified by Alipay+ if the ACQP wants to pass information to the MPP.

More information:

Maximum length: 20000 characters

Response parameters

result Result object REQUIRED

The result of the business processing, including the result code, result status, and result message. For more information about how to return the result in different payment scenarios, see How to return the result in the More information section of this topic.

Show child parameters

paymentId String

The unique ID that is assigned by the MPP to identify a payment.

For the Auto Debit and User-presented Mode Payment scenarios, return this parameter if the value of result.resultCode is SUCCESS, which means that the payment succeeds.

More information:

Maximum length: 64 characters

paymentUrl URL

The URL where the user is redirected to confirm the payment.

More information:

Maximum length: 2048 characters

paymentTime Datetime

The date and time when the payment order reaches a final state.

For the Auto Debit and User-presented Mode Payment scenarios, return this parameter if the value of result.resultCode is SUCCESS, which means that the payment succeeds.

More information:

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

customerId String

The unique ID that is assigned by the MPP to identify a user.

For the Auto Debit and User-presented Mode Payment scenarios, return this parameter if the value of result.resultCode is SUCCESS, which means that the payment succeeds.

More information:

Maximum length: 64 characters

customsDeclarationAmount Amount object

The maximum amount that is to be declared by the ACQP to customs. The currency of the amount is the currency used by the MPP's user. For example, if the user uses ALIPAY_CN to pay, the currency is CNY.

For the Auto Debit and User-presented Mode Payment scenarios, return this parameter if the value of result.resultCode is SUCCESS and customs declaration is required by the MPP's local authority (for now this only includes the Chinese Mainland).

Show child parameters

passThroughInfo String

The information that is passed through by the MPP to Alipay+. The value of this parameter is in a set of key-value pairs.

Return this parameter if the MPP wants to pass information to the ACQP.

More information:

Maximum length: 20000 characters

API Explorer

Request

Request Body

Response

Response Body

More information

How are the different amounts calculated

This section introduces how are paymentAmount, payToAmount, and surchargeAmount calculated when Alipay+ calls the pay API and provides calculation cases to illustrate the process.

Note: Alipay+ calculates the values of all amounts in the smallest currency unit. For example, if the currency is HKD and the amount is $1.00, the value of the amount is set to 100; or if the currency is JPY and the amount is ￥1, the value of the amount is set to 1.

paymentAmount

paymentAmount.currency = The one that Alipay+ uses to create the payment order.
paymentAmount.value = Payment amount that is requested by the ACQP from Alipay+ - Promotion amount that is provided by Alipay+

If the promotion amount is in the MPP's currency, the promotion amount is converted to the currency that is used by the ACQP based on paymentQuote.

payToAmount

payToAmount.currency = The currency that is used by the MPP.
payToAmount.value = Payment amount that is requested by the ACQP from Alipay+ * paymentQuote - Promotion amount that is provided by Alipay+

If the promotion amount is in the currency used by the ACQP, the promotion amount is converted to the MPP's currency based on paymentQuote.

surchargeAmount

surchargeAmount.currency = The currency that is used by the MPP.
surchargeAmount.value = Payment amount that is requested by the ACQP from Alipay+ * surchargeQuote - Promotion amount that is provided by Alipay+

If the promotion amount is in the currency used by the ACQP, the promotion amount is converted to the MPP's currency based on surchargeQuote.

Calculation cases

The following two cases are provided for your reference.

Case 1

In this case, a Hong Kong user purchases a 1000 JPY merchandise from a Japanese merchant and applies a 5 JPY coupon provided by Alipay+ to the order. Besides, Alipay+ collects a surcharge on behalf of the MPP.

Known conditions

Initial order amount (paymentAmount specified by the ACQP): 1000 JPY
Instant discount: 5 JPY
Payment quote between JPY and HKD (paymentQuote): 1 JPY = 8.5614 HKD
Surcharge quote between JPY and HKD (surchargeQuote): 1 JPY = 8.9614 HKD

Calculation results

paymentAmount = 1000 JPY - 5 JPY = 995 JPY
savingsAmount = 5 JPY * 8.5614 = 43 HKD
payToAmount = 1000 JPY * 8.5614 - 5 JPY* 8.5614 = 8518 HKD
surchargeAmount = 1000 JPY * 8.9614 - 5 JPY* 8.9614 = 8916 HKD

Case 2

In this case, a Hong Kong user purchases a 10000 USD merchandise from an American merchant and applies a 500 HKD coupon provided by Alipay+ to the order. No surcharge is collected.

Known conditions

Initial order amount (paymentAmount specified by the ACQP): 10000 USD
Instant discount: 500 HKD
Payment quote between USD and HKD (paymentQuote): 1 USD = 9.3307 HKD

Calculation results

paymentAmount = 10000 USD - 500 HKD / 9.3307 = 9946 USD
savingsAmount = 500 HKD
payToAmount = 10000 USD * 9.3307 - 500 HKD = 92807 HKD

How to identify the payment scenarios

The following table shows how the key payment factors are specified by Alipay+ for each payment scenario. The MPP can identify which payment scenario is in process according to the configuration of the paymentFactor parameter.

Payment scenario	isInStorePayment	isAgreementPayment	isPaymentEvaluation
User-presented Mode Payment	`TRUE`
Auto Debit		`TRUE`
Payment Evaluation for Auto Debit		`TRUE`	`TRUE`

How to return the result

For different payment scenarios, according to the business processing result, the MPP needs to return the corresponding result (specified on the result parameter) and specify some optional parameters.

For the Auto Debit and User-presented Mode Payment scenarios:

If the payment succeeds, set the value of result.resultStatus to S and specify the following optional parameters: paymentId, paymentTime, and customerId.
If the payment fails, set the value of result.resultStatus to F.
If the payment result is unknown, set the value of result.resultStatus to U and the value of result.resultCode to UNKNOWN_EXCEPTION.

For the Auto Debit payment evaluation scenario:

If the payment evaluation result is successful, set the value of result.resultStatus to S.
If the payment evaluation result is unsuccessful, set the value of result.resultStatus to F.
If the payment evaluation result is unknown, set the value of result.resultStatus to U and the value of result.resultCode to UNKNOWN_EXCEPTION.

Samples

The samples in the API explorer show how Alipay+ specifies request parameters and how the MPP returns response parameters for the User-presented Mode Payment scenario (without promotion). The following section shows more samples for different payment scenarios.

Samples without promotion

User-presented Mode Payment

See the API explorer for the samples. The samples assume that a Korean user purchases a 100 JPY merchandise from a Japanese merchant. The merchant scans the user-presented payment code in the MPP app to initiate a cross-border payment.

Auto Debit

The following samples assume that a merchant obtains the authorization to debit a user account. When the user purchases a 100 JPY merchandise at the merchant, the merchant uses the access token to debit the user account.

1. Alipay+ sends a request to the MPP.

Sample Code

2. The MPP returns the response to Alipay+.

Sample Code

Payment evaluation for Auto Debit

In the Auto Debit scenario, the merchant sometimes needs to evaluate whether the user account has sufficient balance to make the payment before initiating a payment request.

The following samples illustrate the payment evaluation message flow:

1. Alipay+ sends a payment evaluation request to the MPP.

Sample Code

2. The MPP returns the result to Alipay+.

Sample Code

Samples with promotion

Alipay+ allows you to specify the promotion information in a payment request for the User-presented Mode Payment and Auto Debit scenarios.

The following sample code takes the User-presented Mode Payment scenario as an example and shows how to initiate a payment request along with promotion information.

The samples assume that a Korean user purchases a 100 JPY merchandise from a Japanese merchant. The user applies a 10 JPY off 100 JPY coupon provided by Alipay+ and thus actually pays 90 JPY. The payment promotion information is specified for the paymentPromoInfo parameter.

1. Alipay+ sends a payment request to the MPP.

Sample Code

2. The MPP returns the response to Alipay+.

Sample Code

Result/Error codes

Code	Value	Message
SUCCESS	S	Success
ACCESS_DENIED	F	The access is denied.
BUSINESS_NOT_SUPPORT	F	The payment business is not supported.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.
EXPIRED_CODE	F	The code is expired.
INVALID_CLIENT	F	The client is invalid.
INVALID_CODE	F	The code is invalid.
INVALID_CONTRACT	F	The contract is invalid.
INVALID_SIGNATURE	F	The signature is invalid.
INVALID_TOKEN	F	The access token is invalid.
KEY_NOT_FOUND	F	The key is not found.
MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.
NO_INTERFACE_DEF	F	API is not defined.
ORDER_IS_CLOSED	F	The order is closed.
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
PAYMENT_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the limit.
PAYMENT_COUNT_EXCEED_LIMIT	F	The number of payments exceeds the limit.
PROCESS_FAIL	F	A general business failure occurred. Don't retry.
REGULATION_RESTRICTION	F	The payment failed due to regulatory restriction.
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.
RISK_REJECT	F	The request is rejected because of the risk control.
UNAVAILABLE_PAYMENT_METHOD	F	The payment method is unavailable.
USER_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the user payment limit.
USER_BALANCE_NOT_ENOUGH	F	The user balance is not enough for the payment.
USER_KYC_NOT_QUALIFIED	F	The user is not KYC compliant.
USER_NOT_EXIST	F	The user does not exist.
USER_PAYMENT_VERIFICATION_FAILED	F	User fails to pass the payment verification in the methods like OTP, PIN, and so on.
USER_STATUS_ABNORMAL	F	The user status is abnormal.
PAYMENT_IN_PROCESS	U	The payment is being processed.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.
UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.

payAlipay+ → MPP

Structure​

Request parameters

acquirerId String REQUIRED

pspId String REQUIRED

order Order object REQUIRED

paymentRequestId String REQUIRED

paymentAmount Amount object REQUIRED

payToAmount Amount object REQUIRED

paymentQuote Quote object

surchargeInfo SurchargeInfo object

paymentMethod PaymentMethod object REQUIRED

paymentFactor PaymentFactor object REQUIRED

paymentExpiryTime Datetime

paymentNotifyUrl URL

paymentRedirectUrl URL

paymentPromoInfo PaymentPromoInfo object

authorizationInfo AuthorizationInfo object

otpVerification OtpVerification object

passThroughInfo String

Response parameters

result Result object REQUIRED

paymentId String

paymentUrl URL

paymentTime Datetime

customerId String

customsDeclarationAmount Amount object

passThroughInfo String

Request

Response

More information

How are the different amounts calculated

paymentAmount

payToAmount

surchargeAmount

Calculation cases

Case 1

Case 2

How to identify the payment scenarios

How to return the result

Samples

Samples without promotion

Samples with promotion

Result/Error codes

Structure