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

      alipay.commerce.qrcode.create

      Call this interface to generate a merchant QR code. For one store ID, up to two merchant QR codes can be created, one with the commission charge and the other not. If you call this interface again after two merchant QR codes being created, the data of an existing merchant QR code are returned.

      #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.commerce.qrcode.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 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:5d479b28fac070e8e5a935685a3b7611

      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.

      Example:2012-12-21 17:11:16

      notify_url

      URL(200)

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

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

      Business parameter

      biz_type

      String Required

      Business type that is defined by Alipay, with a value of OVERSEASHOPQRCODE 

      Example:OVERSEASHOPQRCODE

      biz_data

      String(2000) Required

      Business data, which are in the JSON format. 

      Example:{"secondary_merchant_industry":"5311","secondary_merchant_id":"13xxx20","secondary_merchant_name":"Mika's coffee shop","store_id":"1993","store_name":"Mika's coffee shop","trans_currency":"USD","currency":"USD","country_code":"US","address":"6229 Hillcrest Rd, Dallas, TX 75205","notify_sign_type":"RSA","notify_charset":"UTF-8"}

      #biz_data

      ParameterDescription

      secondary_merchant_industry

      String(4) Required

      Business category code of the secondary merchant. For more information about the business category code, see MCC list.

      Example:7011

      secondary_merchant_id

      String(64) Required

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

      Example:xxx001

      secondary_merchant_name

      String(64) Required

      Registration legal name of the secondary merchant, shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant. 

      Example:xxx Store

      store_id

      String(64) Required

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

      Note: This field is optional for the taxi business (MCC=4121). 

      Example:0001

      store_name

      String Required

      Store name.

      Note: This field is optional for the taxi business (MCC=4121). 

      Example:Apple store

      taxi_operation_id

      String

      Taxi operation ID, which is compulsory for the taxi business (MCC=4121). 

      Example:Xxx001

      taxi_number

      String

      Taxi number, which is compulsory for the taxi business (MCC=4121). 

      Example:S A88888

      taxi_driver_name

      String

      Taxi driver name, which is compulsory for the taxi business (MCC=4121) and is to be used in the transaction history of Alipay wallet. 

      Example:John

      taxi_driver_mobile

      String

      Mobile number of the taxi driver, which is compulsory for the taxi business. (MCC=4121) 

      Example:13888888888

      trans_currency

      String Required

      The pricing currency. Use the same value for this parameter and currency parameter. Contact Alipay technical support if you have to use different values. Use upper case.

      Example:USD

      currency

      String Required

      The settlement currency that the merchant specifies in the contract. Use upper case. For more information about supported currencies, see Supported Currencies.

      Example:USD

      sys_service_provider_id

      String

      System service provider ID. Can't be modified.

      Example:xxx001

      channel_fee

      String

      Channel fee. For more information, see channel_fee.

      Note: If this field exists when the QR code is created, this field cannot be deleted when the QR code is modified. This field is in a format of JSON.

      Example:See channel_fee

      country_code

      String Required

      The country code that consists of two letters (alpha-2 code). Refer to ISO 3166-1 for details. 

      Example:CN

      address

      String Required

      The address of the store where the code is created. Use postal address format. 

      Example:No.278, Road YinCheng, Shanghai, China

      passback_parameters

      String

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

      Note: Nested JSON is not supported. 

      Example:{"inner_trade_no":"100000001"}

      notify_mobile

      String

      Phone number of the merchant legal representative.

      Example:+86 15XXXXX2012

      notify_wangwang

      String

      Wangwang name of the merchant legal representative

      Example:ZiBei

      notify_alipay_account

      String

      Alipay account of the merchant legal representative

      Example:136XXXXXXXX

      is_show_memo

      String(10)

      Indicates whether the payment page shows the memo field, with a value of true or false. The default value is false.

      Example:true

      notify_sign_type

      String(10)

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

      Example:RSA

      notify_charset

      String

      The charset with which the payment result notification is encoded. The default value is GBK. 

      Example:GBK

      Sample biz_data

      copy
      {        "channel_fee":{"type":"FIXED","value":"12"},        "secondary_merchant_industry":"0001",        "secondary_merchant_id":"xxx001",        "secondary_merchant_name":"xxstore",        "store_id":”0001”,        "store_name":"xxstore",        "trans_currency":"TWD",        "currency":"USD",        "country_code":"CN",        "address":"No.278, Road YinCheng, Shanghai, China",        "channel_fee":{"type":"FIXED","value":"10"},        "passback_parameters":{"inner_trade_no":"100000001"},        "notify_mobile":"136XXXXXXXX",        "notify_wangwang":"Zibei",        "notify_alipay_account":"2088101116251688"}

      #channel_fee

      ParameterDescription

      type

      String Required

      Channel fee type. The value can be FIXED to indicate the fee is a fixed amount or RATE to indicate the fee is calculated based on a certain percentage. 

      Example:RATE

      value

      String Required

      1. A FIXED channel fee is charged based on the value. For example, {"type":"FIXED", "value":"X"}. If transaction amount*5% is less than X, the channel fee is transaction amount*5%. If transaction amount*5% is equal to or greater than X, the channel fee is fixed at X. The unit of the value is in accordance with the settlement currency. For the numbers of decimal places supported, refer to the Supported currencies.

      2. If the channel fee type is RATE, the value range is [0, 0.05]. (In promotion season, the channel fee can be 0.)

      Example:0.03


      Sample channel_fee

      copy
      {        "type":"FIXED",        "value":"10"}

      #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_type

      String

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

      Example:MD5

      sign

      String

      Sign value

      Example:8342649bb0b3b818c9bed5952503b3df

      error

      String

      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:ILLEGAL_SIGN

      Business parameter

      qrcode

      String Required

      QR code 

      Example:https://qr.alipay.com/9446219319446735

      qrcode_img_url

      String Required

      The URL of the QR code image

      Example:https://qr.alipay.com/paipai/show.htm?code=9446219319446735

      #Payment breakdown

      ParameterDescription

      ALIPAYACCOUNT

      String

      The amount paid by Alipay account's balance in CNY. 

      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 amount paid by the merchant's voucher in CNY. 

      Example:1.23

      TMPOINT

      String

      The amount paid by the buyer's point at the merchant in CNY.

      Example:1.69

      COUPON

      String

      The amount paid by red package in CNY. 

      Example:1.23

      POINT

      String

      The amount paid by Ji Fen Bao in CNY.

      Example:1.23

      DISCOUNT

      String

      The amount paid by the discount of the account in CNY.

      Example:1.23

      BANKCARD

      String

      The amount paid by bank card. 

      Example:5.55

      MONEYFUND

      String

      The amount paid by Yu'e Bao. 

      Example:1.23

      BAITIAO

      String

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

      Example:1.23

      MCOUPON

      String

      The money amount paid by the merchants issued coupons. 

      Example:2.21

      Payment breakdown message structure

      copy
      [
       {the payment balance type1: amount1},
       {the payment balance type2: amount2},
      …
      ]

      Sample:

      copy
      paytools_pay_amount=
        [{"MCARD":"7.94"},
         {"TMPOINT":"1.69"},
         {"BANKCARD":"5.55"}
         ]

      #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, used by the partner system to verify the notification 

      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(64)

      The unique corresponding PO No. in the order system of the merchant website.But it is created in the alipay system for scan QR code mode. 

      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(64)

      The serial number of a transaction in the 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(100)

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

      Example:zhuzhanghu@alitest.com

      buyer_email

      String(100)

      Buyer's Alipay account, which can be an email address or phone number. 

      Example:13******011

      seller_id

      String(30)

      The unique Alipay user ID of the seller corresponding to the signed Alipay account.

      It consists of 16 digits and begins with 2088.

      Example:2088101106499364

      buyer_id

      String(30)

      The unique Alipay user ID of the buyer corresponding to the signed Alipay account.

      It 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.97

      quantity

      Number

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

      Example:1

      total_fee

      Number

      Total amount of a transaction in CNY. It is the corresponding parameter upon request, and will be returned back as it is if the currency is CNY.

      For a foreign currency, corresponding CNY amount will be calculated based on the exchange rate.

      Example:1.97

      trans_amount

      Number

      Total amount of a transaction based on list price. If the list amount is shown as a foreign currency, then it is the foreign list amount.If the list amount is shown in CNY, this parameter will not be returned.

      Example:10.00

      forex_total_fee

      Number

      The transaction amount in the settlement currency. 

      Example:0.31

      currency

      String(8)

      The currency to settle with the merchant. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

      Example:USD

      trans_currency

      String(8)

      Pricing currency for the transaction. This parameter is transmitted by the corresponding request and needs to be returned with its original value.

      Example:USD

      forex_rate

      String

      The exchange rate between the currency given in the payment notify request and CNY 

      Example:6.0939

      trans_forex_rate

      String

      The exchange rate between trans_currency and currency given in the payment notification request 

      Example:0.0312

      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

      Total refund amount of an order in a refund notification. The unit is Yuan. The currency is CNY. 

      Example:1.00

      out_biz_no

      String(64)

      Merchant service ID, mainly used as a serial number to return a refund request in a refund notification.

      Example:HZRF001

      paytools_pay_amount

      String(512)

      Payment amount information of all successful payments in various channels. 

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

      extra_common_param

      String(256)

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

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

      m_discount_forex_amount

      Number(9,2)

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

      Example:2.19

      #Payment breakdown

      ParameterDescription

      ALIPAYACCOUNT

      String

      The amount paid in Yuan with the balance in Alipay account.

      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 amount paid in Yuan with the merchant voucher. 

      Example:1.23

      TMPOINT

      String

      The amount paid in Yuan with the Tmall points. 

      Example:1.69

      COUPON

      String

      The amount paid in Yuan with the coupon. 

      Example:1.23

      POINT

      String

      The amount paid in Yuan with the bonus points. 

      Example:1.23

      DISCOUNT

      String

      The amount paid in Yuan with the account discounts. 

      Example:1.23

      BANKCARD>

      tring

      The amount paid in Yuan with the bank card. 

      Example:5.55

      MONEYFUND

      String

      Indicates the amount paid in Yuan with Yu'e Bao. 

      Example:1.23

      BAITIAO

      String

      The money amount paid by BAITIAO. 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

      Payment amount information structure:

      copy
      [
      {Type of payment amount 1:payment amount 1}
      ,
      {Type of payment amount 2:payment amount 2}
      ,
      …
      ]

      Sample

      copy
      paytools_pay_amount=[{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}]

      #Error codes

      #Business errors

      Error codeDescription
      AE_BARCODE_GENERAL_CODE_FAILFailed to generate the barcode
      ILLEGAL_ARGUMENTInvalid argument
      ILLEGAL_SIGNInvalid signature
      AE_BARCODE_GENERAL_CODE_FAIL_AND_NOT_RETRYCreating a QR code is failed. This error code does not support retrial.
      AE_BARCODE_GENERAL_CODE_FAIL_AND_RETRYCreating a QR code failed. This error code supports retrial.
      QRCODE_HAS_BEEN_EXISTThe QR code already exists.

      #System errors

      Error codeDescription
      ILLEGAL_SIGNInvalid signature
      ILLEGAL_DYN_MD5_KEYInvalid dynamic key
      ILLEGAL_ENCRYPTInvalid encryption
      ILLEGAL_ARGUMENTInvalid argument
      ILLEGAL_SERVICEInvalid service name
      ILLEGAL_USERInvalid user ID
      ILLEGAL_PARTNERInvalid partner ID
      ILLEGAL_EXTERFACEInterface configure error
      ILLEGAL_PARTNER_EXTERFACEThe partner ID does not have access privilege.
      ILLEGAL_SECURITY_PROFILEThe key is not available
      ILLEGAL_AGENTInvalid Agent ID
      ILLEGAL_SIGN_TYPEInvalid sign type
      ILLEGAL_CHARSETIllegal character set
      HAS_NO_PRIVILEGENo priviledge
      INVALID_CHARACTER_SETInvalid character set.

      #Samples

      #Request

      https://intlmapi.alipay.com/gateway.do?service=alipay.commerce.qrcode.create&partner=2088021966388155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&biz_type=OVERSEASHOPQRCODE&biz_data=%7B%22secondary_merchant_industry%22%3A%225499%22%2C%22secondary_merchant_id%22%3A%221314520%22%2C%22secondary_merchant_name%22%3A%22Mika's%20coffee%20shop%22%2C%22store_id%22%3A%221993%22%2C%22store_name%22%3A%22Mika's%20coffee%20shop%22%2C%22trans_currency%22%3A%22USD%22%2C%22currency%22%3A%22USD%22%2C%22country_code%22%3A%22US%22%2C%22address%22%3A%223%20Old%20Concord%20Rd%2C%20Burlington%2C%20MA%2001803%E7%BE%8E%E5%9B%BD%22%2C%22notify_sign_type%22%3A%22RSA%22%2C%22notify_charset%22%3A%22UTF-8%22%7D&sign=c7648e6c1036f9b01b2911c231435943

      #

      #Response

      #Synchronous response

      The returned data of a successful request:

      copy
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="partner">208xxxxxxxxxx8155</param>
              <param name="service">alipay.commerce.qrcode.create</param>
              <param name="_input_charset">UTF-8</param>
              <param name="biz_type">OVERSEASHOPQRCODE</param>
              <param name="sign">14e4173a362370a06d0f0075498a7cde</param>
              <param name="biz_data">
              {"secondary_merchant_industry":"5499","secondary_merchant_id":"1314520","secondary_merchant_name":"Mika's coffee shop","store_id":"1993","store_name":"Mika's coffee shop","trans_currency":"USD","currency":"USD","country_code":"US","address":"3 Old Concord Rd, Burlington, MA 01803美国","notify_sign_type":"RSA","notify_charset":"UTF-8"}
              </param>
              <param name="sign_type">MD5</param>
          </request>
          <response>
              <qrcodeinfo>
              <qrcode>https://qr.alipay.com/ocx07305q83kwul5nb8ii2e</qrcode>
              <qrcode_img_url>
              https://mobilecodec.alipay.com/show.htm?code=ocx07305q83kwul5nb8ii2e
              </qrcode_img_url>
              </qrcodeinfo>
          </response>
          <sign>f3f93959ee6905cf480c117c80d555b7</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      The response for a failed request:

      copy
      <alipay>
      <is_success>F</is_success>
      <error>ILLEGAL_SIGN</error>
      </alipay>


      #Asynchronous response

      copy
      https://www.mikascoffee.com/notify
      extra_common_param={"qrcode":"https://qr.alipay.com/ocx06147g658p4j362n2hd7"}
      currency=USD
      trans_currency=USD
      trade_no=201xxxxxxxxxxxxxxxxxxxxx2104
      subject=Mika's coffee shop
      paytools_pay_amount=[{"PCREDIT":"0.07","PCC_PROD_ID":"9102"}]
      buyer_email=186****9365
      gmt_create=2019-09-11 19:16:50
      notify_type=trade_status_sync
      quantity=1
      forex_rate=7.13210000
      out_trade_no=188xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0073
      trans_amount=0.01
      notify_time=2019-09-11 19:16:55
      seller_id=208xxxxxxxxx8155
      trade_status=TRADE_SUCCESS
      gmt_payment=2019-09-11 19:16:55
      total_fee=0.07
      seller_email=int***@list.alibaba-inc.com
      notify_action_type=payByAccountAction
      price=0.07
      buyer_id=208xxxxxxxxx6535
      notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx7001
      sign_type=RSA
      sign=$$