alipay.acquire.precreate

Environment

HTTPS request URL

Production environment

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

Test environment

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

service

String Required

Interface name 

Example:alipay.acquire.precreate

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

notify_url

URL(200)

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

Example:http://api.test.alipay.net/atinterface/receive_notify.htm

String Required

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

Example:1456507704121

terminal_timestamp

String

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

Example:1456507704102

String(64) Required

Unique order ID in Alipay’s merchant website

Example:990xxxxxxx8989

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. The value is OVERSEAS_MBARCODE_PAY for oversea in-store payments.

Example:OVERSEAS_MBARCODE_PAY

total_fee

Number(11,2) Required

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

Example:10.00

seller_id

String(28)

Unique Alipay user ID corresponding to Seller’s Alipay account

, which has 16 digits and begins with 2088.

If both sell_id and seller-email are null, the default value of this parameter is the value of merchant.

Example:2088101106499364

seller_email

String(100)

Seller’s Alipay account, can be an email address or phone number

If seller_id is not null, the value of seller_id shall be the seller’s ID and this parameter can be neglected.

Example:test@alitest.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(8)

Required

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

Example:HKD

String(8) 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

price

Number(9,2)

Unit price of the goods in the order. If this parameter is transmitted in the request, the condition of total_fee=price×quantity must be met. 

Example:1

quantity

String(100)

Quantity of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met. 

Example:10

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

Required

This field is used for transmitting specific business information of the merchant. This parameter is valid only if the merchant and Alipay agree to transmit this parameter and reach an agreement on the implication of this parameter. For example, store ID and other information under the circumstance that payment can be made through sound wave. The format is JSON. For more information, see extend_params. 

Example:{"STORE_ID":"BJ_ZZ_001","STORE_NAME":"Muku in the Dreieichstrabe","SECONDARY_MERCHANT_ID":"A80001","SECONDARY_MERCHANT_NAME":"Muku","SECONDARY_MERCHANT_ INDUSTRY":"7011"}

it_b_pay

String(200)

Specifies the time period in which the user can complete the payment from the moment when the user scans the QR code. The trade is closed automatically once the time is up. The value of this field is 3m by default. The value of this field is in the range of 1m - 15d.

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

2、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)

If this parameter was sent to Alipay by the request, Alipay will return this parameter by the asynchronous notification with the extra_common_param parameter. 

Example:{"inner_trade_no":"100000001"}

trade_information

String(6000)

When the Alipay wallet is used, you can specify this field if you want. When the AlipayHK wallet is used, you don’t need to specify this field. The wallet type is identified by the value of the payment_inst field. Information about the trade industry. See trade_information for details.

Example:{"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"}

qr_code_it_b_pay

String(200)

Specifies the time period in which the user can complete the payment from the moment when the QR code was created. The trade is closed automatically once the time is up.The value of this field is in the range of 1m - 2h. If this parameter is specified, the it_b_pay parameter becomes invalid.

Notes:

1、The following abbreviations are used to present units of time:

m: minute

h: hour

2、Decimal point of the numerical value of this parameter is rejected, for example, 1.5h need to be transformed to 90m. 

Example:1m

goodsId

String Required

Goods ID 

Example:apple-01

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

String Required

The quantity of goods 

Example:1

body

String

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

Example:Glitter leggings

price

String Required

Unit price of the goods in the order 

Example:2000

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

Required

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

Example:Muku

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

store_id

String(32)

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

Example:BJ_ZZ_001

store_name

String(32)

Store name, which is used to be shown in the customer’s Alipay wallet and the reconciliation file 

Example:Muku in the Dreieichstrabe

terminal_id

String(10)

Terminal ID 

Example:T80001

sys_service_provider_id

String(32)

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

Example:R00998889911

business_type

String

Business type. 5 types are supported:

1: Hotel

2: AIR

3: Overseas study consulting

4: Sales of goods

5: Others, including all the other business types that do not fall into the above 4 categories. For example, mobile data service recharge, airport pick up service, etc.

If more than one type is involved, use the vertical bar to seperate type values.

Example:1|2|3|4|5 or 1

hotel_name

String

Hotel name that consists of numbers, letters, spaces, and special characters including ,.<>()[]/\-,. If more than one hotel name exists, separate values with vertical bar (|). Specify this field only when business_type is 1 (Hotel). 

Example:zlidu, sluhg-987, 889utng

check_in_time

Date

Check-in time. Format: yyyy-MM-dd. Timezone: GMT +8. Specify this field only when business_type is 1 (Hotel). 

Example:2018-10-20

check_out_time

Date

Check-out time. Format: yyyy-MM-dd. Timezone: GMT +8. Specify this field only when business_type is 1 (Hotel). 

Example:2018-10-22

flight_number

String

Flight number. If flight transfer exists, separate flight numbers with vertical bar (|). Specify this field only when business_type is 2 (AIR). 

Example:NWS 996|TWF 8854

departure_time

Date

Departure time.Format: yyyy-MM-dd HH:mmTimezone: GMT +8. If flight transfer exists, separate time values with vertical bar (|). Specify this field only when business_type is 2 (AIR).

Example:2018-10-22 20:49

admission_notice_url

String

If business_type is 3 (Overseas study consulting), the URL of admission notice (image) must be specified.

Example:https://www.iconfont.cn/search/index?test

goods_info

String

Goods information that includes SKU names and corresponding quantities, in the format of SKU_name^quantity. If more than one goods exists, separate values with vertical bar (|). Specify this field only when business_type is 4 (Sales of goods).

Example:pencil^2|eraser^5|iPhone XS 256G^1

total_quantity

Number

Total quantities of all goods in one order. Specify this field only when business_type is 4 (Sales of goods).

Example:8

other_business_type

String

If business_type is 5 (Others), specify the business type in details. 

Example:Airport pick up service

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

error

String

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

Example:ILLEGAL_SIGN

result_code

String(32)

Processing result of the request, with a value of SUCCESS to indicate the process is successful, FAIL to indicate the process is failed, or UNKNOWN to indicate an unknown result. For more details, see Business Response Code. 

Example:SUCCESS

out_trade_no

String(64)

Unique order ID in order system in 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.

Example:990xxxxxxx8989

voucher_type

String(10)

Voucher type, and the value is qrcode. 

Example:qrcode

qr_code

String(128)

Value of the QR code

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

big_pic_url

String

URL for the QR code in the big size

Example:http://mobilecodec. alipay.com/show.htm?code=baxga4hjmcal5rl8fa&picSize=L

pic_url

String

URL for the QR code in the normal size

Example:http://mobilecodec. alipay.com/show.htm?code=baxga4hjmcal5rl8fa&picSize=M

small_pic_url

String

URL for the QR code in the small size

Example:http://mobilecodec. alipay.com /show.htm?code=baxga4hjmcal5rl8fa&picSize=S

detail_error_code

String(48)

Detailed error code, which describes the reason for not receiving a result_code of ORDER_SUCCESS_PAY_SUCCESS. If the response code of result_code is ORDER_SUCCESS_PAY_SUCCESS, this parameter is not returned.

Example:TRADE_BUYER_NOT_MATCH

detail_error_des

String(64)

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

Example:Trade does not match with buyer

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:601510b7970e52cc63d b0f44997cf70e

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

out_trade_no

String(64)

Unique order ID in order system in 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.

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)

Trade number of the trade in the Alipay system, with a length in the range 16 - 64 bits.

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)

Unique Alipay user ID corresponding to seller’s Alipay account, which contains 16 digits and begins with 2088.

Example:2088101106499364

buyer_id

String(30)

Unique Alipay user ID corresponding to buyer’s Alipay account, which contains 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(11,2)

The transaction amount in CNY. 

Example:10.00

trans_amount

Number

Total pricing of the order, in the pricing currency trans_currency. It will be null if the trans_currency is CNY 

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

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

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

Example:1.00

out_biz_no

String(64)

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"}

payment_inst

String(6)

This parameter identifies the wallet type with a value of ALIPAYCN or ALIPAYHK.

Example:ALIPAYHK

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

ILLEGAL_DYN_MD5_KEY

The trade is closed because the payment has not been completed within a specified time, or because the payment has been fully returned when the trade completes.