# pay (NFC Payment) 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: - [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 #### 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. ##### 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. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, 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) 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1. More information: - Value range: 1 - unlimited ###### goodsQuantity (Integer) The quantity of the goods. This parameter is specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified 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 specified by Alipay+ if the relevant information is passed in by the merchant. ###### firstName (String) The first name of the user.  This parameter is specified 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 specified 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 specified 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 specified 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 specified 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. This parameter is specified by Alipay+ if all the following requirements are met: - _paymentFactor.isInStorePayment_ is specified as `true`. - _paymentFactor.authorizationType_ is specified as `FINAL_AUTHORIZATION`, `PRE_AUTHORIZATION`, or `UNDEFINED_AUTHORIZATION`. - _paymentFactor.inStorePaymentScenario_ is specified as `NfcPayment`. - _paymentFactor.isSupplementalPayment_ is specified as `false`. - _paymentFactor.isTransitDebtRecovery_ is specified as `false`. ###### 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 specified 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 specified 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 specified 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 specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 1024 characters #### 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. ##### 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. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1. More information: - Value range: 1 - unlimited #### 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. ##### 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. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, 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 specified by Alipay+ if _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 by 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 by 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 by 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 by 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+.  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`. ##### 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. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, 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: - Value range: 32 ###### quoteStartTime (Datetime) The time when the quotation (specified by 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 by 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 by 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 by the _baseCurrency_ parameter. More information: - Maximum length: 12 characters #### paymentMethod (PaymentMethod, REQUIRED) The payment method that is used to collect the payment. ##### paymentMethodType (String, REQUIRED) The type of payment method. Sample values include: - `TRUEMONEY`: Indicates the TrueMoney wallet - `ALIPAY_HK`: Indicates the AlipayHK wallet - `TNG`: Indicates the Touch 'n Go eWallet - `ALIPAY_CN`: Indicates the AlipayCN wallet - `GCASH`: Indicates the GCash wallet - `DANA`: Indicates the DANA wallet - `KAKAOPAY`: Indicates the KakaoPay wallet - `RABBIT_LINE_PAY`: Indicates the Rabbit LINE Pay wallet - `BPI`: Indicates the Bank of the Philippine Islands (BPI) - `CONNECT_WALLET`: Indicates the Alipay+ wallets More information: - Maximum length: 32 characters ##### customerId (String) The unique ID that is assigned by the MPP to identify a user. Specify this parameter if _paymentMethod.paymentMethodId_ and _paymentMethod.paymentMethodMetaData.userLoginId_ are not specified. More information: - Maximum length: 64 characters ##### paymentMethodMetaData (PaymentMethodMetaData) The metadata of the payment method. Specify this parameter if _paymentMethod.customerId_ and _paymentMethod.paymentMethodId_ are not specified. ###### authClientId (String) The unique ID that is assigned by the ACQP to identify an auth client. More information: - Maximum length: 64 characters ###### userLoginId (String) The login ID that is used by the MPP user to log in to the MPP platform. The value of _userLoginId_ can be the user's email address or phone number. With this parameter, the MPP can check whether the user's account supports the payment. More information: - Maximum length: 128 characters ###### userLoginIdType (String) The type of method that the MPP user selects to log in to the MPP platform. Valid values are: - MOBILE: indicates that the MPP user logs in to the MPP platform with a phone number. - EMAIL: indicates that the MPP user logs in to the MPP platform with an email address. ##### customData (String) The data that is generated by the MPP app to pass to the MPP server. More information: - Maximum length: 20 characters #### paymentFactor (PaymentFactor, REQUIRED) Factors that impact payment-related items such as the quote price, fee, and regulatory reporting. ##### 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. In the NFC payment scenario, the value of this parameter is `true`. ##### 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`. ##### 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. ##### inStorePaymentScenario (String) The in-store payment scenario. Valid values are: - `PaymentCode`: indicates that the user presents a payment code to pay. - `OrderCode`: indicates that the user scans an order code to pay. - `EntryCode`: indicates that the user scans an entry code to pay. - `NfcPayment`: indicates that the user taps a POS machine with a mobile phone to pay. In the NFC payment scenario, the value of this parameter is `NfcPayment`. ##### authorizationType (String) The authorization type. Valid values are: - `FINAL_AUTHORIZATION`: indicates that a user pays the full amount upon receiving the service or merchandise, for example, retail purchases. - `PRE_AUTHORIZATION`: indicates that prepayment is required before receiving the service or merchandise, for example, hotel bookings, car rentals, or public transport. - `UNDEFINED_AUTHORIZATION`: indicates undefined scenarios. ##### isSupplementalPayment (Boolean) Specifies whether the payment is a supplemental payment. By default, the value of this parameter is `false`. ##### isTransitDebtRecovery (Boolean) Specifies whether the payment is a debt recovery from a transit payment. By default, the value of this parameter is `false`. ##### isDomestic (Boolean) Specifies whether the payment is domestic. By default, the value of this parameter is `false` . #### 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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. ##### 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. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1. More information: - Value range: 1 - unlimited #### paymentNetworkAdditionalInfo (PaymentNetworkAdditionalInfo) Information about the payment network, such as Mastercard. ##### orderSource (String, REQUIRED) The order source type. Valid values are: - `TERMINAL`: indicates that the transaction is initiated through a terminal. - `ECOMMERCE`: indicates that the transaction is conducted through e-commerce. More information: - Maximum length: 64 characters ##### paymentNetworkLifecycleId (String) The transaction lifecycle ID that is assigned by the payment network to identify associated transactions, such as payments and refunds. More information: - Maximum length: 64 characters ##### paymentNetworkOrderId (String) The transaction ID that is assigned by the payment network to identify a transaction. More information: - Maximum length: 64 characters ##### paymentNetworkType (String) The payment network. The valid value is: - `MASTER_CARD`: indicates Mastercard. More information: - Maximum length: 64 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 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. ##### 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. It is recommended that you return this parameter to provide details about the result. More information: - Maximum length: 256 characters #### 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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 ## 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.  ```json { "order":{ "referenceOrderId":"OrderID_0100000101", "orderDescription":"SHOES", "orderAmount":{ "value":"100", "currency":"JPY" }, "merchant":{ "referenceMerchantId":"M00000000001", "merchantMCC":"5411", "merchantName":"UGG", "merchantDisplayName":"UGG", "merchantAddress":{ "region":"JP", "city":"xxx" }, "store":{ "referenceStoreId":"S0000000001", "storeName":"UGG-2", "storeMCC":"5411", "storeTerminalId":"69014001" } } }, "acquirerId": "1020000000000000001", "pspId":"1020000000000000001", "paymentRequestId":"2010000000000000000000000007771", "orderLifecycleId":"2010000000000000000000000007772", "paymentExpiryTime": "2020-01-01T12:01:01+08:30", "paymentAmount":{ "value":"100", "currency":"JPY" }, "paymentMethod":{ "paymentMethodType": "CONNECT_WALLET", "customerId":"2160000000000001" }, "payToAmount":{ "value":"1000", "currency":"KRW" }, "paymentQuote":{ "quoteId":"1234567", "quoteCurrencyPair":"JPY/KRW", "quotePrice":"10.0000" }, "paymentFactor": { "authorizationType": "FINAL_AUTHORIZATION", "inStorePaymentScenario": "NfcPayment", "isSupplementalPayment": "true", "isInStorePayment": "true", "isTransitDebtRecovery": "false", "isDomestic":"true" }, "paymentNetworkAdditionalInfo": { "orderSource": "TERMINAL", "paymentNetworkLifecycleId": "7dbbf678-a720-488a-9040-cbe728a846f4", "paymentNetworkOrderId": "9142e53b-f1f5-484a-a786-9a3a9472ce40", "paymentNetworkType": "MASTER_CARD" } } ``` 2\. The MPP returns the response to Alipay+. { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }, "paymentId": "201000000000000000000000004444", "paymentTime": "2020-01-01T12:01:01+08:30", "customerId": "2160000000000001" } ## 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. | ## Request ```json { "order": { "referenceOrderId": "OrderID_0100000101", "orderDescription": "SHOES", "orderAmount": { "value": "100", "currency": "JPY" }, "merchant": { "referenceMerchantId": "M00000000001", "merchantMCC": "5411", "merchantName": "UGG", "merchantDisplayName": "UGG", "merchantAddress": { "region": "JP", "city": "xxx" }, "store": { "referenceStoreId": "S0000000001", "storeName": "UGG-2", "storeMCC": "5411", "storeTerminalId": "69014001" } }, "env": { "deviceTokenId": "89D64DD5D06B0CBA901DEF4321290ADEF7900B2016E8429AC43BE97BDDD0765D" } }, "acquirerId": "1020000000000000001", "pspId": "1020000000000000001", "paymentRequestId": "2010000000000000000000000007771", "orderLifecycleId": "2010000000000000000000000007772", "paymentExpiryTime": "2020-01-01T12:01:01+08:30", "paymentAmount": { "value": "100", "currency": "JPY" }, "paymentMethod": { "paymentMethodType": "CONNECT_WALLET", "customerId": "2160000000000001", "customData": "0000008c21c727f2be19" }, "payToAmount": { "value": "1000", "currency": "KRW" }, "paymentQuote": { "quoteId": "1234567", "quoteCurrencyPair": "JPY/KRW", "quotePrice": "10.0000" }, "paymentFactor": { "authorizationType": "FINAL_AUTHORIZATION", "inStorePaymentScenario": "NfcPayment", "isSupplementalPayment": "false", "isInStorePayment": "true", "isTransitDebtRecovery": "false", "isDomestic": "false" }, "paymentNetworkAdditionalInfo": { "orderSource": "TERMINAL", "paymentNetworkLifecycleId": "7dbbf678-a720-488a-9040-cbe728a846f4", "paymentNetworkOrderId": "9142e53b-f1f5-484a-a786-9a3a9472ce40", "paymentNetworkType": "MASTER_CARD" } } ``` ## Response ```json { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }, "paymentId": "201000000000000000000000004444", "paymentTime": "2020-01-01T12:01:01+08:30", "customerId": "2160000000000001" } ```