alipay.acquire.precreate (for third-party QR code payment)
Call this interface to place a pre-order without the payer identity information. Alipay returns a payment URL in the response. Payers can access the payment URL by using Alipay wallet to confirm the order and make the payment.
Request
Service address
Environment | HTTPS request URL |
Production environment | Priority: https://globalmapi.alipay.com/gateway.do |
Test environment |
Request parameters
extend_params
Parameter | Description |
secondary_merchant_id String | The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.
|
secondary_merchant_name String | Registration legal name of the secondary merchant, shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant.
|
secondary_merchant_industry String(4) | Industry classification identifier of the secondary merchant, which is assigned by Alipay. For more information about the MCC code, see MCC list.
|
store_name String | Store name. Can be null only when the store information is verified.
|
store_id String | The unique ID that is assigned by the partner to identify a store of a merchant, which can contain letters, numbers, and underscores.
|
terminal_id String | Terminal ID
|
sys_service_provider_id String(32) | System service provider ID, which is used to identify the payment system provider.
|
goods_detail
Goods details parameters shall be in the format of JSON and include the following parameters:
Parameter | Description |
goodsId String | Goods ID
|
goodsName String | Goods name
|
goodsCategory String | Goods category
|
showUrl String | Hyperlink for the show of goods on the webpage of checkout counter.
|
quantity String | The quantity of goods
|
body String | Detailed description about the goods. Special characters are not supported.
|
price String | Unit price of the goods in the order
|
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
Parameter | Description |
Basic parameter | |
is_success String | 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.
|
sign_type String | Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.
|
sign String | Sign value
|
error String | Error code that is returned when the request is failed to describe the request failure reason. This parameter is not returned if the request succeeds. For more information, see the Error Code section in this document.
|
Result Code | |
result_code String(32) | Response code of the processing result of the order placement and payment. For more details, see Business Response Code.
|
out_trade_no String(64) | Unique order ID in the order system in the corresponding merchant's website other than Alipay trade number. Uniqueness of this parameter in merchant's website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.
|
voucher_type String(10) | Voucher type, and the value is qrcode.
|
qr_code String(128) | Value of the QR code
|
big_pic_url String | URL for the QR code in the big size
|
pic_url String | URL for the QR code in the normal size
|
small_pic_url String | URL for the QR code in the small size
|
detail_error_code String(48) | Description of the returned response code. If the response code of result_code is ORDER_SUCCESS_PAY_SUCCESS, this parameter is not returned.
|
detail_error_des String(64) | Explanation of the detailed error code. If result_code is ORDER_SUCCESS_PAY_SUCCESS, this parameter is not returned.
|
Note:
The synchronous response might have more parameters due to the upgrade on the Alipay server side. You can ignore parameters that are not included in this API document.
Asynchronous response
Parameter | Description |
Basic parameter | |
notify_time Timestamp | The time when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss
|
notify_type String | Notification type
|
notify_id String | Notification ID, used by the partner system to verify the notification
|
sign_type String | Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.
|
sign String | Sign value
|
Business parameter | |
out_trade_no String | Unique order ID in the order system in the corresponding merchant's website other than Alipay trade number. Uniqueness of this parameter in merchant's website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.
|
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.
|
trade_no String(64) | The serial number assigned by Alipay to identify a trade in the Alipay system, with a length in the range 16 - 64 bits.
|
trade_status String | Transaction status. See Trade status for details.
|
gmt_create Date | The time when the trade transaction is created. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8.
|
gmt_payment Date | The time when the payment is completed. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8.
|
seller_email String | Alipay ID of the seller, with a format of email address or phone number
|
buyer_email String | Buyer’s Alipay ID, which can be an email address or phone number.
|
seller_id String | Seller’s unique Alipay user ID, consists of 16 digits and begins with 2088.
|
buyer_id String | Buyer's unique Alipay user ID, consists of 16 digits and begins with 2088.
|
price Number | Goods price. This parameter is transmitted by the corresponding request and needs to be returned with its original value.
|
quantity Number | The quantity of goods. This parameter is transmitted by the corresponding request and needs to be returned with its original value.
|
total_fee Number(11,2) | Total amount of a transaction in RMB. It is the corresponding parameter upon request, and will be returned back as it is if the currency is RMB. For a foreign currency, corresponding RMB amount will be calculated based on the exchange rate.
|
body String | Detailed description about the goods. This parameter is transmitted by the corresponding request and needs to be returned with its original value.
|
refund_fee Number | The refund amount. The unit is Yuan.
|
paytools_pay_amount String | Payment amount information of all successful payments in various channels.
|
extra_common_param String | This parameter is returned with the value of passback_parameters in the corresponding request.
|
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.
|
paytools_pay_amount
Parameter | Description |
ALIPAYACCOUNT String | The money amount paid by the balance of Alipay account. The unit is Yuan.
|
MCARD String | The money amount paid by the merchant's prepaid card. The unit is Yuan.
|
MDISCOUNT String | The money amount paid by the merchant's discount coupon. The unit is Yuan.
|
TMPOINT String | The money amount paid by the Tmall points. The unit is Yuan.
|
COUPON String | The money amount paid by coupons. The unit is Yuan.
|
POINT String | The money amount paid by points. The unit is Yuan.
|
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.
|
MONEYFUND String | The money amount paid by the money fund. The unit is Yuan.
|
BAITIAO String | The money amount paid by BAITIAO. The unit is Yuan.
|
PCARD String | The money amount paid by the Alipay card. The unit is Yuan.
|
PCREDIT String | The money amount paid by the consumption credit card. The unit is Yuan.
|
MCOUPON String | The money amount paid by the merchants issued coupons. The unit is Yuan.
|
Error codes
Business response code
Response code | Description |
SUCCESS | The order succeeds. |
FAIL | The order is failed. |
Business code
Error code | Description |
SYSTEM_ERROR | Alipay system is currently not available. Action: Retry this request with the exact parameters. Refer to Case 2 for detailed instruction. |
CONTEXT_INCONSISTENT | You were retrying a request identified by the same out_trade_no, but not all other request parameters were the same. Action: Retry this request with the exactly the same parameters, or with a new out_trade_no. |
TRADE_HAS_SUCCESS | The payment of trade has been made successfully. Action: Mark this transaction as paid in your merchant system. |
TRADE_HAS_CLOSE | The trade has expired. Action: Start a new transaction. |
TRADE_HAS_FINISHED | The trade has been finished. Action: Start a new transaction. |
REASON_ILLEGAL_STATUS | The trade status is illegal. Action: Start a new transaction. |
EXIST_FORBIDDEN_WORD | Forbidden words are included in the order information. Action: Delete concerning words. |
ACCESS_FORBIDDEN | Has no right to use the product. Action: Make sure your agreement with Alipay is still valid. |
SELLER_NOT_EXIST | The seller does not exist. Action: Check the seller parameter value. |
SELLER_BEEN_BLOCKED | The seller's account has been frozen. Action: Contact Alipay tech support for help. |
INVALID_PARAMETER | Parameter error. Action: Check each request parameter according to the API specification. |
CURRENCY_NOT_SUPPORT | This currency is not supported. Action: Check the value of the currency field. |
RESTRICTED_MERCHANT_INDUSTRY | The transaction value cannot be greater than 5000 US dollars. Action: Check your value of secondary_merchant_industry and contact Alipay technical support if needed. |
PRODUCT_AMOUNT_LIMIT_ERROR | The transaction amount exceeded the limitation. Action: Users can use the other payment method such as cash or the credit card |
EXCHANGE_AMOUNT_OR_CURRENCY_ERROR | The exchange amount or currency is incorrect. Action: Contact Alipay technical support for help. |
ILLEGAL_MERCHANT_INDUSTRY | Illegal MCC format. Action: Ensure the value of secondary_merchant_industry to be defined in the MCC list. |
FORBIDDEN_MERCHANT_INDUSTRY | This transaction type is not allowed. Action: Check your value of secondary_merchant_industry and contact Alipay technical support if needed. |
INVALID_RECEIVE_ACCOUNT | The seller is not in the payee list. Action: Contact Alipay technical support for help. |
SECONDARY_MERCHANT_ID_BLANK | The secondary merchant ID is not provided to Alipay. Action: Send the secondary merchant ID to Alipay. |
SECONDARY_MERCHANT_ID_INVALID | The secondary merchant is not registered with Alipay. Action: Check whether the provided secondary merchant ID is correct and whether the secondary merchant is registered with Alipay. If the secondary merchant is not registered with Alipay, register the secondary merchant with Alipay immediately. |
STORE_NOT_MATCH | The secondary merchant is not registered with Alipay. Action: Check whether the provided store ID is correct and whether the secondary merchant is registered with Alipay. If the secondary merchant is not registered with Alipay, register the secondary merchant with Alipay immediately. |
SECONDARY_MERCHANT_STATUS_ERROR | The status of secondary merchant is abnormal in the Alipay system. Action: Contact Alipay Business Support by sending an email to global.service@alipay.com. |
Access code
Error code | Description |
ILLEGAL_SIGN | Illegal signature. Action: Use a legal signature and try again. |
INVALID_PARAMETER | Parameter error. Action: Check each request parameter according to the API specification. |
ILLEGAL_ARGUMENT | Parameter error. Action: Check each request parameter according to the API specification. Contact Alipay technical support if this error persists. |
ILLEGAL_PARTNER | Incorrect partner ID. Action: Ensure that the value of partner parameter matches the partner value provided by Alipay. Contact Alipay technical support if this error persists. |
ILLEGAL_EXTERFACE | Interface configure error. Action: Ensure that the service parameter has the same value with the one in API specification. Contact Alipay technical support if this error persists |
ILLEGAL_PARTNER_EXTERFACE | The partner ID does not have access privilege. Action: Ensure that your agreement with Alipay has been finalized. Contact Alipay technical support if needed. |
ILLEGAL_SIGN_TYPE | Illegal sign type. Action: Ensure that the value of sign_type is among MD5, RSA and RSA2. Contact Alipay technical support if this error persists. |
HAS_NO_PRIVILEGE | Has no privilege. Action: Contact Alipay technical support. |
ILLEGAL_EXTERFACE_FOR_CA_VERIFY | The interface is not allowed to use Certificate Verification Service. Action: Contact Alipay technical support for help. |
ILLEGAL_CERT_IS_OVERDUE | Certificate verification is failed due to the expired certificate. Action: Check the status of your certificate. |
ILLEGAL_CA_SIGN | Certificate verification is failed. Action: Check the status of your certificate. |
Trade status
Enumeration name | Description |
WAIT_BUYER_PAY | The trade has been established and is waiting for the buyer to make payment. |
TRADE_CLOSED | The trade is closed because the payment has not been completed within specified time or the payment has been fully returned when the trade completes. |
TRADE_SUCCESS | The trade succeeds and is operable, such as multi-level royalty distribution or refund. |
TRADE_FINISHED | The trade succeeds and is completed, and is not operable. |
Handling result
Case 1. When the invocation is failed due to network issue or request timeout, no response is returned from Alipay. Take the following actions:
- Check your network connectivity to Alipay gateway. Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
- If you still cannot get any response from Alipay, contact Alipay technical support for help.
Case 2. If you received the response from Alipay, but one of the following results is returned:
- is_success=F and error=SYSTEM_ERROR
- is_success=T, result_code=FAIL, and detail_error_code=SYSTEM_ERROR
Take the following actions:
- Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
- If you still cannot get any response from Alipay, contact Alipay technical support for help.
Case 3. If you received the response from Alipay, and is_success=T and result_code=SUCCESS, continue the business process by rendering the QR code.
Case 4. If you received the response from Alipay, and one of the following results is returned:
- is_success=F and error=!SYSTEM_ERROR
- is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR.
You must refer to the specific error code for instruction.
Pseudo code
try{
if(isCase3){ //CASE 3
doSuccessProcess();
}
else if(isCase4){ //CASE 4
doFailureProcess();
}
else{ //CASE 2
retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.
if(retrySuccess){
doSuccessProcess();
}
else{
// request Alipay tech support.
}
}
}catch (Exception ex){ // CASE 1
retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.
if(retrySuccess){
doSuccessProcess();
}
else{
// request Alipay tech support.
}
}
}
Samples
Request
https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.precreate&partner=2088021966388155&_input_charset=UTF-8&sign_type=MD5&product_code=OVERSEAS_MBARCODE_PAY¤cy=USD&trans_currency=USD&out_trade_no=out_trade_no_20190904_163941&subject=Mika's%20coffee%20shop&total_fee=0.01&seller_id=2088021966388155&extend_params=%7B%22secondary_merchant_id%22%3A%221314520%22%2C%22secondary_merchant_name%22%3A%22Mika's%20coffee%20shop%22%2C%22secondary_merchant_industry%22%3A%225499%22%2C%22store_name%22%3A%22Mika's%20coffee%20shop%22%2C%22store_id%22%3A%221993%22%7D&sign=69f16345d886f551d2e48351d0a64f21
Response
Synchronous response
Business is accepted and processed normally, and acquiring is created successfully:
<alipay>
<is_success>T</is_success>
<request>
<param name="extend_params">
{"secondary_merchant_id":"1314520","secondary_merchant_name":"Mika's coffee shop","secondary_merchant_industry":"5499","store_name":"Mika's coffee shop","store_id":"1993"}
</param>
<param name="_input_charset">UTF-8</param>
<param name="subject">Mika's coffee shop</param>
<param name="sign">69f16345d886f551d2e48351d0a64f21</param>
<param name="product_code">OVERSEAS_MBARCODE_PAY</param>
<param name="trans_currency">USD</param>
<param name="out_trade_no">out_trade_no_20190904_163941</param>
<param name="partner">208xxxxxxxxx8155</param>
<param name="service">alipay.acquire.precreate</param>
<param name="total_fee">0.01</param>
<param name="currency">USD</param>
<param name="sign_type">MD5</param>
<param name="seller_id">208xxxxxxxxx8155</param>
</request>
<response>
<alipay>
<big_pic_url>
https://mobilecodec.alipay.com/show.htm?code=bax00450gieal5w1cxdy80db&picSize=L
</big_pic_url>
<out_trade_no>out_trade_no_20190904_163941</out_trade_no>
<pic_url>
https://mobilecodec.alipay.com/show.htm?code=bax00450gieal5w1cxdy80db&picSize=M
</pic_url>
<qr_code>https://qr.alipay.com/bax00450gieal5w1cxdy80db</qr_code>
<result_code>SUCCESS</result_code>
<small_pic_url>
https://mobilecodec.alipay.com/show.htm?code=bax00450gieal5w1cxdy80db&picSize=S
</small_pic_url>
<voucher_type>qrcode</voucher_type>
</alipay>
</response>
<sign>b25cfef6112d6e910745ce3ee9f1f69b</sign>
<sign_type>MD5</sign_type>
</alipay>
Request succeeds, but the business processing fails:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="body">face-to-face-payment</param>
<param name="subject">iphone</param>
<param name="sign_type">MD5</param>
<param name="out_trade_no">990xxxxxxx8989</param>
<param name="total_fee">10</param>
<param name="partner">208xxxxxxxxx9364</param>
<param name="quantity">10</param>
<param name="sign">a1cb41a4019351965d4418c9cb933f0f</param>
<param name="_input_charset">UTF-8</param>
<param name="price">1</param>
<param name="it_b_pay">1d</param>
<param name="product_code">OVERSEAS_MBARCODE_PAY</param>
<param name="service">alipay.acquire.precreate</param>
<param name="seller_id">208xxxxxxxxx9364</param>
</request>
<response>
<alipay>
<result_code>FAIL</result_code>
<detail_error_code>INVALID_PARAMETER</detail_error_code>
<detail_error_des>request paramter invalid</detail_error_des>
</alipay>
</response>
<sign>ea489fc31da63253bab52ed77fb45eb7</sign>
<sign_type>MD5</sign_type>
</alipay>
Request fails or the data accessed are incorrect:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Asynchronous response
https://www.mikascoffee.com/notify
currency=USD
trans_currency=USD
trade_no=201xxxxxxxxxxxxxxxxxxxxx2392
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:22:52
notify_type=trade_status_sync
forex_rate=7.13210000
quantity=1
out_trade_no=out_trade_no_20190904_163949
trans_amount=0.01
seller_id=208xxxxxxxxx8155
notify_time=2019-09-11 19:22:56
trade_status=TRADE_SUCCESS
total_fee=0.07
gmt_payment=2019-09-11 19:22:56
seller_email=$$$
price=0.07
buyer_id=208xxxxxxxxx6535
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx1425
sign_type=MD5
sign=$$$