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

      Payment (Consumer-presented Mode Payment)

      Use this interface to initiate a payment to Alipay and process payment results according to the status and operation instructions returned by Alipay.   

      Request parameters

      productCodeEnumRequired

      The payment product that the merchant can use, based on the contract between the merchant and Alipay. For Consumer-presented Mode Payment, the value is fixed as IN_STORE_PAYMENT.

      paymentRequestIdString (64)Required
      The unique ID that is assigned by a merchant to identify a payment request. Special characters are not supported.
      orderOrderRequired

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

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

      orderAmountAmountRequired

      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.

      currencyString(3)Required

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

      valueString(16)Required
      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).
      referenceOrderIdString(64)Optional
      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.
      orderDescriptionString(256)Required
      Summary description of the order, which is used for user consumption records display or other further operations.
      goodsList<Goods>Optional

      Goods information

      referenceGoodsIdString(64)Required
      The unique ID to identify the goods
      goodsNameString(256)Required
      Goods name
      goodsUnitAmountAmountOptional

      Price of goods

      currencyString(3)Required

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

      valueString(16)Required
      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).
      goodsQuantityString(32)Optional
      Quantity of goods
      shippingShippingOptional

      Shipping information

      shippingNameUserNameOptional

      The recipant name

      firstNameString(32)Required
      First name
      middleNameString(32)Optional
      Middle name
      lastNameString(32)Required
      Last name
      fullNameString(128)Optional
      Full name
      shippingAddressAddressOptional

      Shipping address

      regionString(2)Required

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

      stateString(8)Optional
      The state, country, or province name.
      cityString(32)Optional
      The city, district, suburb, town, or village name.
      address1String(256)Optional
      Address line 1, for example, the stress address/PO box/company name
      address2String(256)Optional
      Address line 2, for example, the apartment/suite/unit/building informaiton
      zipCodeString(32)Optional
      ZIP or postal code
      shippingCarrierString(128)Optional
      The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.
      shippingPhoneNoString(16)Optional
      The phone number of a recipient (including extension).
      buyerBuyerOptional

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

      referenceBuyerIdString(64)Optional
      The unique ID to identify the buyer
      buyerNameUserNameOptional

      Name of the buyer

      firstNameString(32)Required
      First name
      middleNameString(32)Optional
      Middle name
      lastNameString(32)Required
      Last name
      fullNameString(128)Optional
      Full name
      buyerPhoneNoString(24)Optional
      Mobile phone number of the buyer
      buyerEmailStringOptional
      Email of the buyer
      merchantMerchantRequired

      Information about the secondary merchant

      referenceMerchantIdString(32)Required
      The ID to identify the merchant that directly provides services or goods to the customer.
      merchantMCCString(32)Required

      The merchant category code, which is a four-digit number listed in ISO 18245. This field is required for the PMP.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      merchantNameString(256)Required
      The merchant name
      merchantDisplayNameString(64)Optional
      The merchant name to be displayed
      merchantAddressAddressOptional

      The merchant address information

      regionString(2)Required

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

      stateString(8)Optional
      The state, country, or province name.
      cityString(32)Optional
      The city, district, suburb, town, or village name.
      address1String(256)Optional
      Address line 1, for example, the stress address/PO box/company name
      address2String(256)Optional
      Address line 2, for example, the apartment/suite/unit/building informaiton
      zipCodeString(32)Optional
      ZIP or postal code
      merchantRegisterDateDateOptional

      Merchant registration date, which follows the ISO 8601 standard.

      storeStoreRequired

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

      referenceStoreIdString(64)Required
      The unique store ID assigned by the merchant that owns the store
      storeNameString(512)Required
      Name of the store
      storeMCCString(32)Required
      Store business category code
      storeDisplayNameString(64)Optional
      Display name of the store
      storeAddressAddressOptional

      Address of the store

      regionString(2)Required

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

      stateString(8)Optional
      The state, country, or province name.
      cityString(32)Optional
      The city, district, suburb, town, or village name.
      address1String(256)Optional
      Address line 1, for example, the stress address/PO box/company name
      address2String(256)Optional
      Address line 2, for example, the apartment/suite/unit/building informaiton
      zipCodeString(32)Optional
      ZIP or postal code
      envEnvOptional

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

      terminalTypeEnumOptional

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

      • WEB: The terminal type of the merchant side is a website.
      • WAP: The terminal type of the merchant side is an H5 page on the mobile phone.
      • APP: The terminal type of the merchant side is an app on the mobile phone.

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

      osTypeEnumOptional

      OS type. Possible values are:  

      • IOS 
      • ANDROID 

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

      userAgentString(1024)Optional
      The user agent
      deviceTokenIdString(64)Optional
      Token identifier of the device
      clientIpString(32)Optional
      IP of the client device
      cookieIdString(64)Optional
      The cookie ID of the buyer
      storeTerminalIdString(64)Optional

      Store terminal ID.   

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

      storeTerminalRequestTimeDatetimeOptional

      The time that the request is sent by the store terminal, which follows the ISO 8601 standard.   

      Note: This field must be accurate to milliseconds. Besides, this field is required for the consumer-presented mode payment and order code payment. If you don't have the terminal request time, use the gateway time for this field.

      extendInfoString(2048)Optional
      Extended information
      extendInfoStringOptional

      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.

      businessTypeString(16)Required

      The business type. Supported values are

      1: Hotel

      2: Air Flight

      3: Study Abroad

      4: Trade

      5: Other 

      Multiple business types are delimited with '|'.

      flightNumberString(1000)Optional

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

      departureTimeString(1000)Optional

      The flight departure time. Format as yyyy-MM-dd HH:mm. Multiple flight departure times are delimited with '|'.when businessType=2, you should pass the value.

      hotelNameString(1000)Optional

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

      checkinTimeString(1000)Optional

      The hotel check-in time. Format: yyyy-MM-dd. Timezone: UTC+8

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

      checkoutTimeString(1000)Optional

      The hotel checkout time. Format: yyyy-MM-dd. Timezone: GMT +8.

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

      admissionNoticeUrlString(1000)Optional

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

      goodsInfoString(2000)Optional

      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 vertical bar (|). Specify this field only when business_type is 4 (Sales of goods).when businessType=4, you should pass the value.

      totalQuantityString(8)Optional

      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.

      paymentAmountAmountRequired

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

      currencyString(3)Required

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

      valueString(16)Required
      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).
      payToMethodPaymentMethodRequired

      Account asset identification for merchant settlement.

      paymentMethodTypeString(32)Required

      Payment method type:

      For in-store payments, the value is CONNECT_WALLET.

      paymentMethodIdString(128)Required
      The unique ID of the payment method that belongs to a buyer.
      paymentMethodMetaDataString(2048)Optional
      Other information about payment methods, which are key-value pairs in JSON format
      customerIdString(32)Optional
      The unique ID to identify a buyer
      extendInfoString(2048)Optional
      Extended information
      paymentMethodPaymentMethodRequired

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

      paymentMethodTypeString(32)Required

      Payment method type:

      For in-store payments, the value is CONNECT_WALLET.

      paymentMethodIdString(128)Optional
      The unique ID of the payment method that belongs to a buyer.
      paymentMethodMetaDataString(2048)Optional
      Other information about payment methods, which are key-value pairs in JSON format
      customerIdString(32)Optional
      The unique ID to identify a buyer
      extendInfoString(2048)Optional
      Extended information
      paymentExpiryTimeDatetimeOptional

      A specific time, after which the payment will not succeed. The value follows the ISO 8601 standard.

      paymentRedirectUrlURLOptional
      The URL that the user is redirected to after the payment is completed
      paymentNotifyUrlURLRequired
      The URL that is used to receive the payment result notification
      isAuthorizationBooleanOptional
      This parameter indicates whether the request is a payment authorization.
      paymentVerificationDataPaymentVerificationDataOptional

      Payment verification information

      verifyRequestIdString(64)Required

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

      authenticationCodeString(64)Required
      Verification code
      paymentFactorPaymentFactorOptional

      Specifies the payment scenario

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

      Indicates the payment scenario of in-store payments. Possible values of inStorePaymentScenario 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

      resultResultRequired

      The request result, which contains information related to the request result, such as status and error codes.

      resultCodeString(16)Required
      Result code
      resultStatusEnumRequired

      Result status. Possible values are:   

      • S: Indicates that the result status is successful. 
      • F: Indicates that the result status is failed. 
      • U: Indicates that the result status is unknown.
      resultMessageString(64)Optional
      Result message
      paymentRequestIdString(64)Optional
      The unique ID that is assigned by a merchant to identify a payment request. Special characters are not supported.
      paymentIdString(64)Optional
      The unique ID that is assigned by Alipay to identify a payment
      paymentAmountAmountRequired

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

      currencyString(3)Required

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

      valueString(16)Required
      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).
      paymentTimeDatetimeOptional

      The date and time when the payment reaches a final state of success or failure, which follows the ISO 8601 standard.

      paymentCreateTimeDatetimeOptional

      The date and time when the payment is created, which follows the ISO 8601 standard.

      authExpiryTimeDatetimeOptional

      Authorization expiration time, which follows the ISO 8601 standard.

      pspCustomerInfoPspCustomerInfoOptional

      PMP customer information.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      pspNameString(64)Optional

      The name of PMP.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      pspCustomerIdString(64)Optional

      The customer ID of PMP.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      displayCustomerIdString(64)Optional
      The customer ID used for display. For example, loginId
      challengeActionFormChallengeActionFormOptional

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

      challengeTypeEnumRequired

      Type of challenge. Possible values are: 

      • SMS_OTP: SMS OTP verification
      • PLAINTEXT_CARD_NO: Plain text card number challenge 
      • CARD_EXPIRE_DATE: Card expiry date challenge
      challengeRenderValueString(64)Required
      The actual render value
      triggerSourceEnumRequired

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

      • AMS: Describes the challenge that is required by Alipay.
      • CHANNEL: Describes the challenge that is required by the external party.
      extendInfoString(2048)Optional
      Extended information
      redirectActionFormRedirectActionFormOptional

      Provides information about the redirection action.

      methodEnumRequired

      Indicates the method type. Possible 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.
      parametersString(2048)Optional
      Parameteres required for the HTTP method in the key-value pair
      redirectUrlUrl(1024)Required
      The URL where the user is redirected to
      orderCodeFormOrderCodeFormOptional

      Provides information about the order code.

      paymentMethodTypeString(64)Optional

      Payment method type. Possible values are: 

      • ALIPAY_CN: Alipay CN wallet 
      • CONNECT_WALLET: Connect 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. 
      • 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.
      expireTimeDatetimeOptional
      Expiry time of the order code information
      codeDetailsList<CodeDetail>Required

      Details about the code

      codeValueTypeEnumRequired

      Code type. Possible values are: 

      • BARCODE: Indicates a bar code. 
      • QRCODE: Indicates a QR code.
      codeValueString(2048)Required
      Code value
      displayTypeEnumRequired

      Indicates the way to show the code. Possible 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.
      extendInfoString(2048)Optional
      Extended information
      grossSettlementAmountAmountOptional

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

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

      currencyString(3)Required

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

      valueString(16)Required
      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).
      settlementQuoteQuoteOptional

      The exchange rate between the settlement currency and transaction currency at the time of 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.

      quoteIdString(64)Optional
      The unique ID to identify a quote.
      quoteCurrencyPairString(16)Required
      Pair of currency exchange rate
      quotePriceDecimal(20)Required
      Rate quotation, decimal point that follows market quotation
      quoteStartTimeDatetimeOptional

      Effective time of the exchange rate, which follows the ISO 8601 standard

      quoteExpiryTimeDatetimeOptional

      Expiration time of the exchange rate, which follows the ISO 8601 standard

      guaranteedBooleanOptional
      Guaranteed exchange rate is available for payment

      More information 

      This section gives additional information about certain 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.

      • paymentRequestId:
      The unique ID that is assigned by a merchant to identify an payment request. Alipay uses this field for idempotence control. For example, if a payment request has been successfully processed and the merchant submits a new request with the same paymentRequestId, Alipay returns the previous payment result.

      • 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.
      In this case, order.merchant.referenceMechantId, order.merchant.merchantMCC, order.merchant.store.referenceStoreId, and order.merchant.store.storeMcc are mandatory. It is recommended to specify order.env.storeTerminalRequestTime and order.env.storeTerminalId.

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

      • paymentMethod:
      The value of paymentMethod is CONNECT_WALLET, indicating that Alipay collects money from the user's payment code that was generated by Alipay.

      • paymentMethodId:
      The unique identifier of the user's payment asset, which can be obtained by using the Access Token Application interface. For User-presented Mode Payments, this field is required and can be used by merchant to decide which payment service is to be called to process the payment. See Payment Code Specification for more information.

      • 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 time is then decided by the payment executor.

      • paymentFactor:
      The value of paymentFactor.inStorePaymentScenario is PaymentCode, indicating that the payment code is used for payment.

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

      Payment code specifications

      An Alipay payment code is a number of 16 to 24 digits and starts with a number ranging from 25 to 30.

      For user-presented code payments, use the following rules to determine which payment service is to be called：

      • If an Alipay payment code is used for payment, the merchant needs to route the payment to Alipay.
      • If a non-Alipay payment code is used for payment, the merchant needs to route the payment to the corresponding payment provider of the non-Alipay payment code.
      • If a merchant that is integrated with Alipay has integrated with other local wallets that provide payment codes conforming to Alipay payment code rule, for example, the Macao Wallet, or the PayPay wallet, the merchant needs to route the payment to the local wallet system when payment codes from such local wallets are used, or to route the payment to Alipay when Alipay payment codes are used. To determine the payment code belongs to Alipay or the local wallet, use the following rules: 

      Asia

      Result process logic

      After calling a payment interface, the following results might be returned from Alipay or no result is received by the merchant:

      • Alipay returns that result.resultStatus is S, which indicates the transaction succeeds and the money is deducted successfully.
      • Alipay returns that result.resultStatus is F, the merchant needs to take further actions according to the error message in result.resultCode.
      • Alipay returns that result.resultStatus is U, the merchant needs to use the inquiry interface to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of 3 seconds.
      • If no asynchronous notification and payment result are returned from Alipay within 5 seconds after the payment request is sent, the merchant needs to use the inquiry interface to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of 3 seconds.
      • When calling the inquiry interfaces, if no payment result can be obtained after the inquiry requests being sent more than the maximum number of times, the merchant needs to call the cancel interface to cancel the transaction. If being out of the cancellable period, the merchant cannot use the cancel interface to cancel the transaction. The merchant can call the refund interface to make a refund instead. 

      Result/Error codes

      CodeValueMessage
      SUCCESSSSuccess
      INVALID_CONTRACTFThe contract is invalid.
      INVALID_CODEFThe code is invalid.
      INVALID_ACCESS_TOKENFThe access token is invalid.
      USER_NOT_EXISTFThe user does not exist.
      CURRENCY_NOT_SUPPORT FThe currency is not supported.
      USER_BALANCE_NOT_ENOUGHFThe user balance is not enough for the payment.
      USER_STATUS_ABNORMALFThe user status is abnormal.
      NO_PAY_OPTIONFThis is not a valid payment option.
      ORDER_IS_CANCELEDFThe order is canceled.
      EXPIRED_CODEFThe code is expired.
      PAYMENT_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the limit.
      PAYMENT_COUNT_EXCEED_LIMITFThe number of payments exceeds the limit.
      REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.
      PARAM_ILLEGALFIllegal parameters exist. For example, a non-numeric input, or an invalid date.
      USER_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the user payment limit.
      RISK_REJECTFThe request is rejected because of the risk control.
      PROCESS_FAILFA general business failure occurred. Do not retry.
      KEY_NOT_FOUNDFThe key is not found.
      ACCESS_DENIEDFAccess denied
      REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
      API_INVALIDFAPI is invalid or not active.
      CLIENT_INVALIDFThe client is invalid.
      SIGNATURE_INVALIDFThe signature is invalid.
      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.
      MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
      PAYMENT_IN_PROCESSUThe payment is being processed.
      UNKNOWN_EXCEPTIONUAn API calling is failed, which is caused by unknown reasons.
      PAYMENT_NOT_QUALIFIEDFThe merchant is not qualified to pay because the merchant is not registered, does not have contract for auto debit payment, or is forbidden to make a payment.
      ORDER_NOT_EXISTFThe order does not exist.
      ORDER_IS_CLOSEDFThe order is closed, which might be caused by payment expiration.
      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