3. Creating order using alipay.acquire.create

Last updated: 2019-4-8

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:

[
{ 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&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:

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

If you have any question, please contact us