Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

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:

EnvironmentHTTPS request URL
Production environment

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

Test environment

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

Basic request parameters:

ParameterTypeDescriptionRequiredSample
serviceStringThe name of the interface.

Y

alipay.acquire.create
partnerString(16)The unique number of an Alipay parter. The parter ID consists of 16 numbers that begin with 2088.

Y

2088101106499364
_input_charsetStringThe encoding format that merchants use for websites. Such as utf-8, gbk, gb2312, etc.

Y

utf-8
sign_typeStringThe value can be one of DSA, RSA, or MD5. Uppercase must be used.

Y

MD5
signStringSign value

Y

9aae99502a8dd70e67d3d3575f7176cd
notify_urlStringThe URL configured to receive the async notification from Alipay server.

N

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

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

DescriptionRequiredSample
out_trade_noString(64)The unique order number on the merchant’s site.

Y

205211376305670
subjectString(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_codeString(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_feenumber(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_idString(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_emailString(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_idString(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_emailString(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
bodyString(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_urlString(400)The hyperlink of goods on the cashier page

N

http://www.taobao.com
currencyString(10)Currency for merchants to settle the order

Y

USD
pricenumber(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
quantityString(100)Quantity of the goods. total_fee=price×quantity must be met if this parameter is passed.

N

1
goods_detailString(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_paramsString(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_payString(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_parametersString(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_currencyString(10)Currency of the price of the order.

Y

TWD
timestampString(32)The time when the order is created

N

1456507704102

goods_detail

ParameterTypeDescriptionRequiredSample
goodsNameStringGoods name

Y

ipad
goodsCategoryStringGoods category

N

7788230
showUrlStringThe link of goods on the cashier page

N

http://www.taobao.com
quantityStringThe quantity of the goods

Y

1
bodyStringThe description of the goods

N

特价手机
priceStringThe 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

ParameterTypeDescriptionRequiredSample
secondary_merchant_idStringSecondary merchant ID, must be passed.

Y

A80001
secondary_merchant_nameStringSecondary merchant name. Can be null only in cross-border agency acquiring mode and the name is verified.

Y

Muku
secondary_merchant_industryStringmcc code of the merchant

Y

7011
store_nameStringStore name. Can be null only when the store information is verified.

Y

Muku in the Dreieichstrabe
store_idStringStore ID, must be passed.

Y

BJ_ZZ_001
terminal_idStringTerminal ID

N

T80001
sys_service_provider_idString(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

ParameterTypeDescriptionRequiredSample
Basic parameters
is_successStringRequest succeeds or not. Successful request does not mean the business is accepted and processed successfully. T means success F means failure

Y

T
sign_typeStringThe value can be one of DSA, RSA, or MD5. Uppercase must be used

N

MD5
signStringSign value

N

97ef60dd5015aa311058fcaf2d2ac8e3
errorStringIf the request succeeds, there is no this parameter. If the request fails, the parameter is error code.

N

ILLEGAL_SIGN
Business parameters
result_codeStringSUCCESS:Order succeeds; FAIL:Order fails; UNKNOWN:The result is unknown

Y

SUCCESS
trade_noStringThe serial number of the trade in Alipay system. The range of the length value: 16-64

N

2013111811001004410070187794
out_trade_noStringThe 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_amountNumberIf 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_codeStringCause 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_desStringExplain 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>