3. Creating order using alipay.acquire.create

2020-10-17 10:52

With information such as Alipay user ID，payment amount, the partner sever calls this API to create a new trade transaction, and then receive the trade_no from the returned results. With the trade_no, the partner server can then prompt the user to pay.

For the information about the request and response parameters and error codes, see the API document.

#Request parameters

#The gateway URL：

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

#Basic request parameters:

Parameter	Type	Description	Required	Sample
service	String	The name of the interface.	Y	alipay.acquire.create
partner	String(16)	The unique number of an Alipay parter. The parter ID consists of 16 numbers that begin with 2088.	Y	2088101106499364
_input_charset	String	The encoding format that merchants use for websites. Such as utf-8, gbk, gb2312, etc.	Y	utf-8
sign_type	String	The value can be one of DSA, RSA, or MD5. Uppercase must be used.	Y	MD5
sign	String	Sign value	Y	9aae99502a8dd70e67d3d3575f7176cd
notify_url	String	The URL configured to receive the async notification from Alipay server.	N	http://api.test.alipay.net/atinterface/receive_notify.htm
alipay_ca_request	String	Signature types 1: Certification signature 2: Other secret key signatures. If empty, the default value 2 will be used.	N	2

#business parameters

Parameter	Type	Description	Required	Sample
out_trade_no	String(64)	The unique order number on the merchant’s site.	Y	205211376305670
subject	String(256)	The title of the goods/ The title of the trade/ The title of the order/Key words of the order and so on. The Max length is 128 Chinese characters.	Y	test title
product_code	String(32)	To distinguish the order is in which business type. Fill in the business type confirmed when you sign the contract.	Y	OVERSEAS_MBARCODE_PAY
total_fee	number(9,2)	Total amount of this order, the value range is [0.01,100000000]. Keep 2 digits after the decimal point.	Y	0.01
seller_id	String(28)	Seller's unique Alipay user ID consists of 16 numbers that begin with 2088. If both seller_email and seller_id are null, then fill in partner as the default value.	N	2088101106499364
seller_email	String(100)	Alipay ID of the seller, can be email or phone number. If the seller_id is not null, then the seller_id is the seller’s Alipay ID and ignore the seller_email.	N	test@alitest.com
buyer_id	String(28)	The unique Alipay user ID of the buyer which consists of 16 numbers that begin with 2088. The buyer_id and the buyer_email can’t be null at the same time	N	2088101568338364
buyer_email	String(100)	Alipay ID of the buyer, can be email or phone number. If the buyer_id exists, then the buyer_id is the buyer’s ID and ignore the buyer_email.	N	test11@alitest.com
body	String(400)	The detail description of one trade. If the type of goods is more than one, then accumulate the strings and pass them to the body	N	商品x1
show_url	String(400)	The hyperlink of goods on the cashier page	N	http://www.taobao.com
currency	String(10)	Currency for merchants to settle the order	Y	USD
price	number(9,2)	Unit price of the goods in the order. total_fee=price×quantity must be met if this parameter is passed.	N	0.01
quantity	String(100)	Quantity of the goods. total_fee=price×quantity must be met if this parameter is passed.	N	1
goods_detail	String(512)	Detailed description of the goods in json format. Refer to 4.3 for details.	N	[{"goodsName":"ipad","price":"2000.00","quantity":"1","goodsCategory":"7788230"}]
extend_params	String(512)	This parameter contains extended parameters of the request, and transmits business information of the merchant. Format: JSON.	Y	{"store_id":"PINE","secondary_merchant_industry":"5311","secondary_merchant_name":"Pineapple Tech","store_name":"Pineapple Tech","secondary_merchant_id":"PINE"}
it_b_pay	String(200)	Set the Timeout of the payment of the order, the trade will be automatically closed once the timeout. The value range: 1m～15d, m-minute, h-hour, d- day, 1c-that day. (In the condition of 1c-that day, the trade will be closed wat 0:00 whenever it is created.) Don’t keep decimal point, for example, 1.5h can be transformed into 90 min. To enable this function, contact Alipay to configure the close time.	N	1d
passback_parameters	String(256)	If merchant transfer this parameter by the request string, Alipay will feedback this parameter by the asynchronous notify (parameter name: extra_common_param).	N	test
trans_currency	String(10)	Currency of the price of the order.	Y	TWD
timestamp	String(32)	The time when the order is created	N	1456507704102

#goods_detail

Parameter	Type	Description	Required	Sample
goodsName	String	Goods name	Y	ipad
goodsCategory	String	Goods category	N	7788230
showUrl	String	The link of goods on the cashier page	N	http://www.taobao.com
quantity	String	The quantity of the goods	Y	1
body	String	The description of the goods	N	特价手机
price	String	The unit price of the goods	Y	2000

Data structure:

copy

[
{ goodsName:<Goods name 1>, showUrl:<The link of goods 1>, quantity:<Goods quantity 1>, body:<Goods description1>, price:<Goods price1>, goodsCategory:< Goods category 1>}
,
{ goodsName:<Goods name 2>, showUrl:<The link of goods 2>, quantity:<Goods quantity 2>, body:<Goods description2>, price:<Goods price2>, goodsCategory:< Goods category 2>}
,
…
]

Sample：

copy

goods_detail=[{"goodsName":"ipad","price":"2000.00","quantity":"1","goodsCategory":"7788230"}]

#extend_params

Parameter	Type	Description	Required	Sample
secondary_merchant_id	String	Secondary merchant ID, must be passed.	Y	A80001
secondary_merchant_name	String	Secondary merchant name. Can be null only in cross-border agency acquiring mode and the name is verified.	Y	Muku
secondary_merchant_industry	String	mcc code of the merchant	Y	7011
store_name	String	Store name. Can be null only when the store information is verified.	Y	Muku in the Dreieichstrabe
store_id	String	Store ID, must be passed.	Y	BJ_ZZ_001
terminal_id	String	Terminal ID	N	T80001
sys_service_provider_id	String(32)	The technical provider id. This parameter identifies the payment system provider.	N	R00998889911

Data structure：

copy

secondary_merchant_id: <secondary_merchant_id>, secondary_merchant_name: <secondary_merchant_name>, secondary_merchant_industry: <secondary_merchant_industry>, store_name: <store_name>, store_id: <store_id>, terminal_id: <terminal_id>

Note: for the business extend parameter, only one store’s information is supported to be passed.

Samples: pass the store ID, the store type and the brand number：

copy

extend_params={"store_id":"PINE","secondary_merchant_industry":"5311","secondary_merchant_name":"Pineapple Tech","store_name":"Pineapple Tech","secondary_merchant_id":"PINE"}

#Sample of request

copy

https://intlmapi.alipay.com/gateway.do?operator_id=sky&subject=%E5%88%86%E8%B4%A6%E6%B5%8B%E8%AF%95-sky&sign_type=MD5&notify_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_notify.htm&out_trade_no=205211376305670&sign=9aae99502a8dd70e67d3d3575f7176cd&_input_charset=UTF-8&price=0.01&it_b_pay=1d&product_code=OVERSEAS_MBARCODE_PAY&total_fee=0.01&service=alipay.acquire.create&seller_id=2088101106499364&quantity=1&partner=2088101106499364&extend_params=%7B%22STORE_id%22%3A%22323231%22%2C%22STORE_TYPE%22%3A%221%22%7D&alipay_ca_request=2&ref_ids=%5b%7b%26quot%3bid_type%26quot%3b%3a%26quot%3borig_out_request_no%26quot%3b%2c%26quot%3bid%26quot%3b%3a%26quot%3bHZ0001%26quot%3b%7d%2c%7b%26quot%3bid_type%26quot%3b%3a%26quot%3borig_out_order_no%26quot%3b%2c%26quot%3bid%26quot%3b%3a%26quot%3bHZ0001%26quot%3b%7d%5d

#Synchronous response

After Alipay processes the request data offered by merchants, it feeds back the result to merchants in order that merchants can start further processing accordingly.
There are two cases of response results, one result is that the business is accepted normally; the other result is system-level exceptance or the request data is incorrect. If the business is accepted normally, merchants need to parse the response code to judge wether the business is successfully processed.

#Response parameters

Parameter	Type	Description	Required	Sample
Basic parameters
is_success	String	Request succeeds or not. Successful request does not mean the business is accepted and processed successfully. T means success F means failure	Y	T
sign_type	String	The value can be one of DSA, RSA, or MD5. Uppercase must be used	N	MD5
sign	String	Sign value	N	97ef60dd5015aa311058fcaf2d2ac8e3
error	String	If the request succeeds, there is no this parameter. If the request fails, the parameter is error code.	N	ILLEGAL_SIGN
Business parameters
result_code	String	SUCCESS：Order succeeds; FAIL：Order fails; UNKNOWN：The result is unknown	Y	SUCCESS
trade_no	String	The serial number of the trade in Alipay system. The range of the length value: 16-64	N	2013111811001004410070187794
out_trade_no	String	The merchant order number instead of the Alipay trade number. The number must be unique in merchant’s system and will be returned as it is after request.	N	6409624505322427
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.	N	2.19
detail_error_code	String	Cause description of the result code. Refer to “10.1 business error code”. If the result_code is SUCCESS, this parameter will not be returned.	N	TRADE_BUYER_NOT_MATCH
detail_error_des	String	Explain the detailed error code by using words. If the result_code SUCCESS this parameter will not be returned.	N	Doesn't match with the trade buyer

Note：The synchronous response parameter may have extra tags due to the evolution of the Alipay server side, program users can ignore those extra tags which is not explained in this API document.

#Sample

#Business acceptance is normal and query is successful：

copy

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="body">珠宝饰品</param>
        <param name="operator_id">8888</param>
        <param name="subject">测试</param>
        <param name="sign_type">MD5</param>
        <param name="out_trade_no">3618810634349901</param>
        <param name="royalty_parameters">
[{"serialNo":"1","transOut":"2088101126765726","transIn":"2088101126708402","amount":"0.10","desc":"分账测试1"},{"serialNo":"2","transOut":"2088101126765726","transIn":"2088101126707869","amount":"0.10","desc":"分账测试2"}]</param>
        <param name="royalty_type">ROYALTY</param>
        <param name="total_fee">20.00</param>
        <param name="partner">2088101126765726</param>
        <param name="quantity">2</param>
        <param name="alipay_ca_request">2</param>
        <param name="sign">42fff1757f72510e2027bf03879f03a9</param>
        <param name="goods_detail">
[{"goodsName":"ipad","price":"2000.00","quantity":"1"},{"goodsName":"ipad2","price":"2000.00","quantity":"1"}]</param>
        <param name="_input_charset">UTF-8</param>
        <param name="price">10</param>
        <param name="it_b_pay">50m</param>
        <param name="product_code">OVERSEAS_MBARCODE_PAY</param>
        <param name="service">alipay.acquire.create</param>
        <param name="seller_id">2088101126765726</param>
        <param name="seller_email">yuezhuzhanghu@alitest.com</param>
        <param name="extend_params">{"STORE_ID":"323231","STORE_TYPE":"1"}</param>
    </request>
    <response>
        <alipay>
            <out_trade_no>6409624505322427</out_trade_no>
            <trade_no>2013111811001004410070187794</trade_no>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    <sign>97ef60dd5015aa311058fcaf2d2ac8e3</sign>
    <sign_type>MD5</sign_type>
</alipay>

#Request succeeds, business process falis

copy

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="body">珠宝饰品</param>
        <param name="operator_id">8888</param>
        <param name="subject">测试</param>
        <param name="sign_type">MD5</param>
        <param name="out_trade_no">3618810634349901</param>
        <param name="royalty_parameters">
[{"serialNo":"1","transOut":"2088101126765726","transIn":"2088101126708402","amount":"0.10","desc":"分账测试1"},{"serialNo":"2","transOut":"2088101126765726","transIn":"2088101126707869","amount":"0.10","desc":"分账测试2"}]</param>
        <param name="royalty_type">ROYALTY</param>
        <param name="total_fee">20.00</param>
        <param name="partner">2088101126765726</param>
        <param name="quantity">2</param>
        <param name="alipay_ca_request">2</param>
        <param name="sign">42fff1757f72510e2027bf03879f03a9</param>
        <param name="goods_detail">
[{"goodsName":"ipad","price":"2000.00","quantity":"1"},{"goodsName":"ipad2","price":"2000.00", "quantity":"1"}]</param>
        <param name="_input_charset">UTF-8</param>
        <param name="price">10</param>
        <param name="it_b_pay">50m</param>
        <param name="product_code">OVERSEAS_MBARCODE_PAY</param>
        <param name="service">alipay.acquire.create</param>
        <param name="seller_id">2088101126765726</param>
        <param name="seller_email">yuezhuzhanghu@alitest.com</param>
        <param name="extend_params">{"STORE_id":"323231","STORE_TYPE":"1"}</param>
    </request>
    <response>
        <alipay>
            <result_code>FAIL</result_code>
            <detail_error_code>TRADE_BUYER_NOT_MATCH</detail_error_code>
            <detail_error_des>交易买家不匹配</detail_error_des>
        </alipay>
    </response>
    <sign>97ef60dd5015aa311058fcaf2d2ac8e3</sign>
    <sign_type>MD5</sign_type>
</alipay>

#Request fails or request data is incorrect

copy

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>