# userInitiatedPay `POST /aps/api/v1/payments/userInitiatedPay` The **userInitiatedPay** API is used when a user initiates a payment in one of the following scenarios: - **Merchant-Presented Mode**: The user scans a QR code displayed by the merchant. - **Cashier Payment**: The user is redirected from the merchant's app or website to complete the payment. In both cases, the Mobile Payment Provider (MPP) calls this API to send the order code to Alipay+. Alipay+ then decodes the code and returns the necessary payment information. > **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: - [Request header](api_overview#3mLq0) - [Response header](api_overview#YdmVS) > **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 #### codeValue (String, REQUIRED) The code value that the user scans. More information: - Maximum length: 512 characters #### customerId (String, REQUIRED) The unique ID that is assigned by the MPP to identify a user. 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. Specify this parameter if the MPP wants to pass information to the ACQP. More information: - Maximum length: 20000 characters #### indirectMpp (IndirectMpp) Information about the indirect MPP. Specify this parameter when the payment involves an indirect MPP, for example, when the payment is processed through a special payment network. ##### indirectMppId (String, REQUIRED) The indirect MPP ID. More information: - Maximum length: 64 characters ##### indirectMppName (String) The legal name of the indirect MPP. More information: - Maximum length: 256 characters ## Response parameters #### result (Result, 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_. ##### resultCode (String, REQUIRED) The result code that indicates the detailed processing result. More information: - Maximum length: 64 characters ##### resultStatus (String, REQUIRED) The result status that indicates the processing result. Valid values are: - `S`: Successful - `F`: Failed - `U`: Unknown ##### resultMessage (String) The result message that describes the result code in detail. More information: - Maximum length: 256 characters #### 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: - 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: - 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. **Important**: The value of this parameter must be unique for each payment order. For payment orders with the same _paymentRequestId_, the MPP must regard the payment orders as repeated and process the payment orders only once. This parameter is returned by Alipay+ if the value of the _result_._resultCode_ parameter is `SUCCESS`, which means that the decoding succeeds. More information: - Maximum length: 64 characters #### order (Order) 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. ##### referenceOrderId (String, REQUIRED) The unique ID that is assigned by the merchant to identify an order. The ID is used to display the user's purchase record and to track follow-up operations, such as customer complaints and disputes. More information: - Maximum length: 64 characters ##### orderDescription (String, REQUIRED) The description of the order. More information: - Maximum length: 256 characters ##### orderAmount (Amount, REQUIRED) The initial order amount that is used by the merchant when displaying the customer consumption records or payment result page. ###### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ###### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited ##### merchant (Merchant, REQUIRED) The merchant information, including the merchant ID, merchant name, merchant category code, and so on. ###### referenceMerchantId (String, REQUIRED) The unique ID that is assigned by Alipay+ to identify a merchant. More information: - Maximum length: 32 characters ###### merchantMCC (String, REQUIRED) The merchant category code (MCC) that represents the categorization of the merchant's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details. More information: - Maximum length: 32 characters ###### merchantName (String, REQUIRED) The legal name of the merchant. More information: - Maximum length: 256 characters ###### merchantAddress (Address, REQUIRED) In the Cashier Payment and Auto Debit scenarios, the address indicates the region where the merchant is registered. In the User-presented Mode and Merchant-presented Mode Payment scenarios, the address indicates the region where the payment transaction occurs. ###### region (String, REQUIRED) The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard. More information: - Maximum length: 2 characters ###### state (String) The state, country, or province where the address is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### city (String) The city, district, suburb, town, or village where the address is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### address1 (String) The address line 1, which contains the street name, PO box, or company name.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### address2 (String) The address line 2, which contains the apartment, suite, unit, or building name. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### zipCode (String) The zip or postal code. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### merchantDisplayName (String, REQUIRED) The display name of the merchant. More information: - Maximum length: 64 characters ###### merchantRegisterDate (Datetime) The time when the merchant registered its business at the local regulatory agency. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ###### store (Store) The information about the store of the merchant. This parameter is specified by Alipay+ in the in-store payment scenario. ###### referenceStoreId (String, REQUIRED) The unique ID that is assigned by the merchant to identify a store. More information: - Maximum length: 32 characters ###### storeName (String, REQUIRED) The legal name of the store. More information: - Maximum length: 256 characters ###### storeMCC (String, REQUIRED) The merchant category code (MCC) that represents the categorization of the store's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details. More information: - Maximum length: 32 characters ###### storeDisplayName (String) The display name of the store. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### storeTerminalId (String) The unique ID that is assigned by the merchant to identify a store terminal. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### storeAddress (Address) The address where the store is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. ###### region (String, REQUIRED) The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard. More information: - Maximum length: 2 characters ###### state (String) The state, country, or province where the address is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### city (String) The city, district, suburb, town, or village where the address is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### address1 (String) The address line 1, which contains the street name, PO box, or company name.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### address2 (String) The address line 2, which contains the apartment, suite, unit, or building name. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### zipCode (String) The zip or postal code. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ##### goods (Array) The goods information, including the goods ID, goods name, and so on. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum size: 100 elements ###### referenceGoodsId (String, REQUIRED) The unique ID that is assigned by the merchant to identify the goods. More information: - Maximum length: 64 characters ###### goodsName (String, REQUIRED) The name of the goods. More information: - Maximum length: 256 characters ###### goodsCategory (String) The categorization of the goods. More information: - Maximum length: 256 characters ###### goodsUnitAmount (Amount) The unit price of the goods. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. ###### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ###### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited ###### goodsQuantity (Integer) The quantity of the goods. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Value range: 1 - unlimited ##### shipping (Shipping) The shipping information, including the information about the recipient and the carrier.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. ###### shippingName (UserName, REQUIRED) The name of the shipping recipient. ###### firstName (String) The first name of the user.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### middleName (String) The middle name of the user. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### lastName (String) The last name of the user. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### fullName (String, REQUIRED) The full name of the user. More information: - Maximum length: 128 characters ###### shippingAddress (Address, REQUIRED) The shipping address. ###### region (String, REQUIRED) The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard. More information: - Maximum length: 2 characters ###### state (String) The state, country, or province where the address is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### city (String) The city, district, suburb, town, or village where the address is located. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### address1 (String) The address line 1, which contains the street name, PO box, or company name.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### address2 (String) The address line 2, which contains the apartment, suite, unit, or building name. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### zipCode (String) The zip or postal code. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### shippingCarrier (String) The name of the shipping carrier, such as FedEx, UPS, or USPS.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 128 characters ###### shippingPhoneNo (String) The contact number of the shipping recipient. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 16 characters ##### buyer (Buyer) The buyer information, including the buyer ID, buyer name, and so on.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. ###### referenceBuyerId (String) The unique ID that is assigned by the merchant to identify a buyer. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### buyerName (UserName) The name of the buyer. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. ###### firstName (String) The first name of the user.  This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### middleName (String) The middle name of the user. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### lastName (String) The last name of the user. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### fullName (String, REQUIRED) The full name of the user. More information: - Maximum length: 128 characters ###### buyerPhoneNo (String) The contact number of the buyer. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 24 characters ###### buyerEmail (Email) The email address of the buyer. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ##### env (Env) The environment information about the device that is used by the user to place orders. ###### terminalType (String) The type of terminal that is used to initiate the payment.  Valid values are: - `WEB`: indicates that a PC browser is used. - `WAP`: indicates that a mobile browser is used. - `APP`: indicates that a mobile app is used. - `MINI_APP`: indicates that a mini program is used. ###### osType (String) The mobile operating system type. Valid values are: - `IOS`: indicates the iOS system - `ANDROID`: indicates the Android system ###### deviceTokenId (String) The token ID of the client device. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### clientIp (String) The IP address of the client device. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### cookieId (String) The cookie ID of the user. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### userAgent (String) The user-agent information. This parameter is returned by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 1024 characters #### paymentFactor (PaymentFactor) 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. The MPP can identify the payment scenario based on the following child parameters: - isInStorePayment - isCashierPayment For more information, see How to identify the payment scenarios in the More information section of this topic. ##### isInStorePayment (Boolean) Specifies whether the payment scenario is in-store payment. If the value of this parameter is specified as `true`, the payment scenario is in-store payment; otherwise, the payment scenario is online payment. ##### needSurcharge (Boolean) Specifies whether the MPP is to collect a surcharge from the user. If the value of this parameter is specified as `true`, the MPP is to collect a surcharge. By default, the value of this parameter is `false`. ##### isPaymentEvaluation (Boolean) Specifies whether the payment scenario is payment evaluation for Auto Debit. If the value of this parameter is specified as `true`, the request only evaluates whether the user account has sufficient balance to make the payment and no funds will be deducted. By default, the value of this parameter is `false`. ##### isCashierPayment (Boolean) Specifies whether a cashier page is presented to the user during the payment. If the value of this parameter is specified as `true`, a cashier page is presented to the user during the payment; otherwise, no cashier page is presented to the user during the payment. For Cashier Payment and Merchant-presented Mode Payment, this parameter is specified as `true` to present a cashier page to the user. ##### isAgreementPayment (Boolean) Specifies whether the payment scenario is Auto Debit. If the value of this parameter is specified as `true`, the payment scenario is Auto Debit; otherwise, the payment scenario is not Auto Debit. ##### isAuthorizationAndPay (Boolean) Specifies whether to perform authorization for Auto Debit during the payment. ##### isAuthorizationPayment (Boolean) Specifies whether the payment is an authorized payment. ##### isDeferredPayment (Boolean) Specifies whether the payment is a deferred payment, in which scenario the user uses the product or service in advance. ##### needCheckCompliance (Boolean) Specifies whether the payment information must be validated before the payment is processed. ##### needOtpVerification (Boolean) Specifies whether OTP verification is required before the payment is processed. ##### isCrossborderSettlement (Boolean) Specifies whether the payment requires cross-border settlement. ##### inStorePaymentScenario (String) The in-store payment scenario. Valid values are: - `PaymentCode`: indicates the scenario where a user presents a payment code to pay. - `OrderCode`: indicates the scenario where a user scans an order code to pay. - `EntryCode`: indicates the scenario where a user scans an entry code to pay. Note that this parameter may not return in some scenarios. Do not use this parameter to identify the payment scenario. For more information, see _How to identity the payment scenarios_ in the _More information_ section of this topic. #### paymentAmount (Amount) 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`. ##### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited #### payToAmount (Amount) 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`. ##### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited #### paymentQuote (Quote) 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_. ##### quoteId (String, REQUIRED) The unique ID that is assigned by Alipay+ to identify an exchange rate. More information: - Maximum length: 64 characters ##### quoteCurrencyPair (String, REQUIRED) A currency pair, of which the first listed currency (also called base currency) is quoted against the second currency (also called quote currency). The value of this parameter is in the format of `{``_base_currency_``}/{``_quote_currency_``}`, where `{``_base_currency_``}` and `{``_quote_currency_``}` are alphabetic codes that follow the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. For example, if the base currency is euro and the quote currency is dollar, the value of this parameter is EUR/USD. Sometimes, the first currency is the order currency and the second currency is the user's payment currency. Sometimes, the sequence is reversed. More information: - Maximum length: 8 characters ##### quotePrice (Decimal, REQUIRED) The quotation of the exchange rate between the currency pair that is specified on the _quoteCurrencyPair_ parameter. **Note**: The value is not always greater than or equal to 1 and has a decimal accuracy of 15 places. More information: - Maximum length: 32 characters ##### quoteStartTime (Datetime) The time when the quotation (specified on the _quotePrice_ parameter) takes effect. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ##### quoteExpiryTime (Datetime) The time when the quotation (specified on the _quotePrice_ parameter) expires. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ##### baseCurrency (String) The first currency in the currency pair that is specified on the _quoteCurrencyPair_ parameter. The value is an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. More information: - Maximum length: 3 characters ##### quoteUnit (String) The amount in the base currency that is specified on the _baseCurrency_ parameter. More information: - Maximum length: 12 characters #### 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+.  This parameter is returned by Alipay+ if the value of the _result_._resultCode_ parameter is `SUCCESS` and the value of _paymentFactor_._needSurcharge_ is `true`. ##### surchargeAmount (Amount, REQUIRED) This parameter specifies the actual amount that is paid by the user when a surcharge exists for the payment order. **Important**: The amount that the MPP settles to Alipay+ is still _payToAmount_. ###### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ###### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited ##### surchargeQuote (Quote, REQUIRED) The exchange rate between _paymentAmount.currency_ and _surchargeAmount.currency_. ###### quoteId (String, REQUIRED) The unique ID that is assigned by Alipay+ to identify an exchange rate. More information: - Maximum length: 64 characters ###### quoteCurrencyPair (String, REQUIRED) A currency pair, of which the first listed currency (also called base currency) is quoted against the second currency (also called quote currency). The value of this parameter is in the format of `_{base_currency}/{quote_currency}_`, where `_{base_currency}_` and {`_quote_currency}_` are alphabetic codes that follow the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. For example, if the base currency is euro and the quote currency is dollar, the value of this parameter is EUR/USD. Sometimes, the first currency is the order currency and the second currency is the user's payment currency. Sometimes, the sequence is reversed. More information: - Maximum length: 8 characters ###### quotePrice (Decimal, REQUIRED) The quotation of the exchange rate between the currency pair that is specified on the _quoteCurrencyPair_ parameter. **Note**: The value is not always greater than or equal to 1 and has a decimal accuracy of 15 places. More information: - Maximum length: 32 characters ###### quoteStartTime (Datetime) The time when the quotation (specified on the _quotePrice_ parameter) takes effect. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ###### quoteExpiryTime (Datetime) The time when the quotation (specified on the _quotePrice_ parameter) expires. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ###### baseCurrency (String) The first currency in the currency pair that is specified on the quoteCurrencyPair parameter. The value is an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. More information: - Maximum length: 3 characters ###### quoteUnit (String) The amount in the base currency that is specified on the _baseCurrency_ parameter. More information: - Maximum length: 12 characters #### 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 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: - 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: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". #### authorizationInfo (AuthorizationInfo) 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`. ##### referenceAgreementId (String, REQUIRED) The unique ID that is assigned by the auth client to identify an authorization. More information: - Maximum length: 64 characters ##### authClientId (String, REQUIRED) The unique ID that is assigned by the ACQP to identify an auth client, which is usually the merchant. More information: - Maximum length: 64 characters ##### authState (String) The authorization statement that is generated by the auth client. More information: - Maximum length: 256 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 returned by Alipay+ if the value of the _result_._resultCode_ parameter is `SUCCESS` and a promotion is applied to the payment order. ##### paymentPromoDetails (Array) The details of promotions that are applied to a payment order. ###### promoId (String, REQUIRED) The unique ID that is assigned by Alipay+ to identify a promotion. More information: - Maximum length: 128 characters ###### promoType (String, REQUIRED) The type of promotion. Valid values are: - `INSTANT_DISCOUNT`: indicates that an automatic discount is applied to the user's order - `COUPON`: indicates that a coupon is applied to the user's order ###### promoName (String, REQUIRED) The name of the promotion that is applied to the payment order. More information: - Maximum length: 128 characters ###### savingsAmount (Amount, REQUIRED) The amount that is saved if the promotion is applied to the payment order. The value of _savingsAmount.currency_ is the same as that of _payToAmount.currency_. ###### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ###### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited #### actionForm (ActionForm) The indicator for further action that the MPP needs to take to process the payment.  Note: If this parameter is not returned by Alipay+ or the value is `null`, the MPP needs to continue to process the payment itself. ##### actionType (String, REQUIRED) The type of further action that the MPP needs to take. Valid values are: -  `HANDLE_BY_SDK`:  - In order code scenarios, it indicates that the MPP Client needs to call the Alipay+ Client SDK API **handleAction**. - In entry code scenarios, it indicates that the MPP client executes a callback function of the Alipay+ Client SDK API **decode**. -  `HANDLE_BY_PSP`: indicates that the MPP needs to continue to process the payment itself. ##### sdkActionPayload (String) The data that needs to be passed through to the MPP Client first, and then to the Alipay+ Client SDK in the following ways: - In order code scenarios, the MPP Client passes through the data when calling the **handleAction** API. - In entry code scenarios, the MPP client passes through the data when executing a callback function of the **decode** API. This parameter is returned by Alipay+ if the value of the _actionForm.actionType_ parameter is `HANDLE_BY_SDK`. More information: - Maximum length: 2048 characters #### 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: - Maximum length: 20000 characters ## 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 identify the payment scenarios The following table shows how the key payment factors are returned 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_ | _isCashierPayment_ | | --- | --- | --- | | Merchant-presented Mode Payment | `TRUE` | `TRUE` | | Cashier Payment | `FALSE` or `NULL` | `TRUE` | ### 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` | 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` | REQUEST_TRAFFIC_EXCEED_LIMIT, UNKNOWN_EXCEPTION, etc. | Decoding is in processing. | Retry the same request. | | No result received | No result received | Unknown | Retry the same request. | ## Result/Error codes | Code | Value | Message | Further action | | --- | --- | --- | --- | | SUCCESS | S | Success | Guide the user to confirm the payment. | | ACCESS_DENIED | F | The access is denied. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | BUSINESS_NOT_SUPPORT | F | The payment business is not supported. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | CURRENCY_NOT_SUPPORT | F | The currency is not supported. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | EXPIRED_CODE | F | The code is expired. | Inform the user that the order code is expired. | | INVALID_CLIENT | F | The client is invalid. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | INVALID_CODE | F | The code is invalid. | Inform the user that the order code is invalid. | | INVALID_CONTRACT | F | The contract is invalid. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | INVALID_SIGNATURE | F | The signature is invalid. | Check whether the public key, signed message, and signature algorithm are as expected. | | KEY_NOT_FOUND | F | The key is not found. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Use a media type that is accepted by Alipay+. | | METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. | Ensure the HTTP method is POST. | | NO_INTERFACE_DEF | F | API is not defined. | Check whether the request URL is correct. Ensure that the endpoint of the called API is correct. | | ORDER_IS_CLOSED | F | order has been cancelled | Inform the user that the order is closed. | | PARAM_ILLEGAL | F | Illegal 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_FAIL | F | A 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_LIMIT | U | The request traffic exceeds the limit. | Reduce the frequency of API calls. | | UNKNOWN_EXCEPTION | U | An API calling is failed, which is caused by unknown reasons. | Try to recall the API. | | PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the transaction limit. | It is recommended that you inform the user of the error. | | USER_AMOUNT_EXCEED_LIMIT | F | The total payment amount accumulated by the user exceeds the transaction limit. | It is recommended that you inform the user of the error. | | USER_DAILY_AMOUNT_EXCEED_LIMIT | F | The total payment amount accumulated by the user today exceeds the daily transaction limit. | It is recommended that you inform the user of the error. | | USER_MONTHLY_AMOUNT_EXCEED_LIMIT | F | The total payment amount accumulated by the user this month exceeds the monthly transaction limit. | It is recommended that you inform the user of the error. | | USER_YEARLY_AMOUNT_EXCEED_LIMIT | F | The total payment amount accumulated by the user this year exceeds the yearly transaction limit. | It is recommended that you inform the user of the error. | ## Request ### ALIPAY, ALIPAY_HK, DANA, H5, DIRECT ```json { "codeValue": "http://xxxxx/281xxxxxxxxxxxxxxxx4441", "customerId": "208800000000000001", "indirectMpp": { "indirectMppId": "xxxMppId", "indirectMppName": "xxxMppName" } } ``` ## Response ```json { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }, "acquirerId": "1020000000000000001", "pspId": "1020000000000000001", "order": { "referenceOrderId": "OrderID_0101010101", "orderDescription": "SHOES", "orderAmount": { "value": "100", "currency": "JPY" }, "merchant": { "referenceMerchantId": "M00000000001", "merchantMCC": "5411", "merchantName": "UGG", "merchantDisplayName": "UGG", "merchantAddress": { "region": "JP", "city": "xxx" } } }, "codeType": "ORDER_CODE", "paymentRequestId": "20200000000000000133", "paymentAmount": { "value": "100", "currency": "JPY" }, "payToAmount": { "value": "1000", "currency": "KRW" }, "paymentQuote": { "quoteId": "1234567", "quoteCurrencyPair": "JPY/KRW", "quotePrice": "10.0000" }, "paymentPromoInfo": { "paymentPromoDetails": [ { "promoId": "discount_id_1", "promoType": "INSTANT_DISCOUNT", "promoName": "10 JPY off 100 JPY", "savingsAmount": { "value": "100", "currency": "KRW" } } ] }, "paymentFactor": { "isCashierPayment": "true", "isInStorePayment": "false" }, "paymentExpiryTime": "2025-11-27T12:01:01+08:00" } ```