Alipay+ DocsAlipay+ Docs
APIs & SDKs

userInitiatedPayMPP → Alipay+

POST /aps/api/v1/payments/userInitiatedPay

The userInitiatedPay API is used when the user initiates a payment request by scanning an order code that is recognized by Alipay+. The Mobile Payment Provider (MPP) calls this API to send the decoding request to Alipay+.

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:

  • exclude them from the request body. 
  • set the 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

codeValue String  REQUIRED

The code value that the user scans.

More information about this field

  • This field is an API idempotency field.For requests that are initiated with the same codeValue within the code validity period, Alipay+ regards the requests as repeated and processes the requests only once. Alipay+ checks the consistency of the customerId parameter. If its value is different from that in the previous request, Alipay+ returns the REPEAT_REQ_INCONSISTENT result code.
  • Maximum length: 512 characters

customerId String  REQUIRED

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

More information about this field

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

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

More information about this field

  • Maximum length: 20000 characters

Response parameters

result Result object REQUIRED

The result of the business processing, including the result status, result code, and result message. For more information about how to handle the result of the userInitiatedPay API, see How to handle the result.

Show child parameters

acquirerId String  

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

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS, which means that the decoding succeeds.

More information about this field

  • Maximum length: 64 characters

pspId String  

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

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS, which means that the decoding succeeds.

More information about this field

  • Maximum length: 64 characters

codeType String  

The type of code that the user scans. The valid value is ORDER_CODE, which indicates an order code.

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS, which means that the decoding succeeds.

paymentRequestId String  

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

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS, which means that the decoding succeeds.

More information about this field

  • Maximum length: 64 characters

order Order object 

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.

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS, which means that the decoding succeeds.

Show child parameters

paymentFactor PaymentFactor object 

Factors that impact payment-related items such as service fee, interchange fee (also known as interpartner fee), and regulatory reporting. This parameter is used to identify the payment scenario.

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS, which means that the decoding succeeds.

  • For the Merchant-presented Mode Payment scenario, the following child parameters are returned as below: 
    • isInStorePayment: true
    • isCashierPayment: true
  • For the Cashier Payment scenario, the following child parameters are returned as below: 
    • isInStorePayment: false
    • isCashierPayment: true
Show child parameters

paymentAmount Amount object 

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.

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and the value of the codeType parameter is ORDER_CODE.

Show child parameters

payToAmount Amount object 

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

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and the value of the codeType parameter is ORDER_CODE.

Show child parameters

paymentQuote Quote object 

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

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and 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+. 

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and the value of paymentFactor.needSurcharge is true.

Show child parameters

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 about this field

  • Maximum length: 2048 characters

paymentRedirectUrl URL  

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

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and 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 about this field

  • Maximum length: 2048 characters

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 returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and the value of the paymentFactor.isPaymentEvaluation parameter is false.

More information about this field

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

authorizationInfo AuthorizationInfo object 

The authorization information.

This parameter is returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and the value of the paymentFactor.isAuthorizationAndPay parameter is true.

Show child parameters

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 returned by Alipay+ if the value of the result.resultCode parameter is SUCCESS and a promotion is applied to the payment order.

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 returned by Alipay+ if the ACQP wants to pass information to the MPP.

More information about this field

  • Maximum length: 20000 characters
API Explorer
Sample CodesRun in Sandbox

Request

URL
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+ handles the userInitiatedPay API request 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 handle the result

You might receive different results from Alipay+. Follow the instructions below to handle the result.

result.resultStatus

result.resultCode

Request status

Actions

S

SUCCESS

Decoding succeeds.

Guide the user to confirm the payment.

F

Multiple possible values exist, such as

ACCESS_DENIED,

BUSINESS_NOT_SUPPORT, etc.

Decoding fails.

Take actions according to the result code (specified on the result.resultCode parameter). For more information, see the Result code section.

U

Multiple possible values exist, such as REQUEST_TRAFFIC_EXCEED_LIMIT, UNKNOWN_EXCEPTION, etc.

Decoding is in processing.

Retry the same request.

No result received

Unknown

Retry the same request.

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

Guide the user to confirm the payment.

ACCESS_DENIEDFThe access is denied.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

BUSINESS_NOT_SUPPORTFThe payment business is not supported.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

CURRENCY_NOT_SUPPORT FThe currency is not supported.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

EXPIRED_CODEFThe code is expired.

Inform the user that the order code is expired.

INVALID_CLIENTFThe client is invalid.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

INVALID_CODEFThe code is invalid.

Inform the user that the order code is invalid.

INVALID_CONTRACTFThe contract is invalid.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

INVALID_SIGNATUREFThe signature is invalid.

Check whether the public key, signed message, and signature algorithm are as expected.

KEY_NOT_FOUNDFThe key is not found.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

Use a media type that is accepted by Alipay+.

METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

NO_INTERFACE_DEFFAPI is not defined.

Check whether the request URL is correct. Ensure that the endpoint of the called API is correct.

ORDER_IS_CLOSEDForder has been cancelled

Inform the user that the order is closed.

PARAM_ILLEGALFIllegal parameters exist. For example, a non-numeric input, or an invalid date.

Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of each API, see the Structure section of the specific API reference topic.

PROCESS_FAILFA general business failure occurred. Don't retry.

It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue.

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

Reduce the frequency of API calls.

UNKNOWN_EXCEPTIONUAn API calling is failed, which is caused by unknown reasons.

Try to recall the API.

Learn more about

Home
Get Support
Need more help?