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

alipay.commerce.qrcode.modify

Call this interface to modify the QR code information.

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

ParameterDescription
Basic parameter

service

String Required

Interface name

Example:alipay.commerce.qrcode.modify

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

qrcode

String Required

The returned QR code value after the code is generated successfully.

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

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

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

Pricing currency for the transaction 

Example:HKD

currency

String Required

The currency to settle with the merchant. Only HKD is supported. 

Example:HKD

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: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:Store address

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

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. If the channel fee type is FIXED, the value range is [0, 5% of the original oder amount]. The unit of the value is HKD and is accurate to two decimal places.

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

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

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

Error codes

Business errors

Error codeDescription
AE_BARCODE_GENERAL_CODE_FAIL_AND_RETRYQR code generation fails. You can try again later.
AE_BARCODE_GENERAL_CODE_FAIL_AND_NOT_RETRYQR code generation fails. You can try again later.
ILLEGAL_ARGUMENTPamameter error. Check and try again.

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.modify&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&timestamp=2019-09-10%2014%3A43%3A12&biz_type=OVERSEASHOPQRCODE&qrcode=https%3A%2F%2Fqr.alipay.com%2Focx09863drhqewuprmuzm68&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%2001804%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=9ea53d5a5d36b8e97bb086b5da64b76d

Response

Request succeeds:

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner">208xxxxxxxxx5500</param>
        <param name="service">alipay.commerce.qrcode.modify</param>
        <param name="_input_charset">UTF-8</param>
        <param name="qrcode">https://qr.alipay.com/ocx09863drhqewuprmuzm68</param>
        <param name="biz_type">OVERSEASHOPQRCODE</param>
        <param name="sign">9ea53d5a5d36b8e97bb086b5da64b76d</param>
        <param name="notify_url">https://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 01804美国","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>
        </qrcodeinfo>
    </response>
    <sign>39c65ea091096e63f934506582035005</sign>
    <sign_type>MD5</sign_type>
</alipay>

Request is failed:

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