Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      pay (Order Code Payment)

      Use the pay API to initiate a payment to Alipay and process payment results according to the status and operation instructions returned by 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: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

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

      Request parameters

      productCode StringRequired

      The payment product that the merchant can use, based on the contract between the merchant and Alipay. For Order Code Payment, the value is fixed as IN_STORE_PAYMENT.

      paymentRequestId String Required

      The unique ID that is assigned by a merchant to identify a payment request. Alipay uses this field for idempotence control. 

      More information about this field:

      • This field is an API idempotency field. Merchant uses the paymentRequestId field for idempotency control. For payment requests that are initiated with the same value of paymentRequestId and reach a final status (S or F), the same result is to be returned for the request.
      • Maximum length: 64 characters
      order OrderRequired

      Order information, such as buyer information, merchant information, order description, and order amount. 

      The parameter is also used for risk control, supervision, reporting, user payment result display, and so on.

      orderAmount AmountRequired

      The order amount of the merchant that directly provides services or goods to the customer. This field is used for user consumption records display or payment results page.

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      referenceOrderId StringOptional

      The unique ID to identify the order on the merchant side, which is assigned by the merchant that provides services or goods directly to the customer. This field is used for user consumption records display and further payment operations such as customer complaints and disputes track.

      More information about this field:

      • Maximum length: 64 characters
      orderDescription StringRequired

      Summary description of the order, which is used for user consumption records display or other further operations.

      More information about this field:

      • Maximum length: 256 characters
      goods Array<Goods>Optional

      Goods information

      referenceGoodsId StringRequired

      The unique ID to identify the goods

      More information about this field:

      • Maximum length: 64 characters
      goodsName StringRequired

      Goods name

      More information about this field:

      • Maximum length: 256 characters
      goodsUnitAmount AmountOptional

      Price of goods

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      goodsQuantity IntegerOptional

      Quantity of goods

      More information about this field:

      • Value range: 0 - unlimited
      shipping ShippingOptional

      Shipping information

      shippingName UserName Optional

      The recipant name

      firstName StringRequired

      First name

      More information about this field:

      • Maximum length: 32 characters
      middleName StringOptional

      Middle name

      More information about this field:

      • Maximum length: 32 characters
      lastName StringRequired

      Last name

      More information about this field:

      • Maximum length: 32 characters
      fullName StringOptional

      Full name

      More information about this field:

      • Maximum length: 128 characters
      shippingAddress AddressOptional

      Shipping address

      region StringRequired

      The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.

      More information about this field:

      • Maximum length: 2 characters
      state StringOptional

      The state, country, or province name.

      More information about this field:

      • Maximum length: 8 characters
      city StringOptional

      The city, district, suburb, town, or village name.

      More information about this field:

      • Maximum length: 32 characters
      address1 StringOptional

      Address line 1, for example, the street address, PO box, and company name.

      More information about this field:

      • Maximum length: 256 characters
      address2 StringOptional

      Address line 2, for example, the apartment, suite, unit, and building information.

      More information about this field:

      • Maximum length: 256 characters
      zipCode StringOptional

      ZIP or postal code

      More information about this field:

      • Maximum length: 32 characters
      shippingCarrier StringOptional

      The delivery service that shipped a physical product, such as FedEx, UPS, USPS, etc.

      More information about this field:

      • Maximum length: 128 characters
      shippingPhoneNo StringOptional

      The phone number of a recipient (including extension).

      More information about this field:

      • Maximum length: 16 characters
      buyer BuyerOptional

      Buyer information, which is used for risk control. It is highly recommended to be provided.

      referenceBuyerId StringOptional

      The unique ID to identify the buyer

      More information about this field:

      • Maximum length: 64 characters
      buyerName UserName Optional

      Name of the buyer

      firstName StringRequired

      First name

      More information about this field:

      • Maximum length: 32 characters
      middleName StringOptional

      Middle name

      More information about this field:

      • Maximum length: 32 characters
      lastName StringRequired

      Last name

      More information about this field:

      • Maximum length: 32 characters
      fullName StringOptional

      Full name

      More information about this field:

      • Maximum length: 128 characters
      buyerPhoneNo StringOptional

      Mobile phone number of the buyer

      More information about this field:

      • Maximum length: 24 characters
      buyerEmail EmailOptional
      Email of the buyer
      merchant MerchantRequired

      Information about the secondary merchant

      referenceMerchantId StringRequired

      The ID to identify the merchant that directly provides services or goods to the customer.

      More information about this field:

      • Maximum length: 32 characters
      merchantMCC StringRequired

      The merchant category code, which is a four-digit number listed in MCC codes. This field is required for Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

      More information about this field:

      • Maximum length: 32 characters
      merchantName StringRequired

      The merchant name

      More information about this field:

      • Maximum length: 256 characters
      merchantDisplayName StringOptional

      The merchant name to be displayed

      More information about this field:

      • Maximum length: 64 characters
      merchantAddress AddressOptional

      The merchant address information

      region StringRequired

      The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.

      More information about this field:

      • Maximum length: 2 characters
      state StringOptional

      The state, country, or province name.

      More information about this field:

      • Maximum length: 8 characters
      city StringOptional

      The city, district, suburb, town, or village name.

      More information about this field:

      • Maximum length: 32 characters
      address1 StringOptional

      Address line 1, for example, the street address, PO box, and company name.

      More information about this field:

      • Maximum length: 256 characters
      address2 StringOptional

      Address line 2, for example, the apartment, suite, unit, and building information.

      More information about this field:

      • Maximum length: 256 characters
      zipCode StringOptional

      ZIP or postal code

      More information about this field:

      • Maximum length: 32 characters
      merchantRegisterDate DatetimeOptional

      Merchant registration date

      More information about this field:

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

      Store information. This parameter is required for offline payment scenarios.

      referenceStoreId StringRequired

      The unique store ID assigned by the merchant that owns the store.

      More information about this field:

      • Maximum length: 64 characters
      storeName StringRequired

      Name of the store

      More information about this field:

      • Maximum length: 512 characters
      storeMCC StringRequired

      Store business category code

      More information about this field:

      • Maximum length: 32 characters
      storeDisplayName StringOptional

      Display name of the store

      More information about this field:

      • Maximum length: 64 characters
      storeAddress AddressOptional

      Address of the store

      region StringRequired

      The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.

      More information about this field:

      • Maximum length: 2 characters
      state StringOptional

      The state, country, or province name.

      More information about this field:

      • Maximum length: 8 characters
      city StringOptional

      The city, district, suburb, town, or village name.

      More information about this field:

      • Maximum length: 32 characters
      address1 StringOptional

      Address line 1, for example, the street address, PO box, and company name.

      More information about this field:

      • Maximum length: 256 characters
      address2 StringOptional

      Address line 2, for example, the apartment, suite, unit, and building information.

      More information about this field:

      • Maximum length: 256 characters
      zipCode StringOptional

      ZIP or postal code

      More information about this field:

      • Maximum length: 32 characters
      env EnvOptional

      Information about the environment where the order is placed, such as the device information. This field is required for Entry Code payments.

      terminalType StringOptional

      Terminal type of which the merchant service applies to. Valid values are:

      • WEB: The client-side terminal type is a website that is opened via a PC browser.
      • WAP: The client-side terminal type is an HTML page that is opened via a mobile browser.
      • APP: The client-side terminal type is a mobile application.

      Note: This field is required when productCodeType is Cashier payment.

      osType StringOptional

      OS type. Valid values are:

      • IOS: indicates the operation system is Apple's iOS.
      • ANDROID: indicates the operation system is Google's Android. 

      Note: This field is required when productCodeType is Cashier payment and terminalType is not WEB.

      userAgent StringOptional

      The user agent

      More information about this field:

      • Maximum length: 1024 characters
      deviceTokenId StringOptional

      Token identifier of the device

      More information about this field:

      • Maximum length: 64 characters
      clientIp StringOptional

      IP of the client device

      More information about this field:

      • Maximum length: 32 characters
      cookieId StringOptional

      The cookie ID of the buyer

      More information about this field:

      • Maximum length: 64 characters
      storeTerminalId StringOptional

      Store terminal ID. 

      Note: This field is required for the user-presented mode payment and order code payment.

      More information about this field:

      • Maximum length: 64 characters
      storeTerminalRequestTime Datetime Optional

      The time that the request is sent by the store terminal. 

      Note: This field must be accurate to milliseconds. Besides, this field is required for the User-presented Mode Payment and Order Code Payment. If you don't have the terminal request time, use the gateway time for this field.

      More information about this field:

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

      Extended information

      More information about this field:

      • Maximum length: 2048 characters
      extendInfo StringOptional

      Extended information data. This field includes information for special use cases. For example, for orders to Alipay CN, additional information is required as captured in ChinaExtraTransInfo.

      businessType StringRequired

      The business type. Valid values are

      • 1: Hotel
      • 2: Air Flight
      • 3: Study Abroad
      • 4: Trade
      • 5: Other  

      Multiple business types are delimited with '|'.

      More information about this field:

      • Maximum length: 16 characters
      flightNumber StringOptional

      The flightNumber. Multiple flight numbers are delimited with '|'. when businessType=2, you should pass the value.

      More information about this field:

      • Maximum length: 1000 characters
      departureTime DatetimeOptional

      The flight departure time. Multiple flight departure times are delimited with '|'.when businessType=2, you should pass the value.

      More information about this field:

      • Maximum length: 1000 characters
      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      hotelName StringOptional

      The hotel name. Multiple hotel names are delimited with '|'. when businessType=1, you should pass the value.

      More information about this field:

      • Maximum length: 1000 characters
      checkinTime DatetimeOptional

      The hotel check-in time. Multiple hotel check-in times are delimited with '|'.when businessType=1, you should pass the value.

      More information about this field:

      • Maximum length: 1000 characters
      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      checkoutTime DatetimeOptional

      The hotel checkout time. Multiple hotel checkout times are delimited with '|'.when businessType=1, you should pass the value.

      More information about this field:

      • Maximum length: 1000 characters
      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      admissionNoticeUrl URLOptional

      The school admission notice URL. Mulitple URLs are delimited with '|'.when businessType=3, you should pass the value.

      More information about this field:

      • Maximum length: 1000 characters
      goodsInfo StringOptional

      Goods information that includes SKU names and corresponding quantities, in the format of SKU_name^quantity. If more than one goods exists, separate values with a vertical bar (|). Specify this field only when business_type is 4 (Sales of goods). When businessType=4, you should pass the value.

      More information about this field:

      • Maximum length: 2000 characters
      totalQuantity IntegerOptional

      Total quantities of all goods in one order. Specify this field only when business_type is 4 (Sales of goods). When businessType=4, you should pass the value.

      More information about this field:

      • Value range: 0 - unlimited
      paymentAmount AmountRequired

      The payment amount that the merchant requests to receive in the order currency.

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      payToMethod PaymentMethodOptional

      Account asset identification for merchant settlement. 

      paymentMethodType StringRequired

      Payment method type: 

      For in-store payments, the value is CONNECT_WALLET.

      More information about this field:

      • Maximum length: 32 characters
      paymentMethodId StringOptional

      The unique ID of the payment method that belongs to a buyer.

      More information about this field:

      • Maximum length: 128 characters
      paymentMethodMetaData StringOptional

      Other information about payment methods, which are key-value pairs in JSON format.

      More information about this field:

      • Maximum length: 2048 characters
      customerId StringOptional

      The unique ID to identify a buyer

      More information about this field:

      • Maximum length: 32 characters
      extendInfo StringOptional

      Extended information

      More information about this field:

      • Maximum length: 2048 characters
      paymentMethod PaymentMethodRequired

      The payment method that is used to collect the payment by the payment executor.

      paymentMethodType StringRequired

      Payment method type:

      For in-store payments, the value is CONNECT_WALLET.

      More information about this field:

      • Maximum length: 32 characters
      paymentMethodId StringOptional

      The unique ID of the payment method that belongs to a buyer.

      More information about this field:

      • Maximum length: 128 characters
      paymentMethodMetaData StringOptional

      Other information about payment methods, which are key-value pairs in JSON format.

      More information about this field:

      • Maximum length: 2048 characters
      customerId StringOptional

      The unique ID to identify a buyer

      More information about this field:

      • Maximum length: 32 characters
      extendInfo StringOptional

      Extended information

      More information about this field:

      • Maximum length: 2048 characters
      paymentExpiryTime DatetimeOptional

      A specific time, after which the payment will not succeed. The payment expiry time must be less than 30 minutes.

      More information about this field:

      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      paymentRedirectUrl URLOptional
      The URL that the user is redirected to after the payment is completed

      More information about this field:

      • Maximum length: 2048 characters
      paymentNotifyUrl URLRequired
      The URL that is used to receive the payment result notification

      More information about this field:

      • Maximum length: 2048 characters
      isAuthorization BooleanOptional
      This parameter indicates whether the request is a payment authorization.
      paymentVerificationData PaymentVerificationDataOptional

      Payment verification information

      verifyRequestId StringRequired

      This is the requestId generated by payment site when calling the initAuthentication interface that is associated with this request.

      More information about this field:

      • Maximum length: 64 characters
      authenticationCode StringRequired

      Verification code

      More information about this field:

      • Maximum length: 64 characters
      paymentFactor PaymentFactorOptional

      Specifies the payment scenario

      isPaymentEvaluation BooleanOptional

      Indicates whether it's a payment evaluation. The default value is F.

      inStorePaymentScenario StringOptional

      Indicates the payment scenario of in-store payments. Valid values are:

      • PaymentCode: Indicates that the user can use the payment code to pay.
      • OrderCode: Indicates that the user can use the order code to pay.
      • EntryCode: Indicates that the user can use the entry code to pay.

      Response parameters

      result ResultRequired

      The request result contains information such as status and error codes.

      resultCode StringRequired

      Result code

      More information about this field:

      • Maximum length: 64 characters
      resultStatus StringRequired

      Result status. Valid values are: 

      • S: Indicates that the result status is successful. 
      • F: Indicates that the result status failed. 
      • U: Indicates that the result status is unknown.
      resultMessage StringOptional

      Result message

      More information about this field:

      • Maximum length: 256 characters
      paymentRequestId StringOptional

      The unique ID that is assigned by a merchant to identify a payment request.

      More information about this field:

      • Maximum length: 64 characters
      paymentId StringOptional

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

      More information about this field:

      • Maximum length: 64 characters
      paymentAmount AmountOptional

      The payment amount that the merchant requests to receive in the order currency.

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      paymentTime DatetimeOptional

      The date and time when the payment reaches a final state of success or failure. 

      More information about this field:

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

      The date and time when the payment is created.

      More information about this field:

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

      Authorization expiration time. 

      More information about this field:

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

      The customer information of Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

      pspName StringOptional

      The name of Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

      More information about this field:

      • Maximum length: 64 characters
      pspCustomerId StringOptional

      The customer ID of Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

      More information about this field:

      • Maximum length: 64 characters
      displayCustomerId StringOptional

      The customer ID used for display. For example, loginId.

      More information about this field:

      • Maximum length: 64 characters
      challengeActionForm ChallengeActionFormOptional

      Provides information about the challenge action when the payment result is not in a final state of success or failure.

      challengeType StringRequired

      Type of challenge. Valid values are: 

      • SMS_OTP: SMS OTP verification
      • PLAINTEXT_CARD_NO: Plain text card number challenge
      • CARD_EXPIRE_DATE: Card expiry date challenge 
      challengeRenderValue StringRequired

      The actual render value

      More information about this field:

      • Maximum length: 64 characters
      triggerSource StringRequired

      Describes that the challenge is required by Alipay or external party. Valid values are:

      • AMS: Describes the challenge that is required by Alipay.
      • CHANNEL: Describes the challenge that is required by the external party.
      extendInfo StringOptional

      Extended information

      More information about this field:

      • Maximum length: 2048 characters
      redirectActionForm RedirectActionFormOptional

      Provides information about the redirection action.

      method StringRequired

      Indicates the method type. Valid values are:

      • POST: Indicates that the request that is sent to the redirection address needs to be a POST request.
      • GET: Indicates that the request that is sent to the redirection address needs to be a GET request.
      • SCAN: Indicates that the request that is sent to the redirection address needs to be a SCAN request. 
      parameters StringOptional

      Parameters required for the HTTP method in the key-value pair.

      More information about this field:

      • Maximum length: 2048 characters
      redirectUrl URLRequired

      The URL where the user is redirected to.

      More information about this field:

      • Maximum length: 1024 characters
      orderCodeForm OrderCodeFormOptional

      Provides information about the order code.

      paymentMethodType StringOptional

      Payment method type. Valid values are:

      • ALIPAY_CN: Alipay CN wallet 
      • CONNECT_WALLET: Alipay+ Mobile Payment Partner 
      • TRUEMONEY: TrueMoney wallet.
        Note: The minimum payment amount allowed for this wallet is 1 THB. The minimum refund amount allowed for this wallet is 1 THB. 
      • ALIPAY_HK: Alipay HK wallet.
        Note: For the auto debit payment, the minimum payment amount allowed for this wallet is 0.01 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.01 HKD. For the cashier payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum refund amount allowed for this wallet is 0.1 HKD. 
      • TNG: Touch 'n Go wallet
        Note: The minimum payment amount allowed for this wallet is 0.1 MYR. The minimum refund amount allowed for this wallet is 0.1 MYR. 
      • GCASH: Gcash wallet
        Note: The minimum payment amount allowed for this wallet is 1 PHP. The minimum refund amount allowed for this wallet is 1 PHP. 
      • DANA: Dana wallet
        Note: The minimum payment amount allowed for this wallet is 300 IDR. The minimum refund amount allowed for this wallet is 300 IDR. 
      • BKASH: bKash wallet
        Note: The minimum payment amount allowed for this wallet is 0.01 BDT. The minimum refund amount allowed for this wallet is 0.01 BDT. 
      • EASYPAISA: EasyPaisa wallet
        Note: The minimum payment amount allowed for this wallet is 100 PKR. The minimum refund amount allowed for this wallet is 100 PKR. 
      • KAKAOPAY: KakaoPay wallet
        Note: The minimum payment amount allowed for this wallet is 50 KRW. The minimum refund amount allowed for this wallet is 50 KRW.

      More information about this field:

      • Maximum length: 64 characters
      expireTime DatetimeOptional

      Expiry time of the order code information.

      More information about this field:

      • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
      codeDetails Array<CodeDetail>Required

      Details about the code.

      More information about this field:

      • Maximum size: 4 elements
      codeValueType StringRequired

      Code type. Valid values are:

      • BARCODE: Indicates a bar code.
      • QRCODE: Indicates a QR code. 
      codeValue StringRequired

      Code value

      More information about this field:

      • Maximum length: 2048 characters
      displayType StringRequired

      Indicates the way to show the code. Valid values are:

      • TEXT: Indicates to be directly shown on UI as text or label.
      • MIDDLEIMAGE: Indicates to be shown as a middle size image.
      • SMALLIMAGE: Indicates to be shown as a small size image.
      • BIGIMAGE: Indicates to be shown as a big size image. 
      extendInfo StringOptional

      Extended information

      More information about this field:

      • Maximum length: 2048 characters
      grossSettlementAmount AmountOptional

      Gross settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote

      Note: This field is empty when the settlement currency is the same as the transaction currency.

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      settlementQuote QuoteOptional

      The exchange rate between the settlement currency and transaction currency at the time of the transaction, which is provided only in the locked-in rate case. 

      Note: This field is empty when the settlement currency is the same as the transaction currency.

      quoteId StringOptional

      The unique ID to identify an exchange rate.

      More information about this field:

      • Maximum length: 64 characters
      quoteCurrencyPair StringRequired

      Pair of currency exchange rate

      More information about this field:

      • Maximum length: 16 characters
      quotePrice DecimalRequired

      The exchange rate used when a currency conversion occurs.

      More information about this field:

      • Value range: 0 - unlimited
      quoteStartTime DatetimeOptional

      Effective time of the exchange rate. 

      More information about this field:

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

      Expiration time of the exchange rate. 

      More information about this field:

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

      Guaranteed exchange rate available for payment

      More information 

      This section gives additional information about other parameters. See the following parameters for details:

      productCode:
      The value of this parameter is the payment product that the merchant uses for collecting payments, based on the contract between the merchant and Alipay. When the merchant can use multiple products, this parameter is required.

      order:
      The order parameter contains order information, such as Merchant, Goods, logistic, and purchase environment. During the payment process, the order information is mainly used by Alipay for risk control or anti-money laundering. After the payment is completed, the information is used to display consumption records, regulatory reporting, and other purposes.
      However, Alipay does not verify the consistency of the amount in order and the amount in the payment request. The order information is not applied in fund operations either. Use the env field if the risk control capability provided by Alipay is needed.

      payToMethod:
      The parameter is mainly used for payee account settings. When the merchant signs the settlement contract with Alipay, the default settlement account will be specified. If the merchant needs to settle to an account that is not the default one, the merchant must specify the new settlement account.

      paymentMethod:
      The value of paymentMethod is CONNECT_WALLET, indicating that Alipay collects money from the order code that was generated by Alipay.

      paymentExpiryTime:
      The payment executor must ensure that the payment will not succeed after the expiration time. If this parameter is not specified in the request, the expiration time is then decided by the payment executor.

      paymentFactor:
      The value of paymentFactor.inStorePaymentScenario is OrderCode, indicating that Alipay needs to generate an order code in this payment.

      paymentId:
      If this field is not returned in the response, you can use the paymentRequestId field to initiate inquiryPayment and cancel requests.

      authExpiryTime:
      If the value of this field is true, a specific value is returned. 

      Result process logic

      After calling a pay interface, the following results might be returned from Alipay:

      • Alipay returns that result.resultStatus is S, which indicates the merchant needs to display the payment information to the user by using the parameters in a form that the user can proceed.
      • Alipay returns that result.resultStatus is F, the payment request fails.
      • Alipay returns that result.resultStatus is U, the merchant needs to call the pay interface again. 

      Error codes

      Error codes are usually classified into the following categories:

      • Common error codes: common for all online and in-store payment APIs.
      • API-specific error codes: listed in the following table.  

      Result/Error codes

      CodeValueMessageFurther action
      SUCCESSSSuccess

      The payment is successful, no further action is needed.

      CURRENCY_NOT_SUPPORT FThe currency is not supported.

      Use the currency that is agreed in the contract.

      PAYMENT_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the limit.

      Recommend to modify the payment amount.

      REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.

      Change paymentRequestID and call the interface again.

      CLIENT_INVALIDFThe client is invalid.

      Check whether the clientId is correct.

      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

      Check whether the HTTP method is correct.

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

      Check whether the media type is correct.

      USER_KYC_NOT_QUALIFIEDFPayment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information).

      Prompt the user to complete KYC.

      Request/Response Code

      Request

      Method

      POST

      Endpoint

      /v1/payments/pay

      Header

      Accept: application/json

      URL

      Domain name

      Request Body
      Request parameters
      Response Body
      Body content