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

      pay (Auto Debit)

      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 Auto Debit Payment, the value is fixed as AGREEMENT_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 StringRequired

      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 UserNameOptional
      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 UserNameOptional
      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 MerchantOptional

      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 StringOptional

      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 StringOptional

      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 StoreOptional

      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.
      • MINI_APP: The terminal type of the merchant side is a mini program on the mobile phone. 

      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 DatetimeOptional

      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.
      • For auto debit and cashier payments, valid values are:
        • CONNECT_WALLET: Alipay+ Mobile Payment Partner 
        • ALIPAY_CN: Alipay CN wallet 
        • 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. 
        • 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. 
        • ALIPAY_HK: Alipay HK wallet.
          Note: For the auto debit payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.1 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.

      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.
      • For auto debit and cashier payments, valid values are:
        • CONNECT_WALLET: Alipay+ Mobile Payment Partner 
        • ALIPAY_CN: Alipay CN wallet 
        • 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. 
        • 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. 
        • ALIPAY_HK: Alipay HK wallet.
          Note: For the auto debit payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.1 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.

      More information about this field:

      • Maximum length: 32 characters
      paymentMethodId StringOptional

      The unique ID of the payment method that belongs to a buyer. By specifying this field, it indicates that the token generated by the contract is used for deduction.

      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.
      Note: The time specified in this field must be within one minute after the payment request is sent by the merchant. 

      More information about this field:

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

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

      The settlement strategy for the payment request

      settlementCurrency StringOptional

      The ISO currency code of the currency that the merchant wants to be settled against. When paymentMethod is AlipayCN, this field must be specified.

      More information about this field:

      • Maximum length: 3 characters
      creditPayPlan CreditPayPlanOptional

      The credit payment plan information for this payment when the payment method is credit payment.

      installmentNum StringRequired

      The number of installments within a month.

      More information about this field:

      • Maximum length: 8 characters
      creditPayFeeType StringRequired

      The value of this field is PERCENTAGE, which indicates that the fee is described in percentage with 1 - 3 digits. For example, 5 means 5%, 100 means 100%.

      feePercentage IntegerOptional

      This field is determined by the sellers' liability. For example: 0 indicates the seller is not liable for any fee. 100 indicates the seller pays 100% of the fee.   

      Note: This field is required when the value of creditPayFeeType is PERCENTAGE.

      More information about this field:

      • Value range: 0 - 100
      appId StringOptional

      The unique ID that is assigned by Alipay to identify the mini program app.

      Note: This field is required when terminalType is MINI_APP.

      More information about this field:

      • Maximum length: 32 characters
      paymentNotifyUrl URLOptional

      The URL that is used to receive the payment result notification.

      Note: Specify this field if you want to receive an asynchronous notification of the auto debit result. You can also set the URL to receive the payment result notification in Alipay Developer Center. But if the payment notification URL is specified in both the request and Alipay Developer Center, the value specified in the request takes precedence.

      More information about this field:

      • Maximum length: 2048 characters

      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:

      • 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
      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.1 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.1 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>Optional

      Details about the code.

      More information about this field:

      • Maximum size: 4 elements
      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

      The value of this field equals to transaction amount multiplied by the value of settlementQuote, which is the actual settlement amount of this transaction for the corresponding refund amount. This field is only provided when the currency exchange is predetermined and the exchange rate is locked at the time of transaction. This field will be empty for all other cases. 

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

      Note: This field is empty when the value of grossSettlementAmount is null.

      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 list for details:

      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 for display of consumption records, regulatory reporting, and some 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.

      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.

      paymentMethodType:
      By specifying this field, it indicates that the payment is made by using the specific wallet.

      paymentMethodId:
      By specifying this field, it indicates that the token generated by the contract is used for deduction.

      payToMethod:
      The parameter is mainly used for payee account setting. 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.

      paymentExpiryTime:
      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 is then decided by the contract. 

      authExpiryTime:
      If the value of isAuthorization is ​true, a specific value is returned. 

      Result process logic

      For different request results, different actions are to be performed. See the following list for details:

      When the value of isPaymentEvaluation is false:

      • If the value of result.resultStatus is S, the payment request is successfully processed by Alipay.
      • If the value of result.resultStatus is F, the payment request fails.
      • If the value of result.resultStatus is U, the result is unknown and payment initiator needs to check if the value of challengeActionForm, redirectActionForm, or orderCodeForm is empty:
        • If the value of orderCodeForm is not empty, the merchant displays the payment information to the user by using the parameters in the form so that the user can proceed.
        • If the value of challengeActionForm is not empty, the merchant initiates a challenge by using the parameters in the form to drive the payment process.
        • If the value of redirectActionForm is not empty, the merchant initiates a redirection by using the parameters in the form to drive the payment process.
        • If all the three fields are empty, the merchant can continue to query the payment result or wait for the notification of the asynchronous payment result. 

      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.

      INVALID_ACCESS_TOKENFThe access token is invalid.

      Check whether the accessToken has expired. If the accessToken has expired, call the applyToken interface to refresh the token or re-sign the contract.

      USER_NOT_EXISTFThe user does not exist.

      Prompt the user to check whether the user exists.

      CURRENCY_NOT_SUPPORT FThe currency is not supported.

      Use the currency that is agreed in the contract.

      USER_BALANCE_NOT_ENOUGHFThe user balance is not enough for the payment.

      Prompt the user that the balance is insufficient.

      USER_STATUS_ABNORMALFThe user status is abnormal.

      Prompt the user that the user status is abnormal.

      NO_PAY_OPTIONFThis is not a valid payment option.

      Contact Alipay Technical Support.

      ORDER_IS_CANCELEDFThe order is canceled.

      Re-place the order.

      PAYMENT_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the limit.

      Prompt the user to check whether the payment amount exceeds the limit.

      PAYMENT_COUNT_EXCEED_LIMITFThe number of payments exceeds the limit.

      Prompt the user that the number of payments exceeds the limit.

      REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.

      Use a unique paymentRequestId to initiate the payment again.

      USER_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the user payment limit.

      Prompt the user to check the payment amount.

      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.

      PAYMENT_IN_PROCESSUThe payment is being processed.

      Call the inquiryPayment interface to query the final payment status.

      UNKNOWN_EXCEPTIONUAn API call failed due to unknown reasons.

      Call the inquiryPayment interface to query the final payment status.

      PAYMENT_NOT_QUALIFIEDFThe merchant is not qualified to pay because the merchant is not registered, does not have a contract for auto debit payment, or is forbidden to make a payment.

      Contact Alipay Technical Support.

      ORDER_NOT_EXISTFThe order does not exist.

      Check whether paymentRequestId is correct.

      ORDER_IS_CLOSEDFThe order is closed, which might be caused by payment expiration.

      Re-place the order.

      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