Alipay+ DocsAlipay+ Docs

payAlipay+ → MPP

The pay API enables Alipay+ to send a request to the Mobile Payment Provider (MPP) to deduct refunds 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  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.

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. The MPP must regard the requests with the same paymentRequestId as repeated and process them only once. The MPP is recommended to check the consistency of the following key request parameters: paymentAmount, payToAmount, surchargeInfo, paymentMethod, and paymentPromoInfo. If any values differ from the previous request, the MPP needs to return the REPEAT_REQ_INCONSISTENT result code.
  • Maximum length: 64 characters

paymentAmount Amount  REQUIRED

The amount that Alipay+ requests to receive from the MPP. The currency of this amount must be the same as that used by Alipay+ to create the payment order. If a promotion exists, this amount does not include the promotion amount.

For more information about how does Alipay+ calculate 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  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  

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  

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  REQUIRED

The payment method that is used to collect the payment.

Show child parameters

paymentFactor PaymentFactor  REQUIRED

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

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.

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 in the paymentNotifyUrl parameter.

More information:

  • Maximum length: 2048 characters

orderLifecycleId String  REQUIRED

The unique ID that is assigned by Alipay+ to identify a lifecycle. This parameter associates a supplementary payment with the original payment.

More information:

  • Maximum length: 64 characters

paymentPromoInfo PaymentPromoInfo  

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

paymentNetworkAdditionalInfo PaymentNetworkAdditionalInfo  

Information about the payment network, such as Mastercard.

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

Return this parameter if the value of result.resultCode is SUCCESS, which means that the payment succeeds.

More information:

  • Maximum length: 64 characters

paymentTime Datetime  

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

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.

Return this parameter if the value of result.resultCode is SUCCESS, which means that the payment succeeds.

More information:

  • Maximum length: 64 characters

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

guideUrl string  

The URL that redirects users to a page predefined by the MPP, such as a page for users to perform KYC verification, recharge, or bind cards.

The MPP can decide whether it needs to return this parameter.

More information:

  • Maximum length: 2048 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 currency that Alipay+ uses to create the payment order
  • paymentAmount.value = payment amount that is requested by the ACQP from Alipay+

payToAmount

  • payToAmount.currency = the currency that is used by the MPP
  • payToAmount.value = payment amount that is requested by the ACQP from Alipay+ * 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

How to return the result

The MPP needs to return the result (specified in the result parameter) and specify some optional parameters based on the business processing result as follows:

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

Samples

Payment samples

See the API explorer for the samples. The samples assume that a Korean user purchases a 100 JPY merchandise from a Japanese merchant.

Supplemental payment samples

The following sample code shows how to initiate a supplemental payment request. 

The samples assume that a Korean user purchases a 100 JPY merchandise from a Japanese merchant.

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

Sample Code


2. The MPP returns the response to Alipay+.

Sample Code

 

Result/Error codes

CodeValueMessage
SUCCESSSSuccess
ACCESS_DENIEDFThe access is denied.
BUSINESS_NOT_SUPPORTFThe payment business is not supported.
CURRENCY_NOT_SUPPORTFThe currency is not supported.
EXPIRED_CODEFThe code is expired.
INVALID_CLIENTFThe client is invalid.
INVALID_CODEFThe code is invalid.
INVALID_CONTRACTFThe contract is invalid.
INVALID_SIGNATUREFThe signature is invalid.
INVALID_TOKENFThe access token is invalid.
KEY_NOT_FOUNDFThe key is not found.
MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
MERCHANT_NOT_REGISTEREDFThe merchant is not registered.
METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.
NO_INTERFACE_DEFFAPI is not defined.
ORDER_IS_CLOSEDFThe order is closed.
PARAM_ILLEGALFIllegal parameters exist. For example, a non-numeric input, or an invalid date.
PAYMENT_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the limit.
PAYMENT_COUNT_EXCEED_LIMITFThe number of payments exceeds the limit.
PROCESS_FAILFA general business failure occurred. Don't retry.
REGULATION_RESTRICTIONFThe payment failed due to regulatory restriction.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.
RISK_REJECTFThe request is rejected because of the risk control.
UNAVAILABLE_PAYMENT_METHODFThe payment method is unavailable.
USER_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the user payment limit.
USER_BALANCE_NOT_ENOUGHFThe user balance is not enough for the payment.
USER_KYC_NOT_QUALIFIEDFThe user is not KYC compliant.
USER_NOT_EXISTFThe user does not exist.
USER_PAYMENT_VERIFICATION_FAILEDFUser fails to pass the payment verification in the methods like OTP, PIN, and so on.
USER_STATUS_ABNORMALFThe user status is abnormal.
PAYMENT_IN_PROCESSUThe payment is being processed.
REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
UNKNOWN_EXCEPTION UAn API calling is failed, which is caused by unknown reasons.

Learn more about

Home
Get Support
Need more help?