alipay.commerce.qrcode.create

2021-03-29 09:52

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 is returned.

Request

Service address

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

Request parameters

Parameter Description

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 is 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 request. The time is in GMT+8, and in a format of yyyy-MM-dd HH:mm:ss.By default, the request expires in 30 minutes.

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 is in the JSON format. For more information, see biz_data.

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":"HKD","currency":"HKD","country_code":"US","address":"6229 Hillcrest Rd, Dallas, TX 75205","notify_sign_type":"RSA","notify_charset":"UTF-8"}

biz_data

Parameter Description

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

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

secondary_merchant_name

String(32) 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 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 the currency parameter. Contact Alipay technical support if you have to use different values. Use upper case.

Example:HKD

currency

String Required

The settlement currency that the merchant specifies in the contract. Only HKD is supported.

Example:HKD

sys_service_provider_id

String

System service provider ID, which is used to identify the payment system provider. 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:Refer to “table 4-3 channel_fee parameter list”

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:Hangzhou Delixi building

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. Must be numbers only.

Example:136XXXXXXXX

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

channel_fee

Parameter Description

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.

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

Note:

Do not use the halfwidth quotation mark (") in parameter values.

Response

Synchronous response

Parameter Description

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. Only MD5 is supported. Use uppercase.

Example:MD5

sign

String

Sign value

Example:8342649bb0b3b818c9bed5952503b3df

error

String

Error code that is returned when the request is not successful to describe the request failure reason. If the request is successful, this field is not returned. 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_urlString Required

The URL of the QR code image

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

Asynchronous response

Parameter Description

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

Example:kids clothing

trade_no

String(64)

Alipay transaction ID

Example:2013112711001004940000394507

trade_status

String

Alipay transaction status. See Trade status for details.

Example:WAIT_BUYER_PAY

gmt_create

Date

The time when the 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 transaction is paid by the buyer. 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:138*****011

seller_id

String(30)

The merchant’s partner ID, which consists of 16 digits and begins with 2088.

Example:2088101106499364

buyer_id

String(30)

The buyer’s user ID, which 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

The total transaction amount in CNY. If the value was sent in a currency that is not CNY, this value is obtained by converting with the exchange rate.

Example:10.00

forex_total_fee

Number

The transaction amount in the settlement currency.

Example:10.00

trans_amount

Number

The total amount of the transaction. If the transaction was paid by CNY, this parameter returns null.

Example:10.00

currency

String(8)

The settlement currency

Example:HKD

trans_currency

String(8)

Pricing currency for the transaction

Example:HKD

forex_rate

String

The exchange rate between the settlement currency and CNY

Example:6.0939

trans_forex_rate

String

The exchange rate between the pricing currency and settlement currency

Example:0.0312

body

String(400)

Detailed description about the goods

Example:Glitter leggings

refund_fee

Number

Refunded amount returned in the refund notification. The unit is Yuan.

Example:1.00

out_biz_no

String(64)

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

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

Error codes

Business errors

Error Code	Specification
AE_BARCODE_GENERAL_CODE_FAIL	Failed to generate the barcode
ILLEGAL_ARGUMENT	Invalid agument
ILLEGAL_SIGN	Invalid signature

System errors

Error Code	Specification
ILLEGAL_SIGN	Invalid signature
ILLEGAL_DYN_MD5_KEY	Invalid dynamic key
ILLEGAL_ENCRYPT	Invalid encryption
ILLEGAL_ARGUMENT	Invalid argument
ILLEGAL_SERVICE	Invalid service name
ILLEGAL_USER	Invalid user ID
ILLEGAL_PARTNER	Invalid partner ID
ILLEGAL_EXTERFACE	Interface configure error.
ILLEGAL_PARTNER_EXTERFACE	The partner ID does not have access privilege.
ILLEGAL_SECURITY_PROFILE	The key is not available
ILLEGAL_AGENT	Invalid agent ID
ILLEGAL_SIGN_TYPE	Invalid sign type
ILLEGAL_CHARSET	Illegal character set
HAS_NO_PRIVILEGE	No priviledge
INVALID_CHARACTER_SET	Invalid character set

Samples

Request

https://intlmapi.alipay.com/gateway.do?service=alipay.commerce.qrcode.create&partner=2088021966645500&_input_charset=UTF-8&sign_type=MD5&notify_url=http%3A%2F%2Fwww.mikascoffee.com%2Fnotify&timestamp=2019-09-10%2014%3A43%3A12&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%22HKD%22%2C%22currency%22%3A%22HKD%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=a494fbdca0d437d2b48860e485329bab

Response

Synchronous response

The response of a successful request:

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner">208xxxxxxxxx5500</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">a494fbdca0d437d2b48860e485329bab</param>
        <param name="notify_url">http://www.mikascoffee.com/notify</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":"HKD","currency":"HKD","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>
        <param name="timestamp">2019-09-10 14:43:12</param>
    </request>
    <response>
        <qrcodeinfo>
            <qrcode>https://qr.alipay.com/ocx09863drhqewuprmuzm68</qrcode>
            <qrcode_img_url>
                https://mobilecodec.alipay.com/show.htm?code=ocx09863drhqewuprmuzm68
            </qrcode_img_url>
        </qrcodeinfo>
    </response>
    <sign>92d50b1269827bff460f8959a5218224</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
http://www.mikascoffee.com/notify
extra_common_param={"qrcode":"https://qr.alipay.com/ocx00197t1iruoiqhwwjr19"}
currency=HKD
payment_inst=ALIPAYHK
trans_currency=HKD
trade_no=201xxxxxxxxxxxxxxxxxxxxx0583
subject=Mika's coffee shop
buyer_email=852-****4034
paytools_pay_amount=[{"BANKCARD":"0.01"}]
gmt_create=2019-09-11 19:02:02
notify_type=trade_status_sync
quantity=1
forex_rate=1
out_trade_no=882xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2346
trans_amount=0.01
notify_time=2019-09-11 19:02:41
seller_id=208xxxxxxxxx5500
trade_status=TRADE_SUCCESS
gmt_payment=2019-09-11 19:02:40
total_fee=0.01
seller_email=che***@antfin.com
notify_action_type=payByAccountAction
price=0.01
buyer_id=208xxxxxxxxx4270
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx7574
sign_type=RSA
sign=$$$

The payment breakdown

The payment breakdown is represented in JSON format, and it includes the following parameters:

Parameter Description

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

The JSON format：

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

An JSON Format Example:

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

Payment amount information

The payment amount information is displayed in json, which includes the following parameters:

Parameter Description

ALIPAYACCOUNT

String

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

Example:1.23

TMPOINT

String

The amount paid in Yuan by the Tmall points.

Example:1.69

COUPON

String

The amount paid in Yuan by the coupon.

Example:1.23

POINT

String

The amount paid in Yuan by the bonus points.

Example:1.23

DISCOUNT

String

The amount paid in Yuan by the account discounts.

Example:1.23

BANKCARD

String

The amount paid in Yuan by the bank card.

Example:5.55

MONEYFUND

String

The amount paid in Yuan 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. The unit is Yuan.

Example:2.21

Format structure:

[

{Type of payment amount 1:payment amount 1}

{Type of payment amount 2:payment amount 2}

…

]

Example:

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

Example

http://merchant customized address/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_email=zhuzhanghu%40alitest.com&notify_type=trade_status_sync&buyer_email=138*****011&sign=601510b7970e52cc63db0f44997cf70e&trade_no=2013112711001004940000394507&buyer_id=2088102105236945&quantity=10&total_fee=10.00&price=1.00&gmt_create=2013-11-27+15%3A45%3A57&out_trade_no=5431395578198135&seller_id=2088101106499364&notify_time=2013-11-27+15%3A45%3A58&subject=%E5%A3%B0%E6%B3%A2%E6%94%AF%E4%BB%98-%E5%88%86%E8%B4%A6-sky&trade_status=WAIT_BUYER_PAY&payment_inst=ALIPAYCN&sign_type=MD5

Note:

This example is only for reference. The actual gateway is the domain name of a merchant.