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

      alipay.acquire.create

      Call this interface to create a payment transaction.

      #Request

      #Service address

      Environment

      HTTPS request URL

      Production environment

      Priority: https://globalmapi.alipay.com/gateway.do

      Backup: https://intlmapi.alipay.com/gateway.do

      Test environment

      https://mapi.alipaydev.com/gateway.do

      Note:

      If you use POST method, please specify _input_charset in the request URL.

      For example: https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

      #Request parameters

      ParameterDescription
      Basic parameter

      service

      String Required

      Interface name 

      Example:alipay.acquire.create

      partner

      String(16) Required

      The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088. 

      Example:2088*********662

      _input_charset

      String(10) Required

      The charset with which the request data are encoded. UTF-8, GBK, and GB2312 are supported. 

      Example:UTF-8

      sign_type

      String Required

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

      Example:MD5

      sign

      String Required

      Sign value 

      Example:97ef60dd5015aa311058fcaf2d2ac8e3

      notify_url

      URL(200) Required

      The URL for receiving asynchronous notifications after the payment is completed.

      Example:https://www.test.com/alipay/notify_url.php

      timestamp

      String Required

      The time when the merchant server sends the request. The time is in GMT+8, with a format of yyyy-MM-dd HH:mm:ss. By default, the request expires in 30 minutes.

      Example:2018-03-22 12:23:21

      terminal_timestamp

      String

      The time when the terminal sends the request. The value is accurate to the millisecond.

      Example:2018-03-22 12:23:21

      Business parameter

      out_trade_no

      String(64) Required

      The unique serial number to identify a transaction in partner system. The number can contain letters, digits, and underscores. 

      Example:990xxxxxxx8989

      subject

      String(256) Required

      Brief description of the transaction. Special characters are not supported.

      Note: The value of this field will be displayed to customers.

      Example:kids clothing

      product_code

      String(32) Required

      Product code of the Alipay product that you use, which is specified in the contract you signed with Alipay.

      Example:OVERSEAS_MBARCODE_PAY

      total_fee

      Number(11,2) Required

      Total amount of a transaction in trans_currency. The CNY amount the user actually pays is converted from the value of this parameter.

      Example:100.30

      seller_id

      String(30)

      Unique Alipay user ID of the seller, contains 16 digits and begins with 2088. If both seller_email and seller_id are null, use the partner ID as the default value.

      Example:2088101106499364

      seller_email

      String

      Alipay ID of the seller, can be email or phone number. If the seller_id is not null, the seller_id is the seller’s Alipay ID and ignore the seller_email.

      Example:tianc001@alipay.com

      buyer_id

      String(30)

      The unique Alipay user ID of the buyer corresponding to the signed Alipay account. The ID contains 16 digits and begins with 2088. The buyer_id and the buyer_email cannot be null at the same time. 

      Example:2088002007018955

      buyer_email

      String

      The buyer Alipay account. If both buyer_email and buyer_id are null, use the buyer ID as the default value.

      Example:t********@alipay.com

      body

      String(400)

      Detailed description about the goods. Special characters are not supported. 

      Example:Glitter leggings

      show_url

      String(400)

      The hyperlink for showing goods on the webpage of the checkout counter. 

      Example:http://www.taobao.com/product/113714.html

      currency

      String(10) Required

      The currency used for labelling the price of the transaction and also the settlement currency that the merchant specifies in the contract. Use upper case. For more information about supported currencies, see Supported Currencies.

      Example:USD

      price

      Number

      Goods prices, which is accurate to 2 digits after the decimal point. The unit is RMB. 

      Example:100.30

      quantity

      Number

      The quantity of goods 

      Example:1

      goods_detail

      String

      Details about the goods, which is in the format of JSON. The maximum number of goods for this field is 50. For more information, see goods_detail. 

      Example:[{"goodsId":"apple-01","goodsName":"ipad","goodsCategory":"7788230","price":"2000.00","qu antity":"1"}]

      extend_params

      String(512) Required

      This parameter contains extended parameters of the request, and transmits business information of the merchant. Format: JSON. See extend_params for details. 

      Example:{"secondary_merchant_name":"Lotte", "secondary_merchant_id":"123", "secondary_merchant_industry":"5812","store_id":"A101","store_name":"McDonald in 966 3rd Ave, New York","terminal_id":"212133131" }

      it_b_pay

      String(200)

      Specifies the expiration time of unpaid transactions. The trade is closed automatically once the time is up. The value of this field is in the range of 1m - 15d or can be an absolute time such as 2014-06-13 16:00:00.

      Notes:

      1. The following abbreviations are used to present units of time:
      • m: minute
      • h: hour
      • d: day
      • c: current day (Whenever the trade is created, it will be closed at 0:00).
      1. Decimal point of the numerical value of this parameter is rejected, for example, 1.5h need to be transformed to 90m.

      Example:1d

      passback_parameters

      String(256)

      The response parameters returned to the merchant in a JSON format after the payment succeeds. Merchants can define the parameters. 

      Example:{"inner_trade_no":"100000001"}

      trans_currency

      String Required

      Pricing currency for the transaction. Use uppercase. For more information about supported currencies, see Supported Currencies. 

      Example:TWD

      #goods_detail

      ParameterDescription

      goodsId

      String Required

      Goods ID

      Example:apple-01

      goodsName

      String Required

      Goods name 

      Example:ipad

      goodsCategory

      String

      Goods category 

      Example:34543238

      showUrl

      String

      Hyperlink for the show of goods on the webpage of checkout counter.

      Example:http://www.taobao.com

      quantity

      Number Required

      The quantity of goods 

      Example:1

      body

      String(400)

      Detailed description about the goods. Special characters are not supported.

      Example:Glitter leggings

      price

      Number Required

      Goods prices, which is accurate to 2 digits after the decimal point. The unit is RMB.

      #extend_params

      ParameterDescription

      secondary_merchant_id

      String(32)  Required

      The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.

      Example:A80001

      secondary_merchant_name

      String Required

      Registration legal name of the secondary merchant. Can be null only in cross-border agency acquiring mode when the name is verified.

      Example:Apple

      secondary_merchant_industry

      String(4) Required

      Industry classification identifier of the secondary merchant, which is assigned by Alipay. For more information about the MCC code, see MCC list.

      Example:5123

      store_name

      String Required

      The store name. Can be null only when the store information is verified. 

      Example:Apple store

      store_id

      String(32) Required

      The unique ID that is assigned by the partner to identify a store of a merchant, which can contain letters, numbers, and underscores. 

      Example:S123

      terminal_id

      String

      Terminal ID 

      Example:T123

      sys_service_provider_id

      String(32)

      System service provider ID, which is used to identify the payment system provider. 

      Example:R00998889911


      Note:

      The decimal place accuracy of amounts, such as the values of total_fee and price, depends on the value of currency. If the value of currency isJPY, then the amount must be an integer. For example, 100 JPY. For other currencies, the amount is of two decimal place accuracy. For example, 100.00 USD. Amounts in other formats will cause error, for example, 100.999 USD.

      #Response

      #Synchronous response

      ParameterDescription
      Basic parameter

      is_success

      String Required

      Indicates whether the request succeeds or not, with a value of T for success and F for failure.

      Note: a successful request does not mean the business is accepted and processed successfully. 

      Example:T

      sign

      String

      Sign value 

      Example:97ef60dd5015aa311058fcaf2d2ac8e3

      sign_type

      String

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

      Example:MD5

      error

      String(48)

      Error code that is returned when the request is unsuccessful, to describe the request failure reason. For more information, see the Error Code section in this document.

      Example:REPEATED_REFUNDMENT_REQUEST

      Business parameter

      result_code

      String(32) Required

      Processing result of the transaction request, with a value of SUCCESS to indicate the transaction is successful, FAIL to indicate the transaction is failed, or UNKNOWN to indicate an unknown result.

      Example:SUCCESS

      trade_no

      String(64)

      The unique transaction ID in Alipay system, with a length in the range 16 - 64.

      Example:2015070800001000100080029361

      out_trade_no

      String(64)

      The unique serial number to identify a transaction in partner system. The number can contain letters, digits, and underscores. 

      Example:990xxxxxxx8989

      m_discount_forex_amount

      Number(9,2)

      If coupons/vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return. 

      Example:2.19

      detail_error_codeString(48)

      Reason of the returned response code. If the response code of result_code is SUCCESS, this parameter is not returned. For more information about the value of detail_error_code, see the Error Code section. 

      Example:TRADE_STATUS_ERROR

      detail_error_des

      String(46)

      Explanation of the detailed error code. If result_code is SUCCESS, this parameter is not returned.

      Example:Trade status is illegal.

      #Asynchronous response

      ParameterDescription
      Basic parameter

      notify_time

      Timestamp Required

      The time when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss. 

      Example:2013-11-27 15:45:58

      notify_type

      String Required

      Notification type

      Example:trade_status_sync

      notify_id

      String Required

      Notification ID 

      Example:ac05099524730693a8b330c5ecf72da978

      sign_type

      String Required

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

      Example:MD5

      sign

      String Required

      Sign value 

      Example:601510b7970e52cc63db0f44997cf70e

      notify_action_type

      String

      Notification action type. The value can be one of the following items:

      • createDirectPayTradeByBuyerAction: Create a transaction
      • payByAccountAction: Make the payment
      • refundFPAction: Make the refund
      • reverseAction: Cancel the transaction
      • closeTradeAction: Close the transaction
      • finishFPAction: Complete the transaction

      Example:payByAccountAction

      Business parameter

      out_trade_no

      String

      Unique order ID in the order system in corresponding merchant's website other than Alipay trade number. Uniqueness of this parameter in merchant's website shall be guaranteed.

      Example:990xxxxxxx8989

      subject

      String(256)

      Brief description of the transaction. This parameter is in the first column of Alipay trade details and is important for account checking. This parameter is transmitted by the corresponding request and needs to be returned with its original value.

      Example:kids clothing

      trade_no

      String

      The serial number of the trade in Alipay system

      Example:2013112711001004940000394507

      trade_status

      String

      Transaction status. See Trade status for details.

      Example:WAIT_BUYER_PAY

      gmt_create

      Date

      The time when the trade transaction is created. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8. 

      Example:2013-11-27 15:45:57

      gmt_payment

      Date

      The time when the payment is completed. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8. 

      Example:2013-11-27 15:45:57

      seller_email

      String

      Alipay ID of the seller, with a format of email address or phone number

      Example:zhuzhanghu@alitest.com

      buyer_email

      String

      Buyer’s Alipay ID, which can be an email address or phone number. 

      Example:138*****011

      seller_id

      String

      Seller's unique Alipay user ID, which consists of 16 digits and begins with 2088.

      Example:2088101106499364

      buyer_id

      String

      Buyer's unique Alipay user ID consists of 16 digits and begins with 2088.

      Example:2088102105236945

      price

      Number

      Goods price. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

      Example:1.00

      quantity

      Number

      The quantity of goods. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

      Example:10

      total_fee

      Number

      Total transaction amount in CNY, converted from the value of total_fee in the request

      Example:10.00

      body

      String(400)

      Detailed description about the goods. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

      Example:Glitter leggings

      refund_fee

      Number

      The refund amount. The unit is Yuan. 

      Example:1.00

      out_biz_no

      String

      Merchant's business ID, which is the serial number of the refund request in the refund notification for most cases.

      Example:HZRF001

      paytools_pay_amount

      String

      Payment amount information of all successful payments in various channels. 

      Example:[{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}]

      extra_common_param

      String

      This parameter is returned with the value of passback_parameters in the corresponding request. 

      Example:{"qrcode":"https://qr.alipay.com/9446219319446735"}

      m_discount_forex_amount

      Number

      If coupons/vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return. 

      Example:2.19


      #paytools_pay_amount

      ParameterDescription

      ALIPAYACCOUNT

      String

      The money amount paid by the balance of Alipay account. The unit is Yuan. 

      Example:1.23

      MCARD

      String

      The money amount paid by the merchant's prepaid card. The unit is Yuan.

      Example:7.94

      MDISCOUNT

      String

      The money amount paid by the merchant's discount coupon. The unit is Yuan. 

      Example:1.23

      TMPOINT

      String

      The money amount paid by the Tmall points. The unit is Yuan.

      Example:1.69

      COUPON

      String

      The money amount paid by coupons. The unit is Yuan.

      Example:1.23

      POINT

      String

      The money amount paid by points. The unit is Yuan. 

      Example:1.23

      DISCOUNT

      String

      The money amount paid by the discount. The unit is Yuan. 

      Example:1.23

      BANKCARD

      String

      The money amount paid by the money fund. The unit is Yuan.

      Example:5.55

      MONEYFUND

      String

      The money amount paid by the money fund. The unit is Yuan.

      Example:1.23

      BAITIAO

      String

      The money amount paid by BAITIAO. The unit is Yuan. 

      Example:1.23

      PCARD

      String

      The money amount paid by the Alipay card. The unit is Yuan.

      Example:2.13

      PCREDIT

      String

      The money amount paid by the consumption credit card. The unit is Yuan.

      Example:1.23

      MCOUPON

      String

      The money amount paid by the merchants issued coupons. The unit is Yuan. 

      Example:2.21

      #Error codes

      #Business errors

      Error code

      Description

      TRADE_SETTLE_ERROR

      Settlement verification fails.

      TRADE_BUYER_NOT_MATCH

      The buyer doesn’t match.

      CONTEXT_INCONSISTENT

      The trade context is inconsistent.

      TRADE_HAS_SUCCESS

      The trade is already paid.

      TRADE_HAS_CLOSE

      The trade is closed.

      REASON_ILLEGAL_STATUS

      The trade status is illegal.

      EXIST_FORBIDDEN_WORD

      Forbidden words exist in the order information.

      ACCESS_FORBIDDEN

      No access to use this product.

      SELLER_NOT_EXIST

      The seller doesn’t exist.

      BUYER_NOT_EXIST

      The buyer doesn’t exist.

      BUYER_ENABLE_STATUS_FORBID

      The trade is forbidden because the buyer’s status is illegal.

      BUYER_SELLER_EQUAL

      The trade is forbidden because the seller and the buyer’s ID is the same.

      INVALID_PARAMETER

      The parameter is invalid.

      INVALID_RECEIVE_ACCOUNT

      The seller’s account is not in the list of valid receivers.

      ERROR_BUYER_CERTIFY_LEVEL_LIMIT

      The buyer account not certified.

      ERROR_SELLER_CERTIFY_LEVEL_LIMIT

      The seller account not certified.

      SELLER_BEEN_BLOCKED

      The seller’s account is blocked.

      BEYOND_PER_RECEIPT_RESTRICTION

      The amount that the seller receives is beyond the up limit of that month.

      TOTAL_FEE_EXCEED

      The amount of the order is beyond the limit.

      BUYER_PAYMENT_COUNT_DAY_LIMIT_ERROR

      The buyer’s number of payment is beyond the limit of one day.

      BUYER_PAYMENT_COUNT_MONTH_LIMIT_ERROR

      The The buyer’s number of payment is beyond the limit of one month.

      TRADE_STATUS_ERROR

      Trade status error.

      BUYER_PAYMENT_AMOUNT_MONTH_LIMIT_ERROR

      The The buyer’s amount of payment is beyond the limit of one month.

      PRODUCT_AMOUNT_LIMIT_ERROR

      The amount of the product is beyond the limit.

      DUPLICATE_PAY_CURRENCY_NOT_EQUAL

      The currency is inconsistent.

      USER_LOGONID_DUP

      Can’t do the payment or receipt because the account name of your phone is duplicated. We suggest you to inform he/she to modify the account name and update his/her account name after you check together.

      EXCHANGE_AMOUNT_OR_CURRENCY_ERROR

      The currency of the price or of the settlement is not supported.

      BUYER_ENABLE_STATUS_FORBID

      The buyer’s status is illegal, mostly it’s because the buyer’s certification level is not enough.

      SECONDARY_MERCHANT_ID_BLANK

      The secondary merchant ID is not provided to Alipay.

      SECONDARY_MERCHANT_ID_INVALID

      The secondary merchant is not registered with Alipay.

      STORE_NOT_MATCH

      The secondary merchant is not registered with Alipay.

      SECONDARY_MERCHANT_STATUS_ERROR

      The status of secondary merchant is abnormal in the Alipay system.

      #Access errors

      Error code

      Description

      ILLEGAL_SIGN

      Illegal signature.

      ILLEGAL_DYN_MD5_KEY

      Dynamic key information is incorrect.

      ILLEGAL_ENCRYPT

      Encryption is incorrect.

      ILLEGAL_ARGUMENT

      Parameter is incorrect.

      ILLEGAL_SERVICE

      Service parameter is incorrect.

      ILLEGAL_USER

      User ID is incorrect.

      ILLEGAL_PARTNER

      Partner ID is incorrect.

      ILLEGAL_EXTERFACE

      Interface configuration is incorrect.

      ILLEGAL_PARTNER_EXTERFACE

      Partner’s interface information is incorrect.

      ILLEGAL_SECURITY_PROFILE

      Matching private key configuration has not been found.

      ILLEGAL_AGENT

      Agency ID is incorrect.

      ILLEGAL_SIGN_TYPE

      The signature type is incorrect.

      ILLEGAL_CHARSET

      The character set is illegal.

      HAS_NO_PRIVILEGE

      Has no right to visit.

      INVALID_CHARACTER_SET

      The character set is invalid.

      #System errors

      Error code

      Description

      SYSTEM_ERROR

      Alipay system error

      SESSION_TIMEOUT

      Session timeout

      ILLEGAL_TARGET_SERVICE

      Wrong  target_service

      ILLEGAL_ACCESS_SWITCH_SYSTEM

      Merchant is not allowed to visit system of this type.

      EXTERFACE_IS_CLOSED

      The interface has been closed.

      #Samples

      #Request

      https://intlmapi.alipay.com/gateway.do?operator_id=sky&subject=%E5%88%86%E8%B4%A6%E6%B5%8B%E8%AF%95-sky&sign_type=MD5&notify_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_notify.htm&out_trade_no=205211376305670&sign=9aae99502a8dd70e67d3d3575f7176cd&_input_charset=UTF-8&price=0.01&it_b_pay=1d&product_code=OVERSEAS_MBARCODE_PAY&total_fee=0.01&service=alipay.acquire.create&seller_id=2088101106499364&quantity=1&partner=2088101106499364&extend_params=%7B%22STORE_ID%22%3A%22323231%22%2C%22STORE_TYPE%22%3A%221%22%7D&alipay_ca_request=2&ref_ids=%5b%7b%26quot%3bid_type%26quot%3b%3a%26quot%3borig_out_request_no%26quot%3b%2c%26quot%3bid%26quot%3b%3a%26quot%3bHZ0001%26quot%3b%7d%2c%7b%26quot%3bid_type%26quot%3b%3a%26quot%3borig_out_order_no%26quot%3b%2c%26quot%3bid%26quot%3b%3a%26quot%3bHZ0001%26quot%3b%7d%5d


      #Response

      #Synchronous response

      Business acceptance is normal and query is successful:

      copy
      <?xml version="1.0" encoding="utf-8"?> 
      <alipay> 
          <is_success>T</is_success> 
          <request> 
              <param name="body">Jewellery</param> 
              <param name="operator_id">8888</param> 
              <param name="subject">test</param> 
              <param name="sign_type">MD5</param> 
              <param name="out_trade_no">3618810634349901</param>
              <param name="total_fee">20.00</param> 
              <param name="partner">2088101126765726</param> 
              <param name="quantity">2</param> 
              <param name="alipay_ca_request">2</param> 
              <param name="sign">42fff1757f72510e2027bf03879f03a9</param> 
              <param name="goods_detail"> 
      [{"goodsName":"ipad","price":"2000.00","quantity":"1"},{"goodsName":"ipad2","price":"2000.00", "quantity":"1"}]</param> 
              <param name="_input_charset">UTF-8</param> 
              <param name="price">10</param> 
              <param name="it_b_pay">50m</param> 
              <param name="product_code">WAP_CREATE_TRADE</param> 
              <param name="service">alipay.acquire.create</param> 
              <param name="seller_id">2088101126765726</param> 
              <param name="seller_email">yuezhuzhanghu@alitest.com</param> 
              <param name="extend_params">{"STORE_ID":"323231","STORE_TYPE":"1"}</param> 
          </request> 
              <response> 
              <alipay> 
                  <out_trade_no>6409624505322427</out_trade_no> 
                  <trade_no>2013111811001004410070187794</trade_no> 
                  <result_code>SUCCESS</result_code> 
              </alipay> 
          </response> 
          <sign>97ef60dd5015aa311058fcaf2d2ac8e3</sign> 
          <sign_type>MD5</sign_type> 
      </alipay>


      Request succeeds, but the business processing falis:

      copy
      <?xml version="1.0" encoding="utf-8"?> 
      <alipay> 
          <is_success>T</is_success> 
          <request> 
              <param name="body">Jewellery</param> 
              <param name="operator_id">8888</param> 
              <param name="subject">test</param> 
              <param name="sign_type">MD5</param> 
              <param name="out_trade_no">3618810634349901</param>
              <param name="total_fee">20.00</param> 
              <param name="partner">2088101126765726</param> 
              <param name="quantity">2</param> 
              <param name="alipay_ca_request">2</param> 
              <param name="sign">42fff1757f72510e2027bf03879f03a9</param> 
              <param name="goods_detail"> 
      [{"goodsName":"ipad","price":"2000.00","quantity":"1"},{"goodsName":"ipad2","price":"2000.00", "quantity":"1"}]</param> 
              <param name="_input_charset">UTF-8</param> 
              <param name="price">10</param> 
              <param name="it_b_pay">50m</param> 
              <param name="product_code">WAP_CREATE_TRADE</param> 
              <param name="service">alipay.acquire.create</param> 
              <param name="seller_id">2088101126765726</param> 
              <param name="seller_email">yuezhuzhanghu@alitest.com</param> 
              <param name="extend_params">{"STORE_ID":"323231","STORE_TYPE":"1"}</param> 
          </request> 
          <response> 
              <alipay> 
                  <result_code>FAIL</result_code> 
                  <detail_error_code>TRADE_BUYER_NOT_MATCH</detail_error_code> 
                  <detail_error_des>Buyer not matched</detail_error_des> 
              </alipay> 
          </response> 
          <sign>97ef60dd5015aa311058fcaf2d2ac8e3</sign> 
          <sign_type>MD5</sign_type> 
      </alipay>


      Request fails or the request data are incorrect:

      copy
      <?xml version="1.0" encoding="utf-8"?> 
      <alipay> 
          <is_success>F</is_success> 
          <error>ILLEGAL_SIGN</error> 
      </alipay>


      #Asynchronous response

      http://some_domain/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_emai