3. Creating order using alipay.acquire.create
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 | |
Test environment |
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:
[
{ 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:
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:
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:
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
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¬ify_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:
<?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
<?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
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>