alipay.acquire.createandpay
Auto-debit creation & payment interface -- alipay.acquire.createandpay
Merchant creates trade through this Interface and conduct withholding payment or initiate payment with checkout counter under the circumstances that all conditions are met.
Request
Service address
Environment | HTTPS request URL |
Production environment | |
Test environment |
Request parameters
Parameter | Type(length) | Description | Required | Example |
Basic parameter | ||||
service | String | Service Name | Y | alipay.acquire.createandpay |
partner | String(16) | Partner ID that is composed of 16 digits beginning with 2088. | Y | 2088101568358171 |
_input_charset | String | The charset with which the request data is encoded. UTF-8 is supported. | Y | utf-8 |
sign_type | String | Sign type. RSA2, RSA, and MD5 are supported. Use uppercase. | Y | MD5 |
sign | String | Sign value | Y | 85bf83f78d5cefb804bd805532fc688e |
notify_url | String(190) | The URL for receiving asynchronous notifications after the payment is completed. | N | http://api.test.alipay.net/atinterface/receive_notify.htm |
Business parameter | ||||
out_trade_no | String(64) | Unique order ID in Alipay’s merchant website | Y | 4652151518967003 |
subject | String(256) | Goods title/trade tile/order subject/order key word etc. The length of this parameter is up to 128 Chinese characters. | Y | Payment by sound wave –royalty distribution-sky |
product_code | String(32) | Order placement used to distinguish the business type: The following 5 types are supported at present:
| Y | FOREX_GENERAL_WITHHOLDING or GENERAL_WITHHOLDING |
total_fee | number (9,2) | Total fee of this order. The range of values is [0.01, 100000000], such value can have up to two digits after the decimal point. | Y | 10 |
body | String(400) | Specific description of the trade. In case of a variety of goods, please accumulate the character strings descrbing the goods, and transmit the same to body. | N | iphone cellphone |
show_url | String(400) | Hyperlink for the show of goods on the webpage of checkout counter. | N | http://www.taobao.com/product/113714.html |
currency | String(8) | Settlement currency. Currency and trans_currency cannot be different foreign currency. | Y | USD |
trans_currency | String(8) | Pricing currency for the transaction, if it is not CNY, the CNY amount user will be charged will be calculated based on trans_currency and exchange rate. | Y | USD |
agreement_info | String(256) | Be Used for transferring the agreement informaiotn between user and Alipay, json format, refer to agreement_info. | Y | {"agreement_no":"20141107000377985008"} |
extend_params | String(128) | Be used for transmitting specific business information of the merchant; this parameter will only be valid if 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; such information shall be written in the format of json. | Merchant direct-contract with Alipay: N System provider: Y | {"STORE_ID":"BJ_ZZ_001","STORE_NAME":"Muku in the Dreieichstrabe","SECONDARY_MERCHANT_ID":"A80001","SECONDARY_MERCHANT_NAME":"Muku","SECONDARY_MERCHANT_ INDUSTRY":"7011"} |
trade_information | String(6000) | Information about the trade industry. See trade_information for details. | Y | {"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"} |
trade_information
Parameter | Type(length) | Description | Required | Example |
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, separate type values with vertical bar (|). | Y | 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). | Y | 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). | Y | 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). | Y | 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). | Y | NWS 996|TWF 8854 |
departure_time | Date | Departure time. Format: yyyy-MM-dd HH:mm Timezone: GMT +8. If flight transfer exists, separate time values with vertical bar (|). Specify this field only when business_type is 2 (AIR). | Y | 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. | Y | 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). | Y | 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). | Y | 8 |
other_business_type | String | If business_type is 5 (Others), specify the business type in details. | Y | Airport pick up service |
agreement_info
Parameter | Type(length) | Description | Required | Example |
agreement_no | String | Represent the agreement number that user signed in Alipay.such as agreement deduct number. | N | 20141107000377985008 |
Response
Synchronous response
Parameter | Type(length) | Description | Required | Example |
Basic parameters | ||||
is_success | String | Request succeeds or not. Successful request does not mean the business is accepted and processed successfully. T: success F: failure | Y | T |
sign_type | String | Sign type. DSA, RSA, and MD5 are supported. Use uppercase. | N | MD5 |
sign | String | Sign value | N | ea489fc31da63253ba b52ed77fb45eb7 |
error | String | This parameter does not exist if request succeeds; This parameter is error coade if request fails; please refer to System errors | N | ILLEGAL_SIGN |
Business parameters | ||||
result_code | String(32) | Response code of the processing result of order placement and payment; please refer to Business response codes. | Y | ORDER_SUCCESS_ PAY_SUCCESS |
trade_no | String(64) | Trade number of the trade in Alipay system 16 bits at least, 64 bits at most | N | 2013112311001004940000384027 |
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. | N | 7085502131376415 |
buyer_user_id | String(30) | Unique Alipay user ID corresponding to Buyer’s Alipay logon ID.16 numbers beginning with 2088 | N | 2088102105236945 |
buyer_logon_id | String(100) | Buyer’s Alipay logon ID, may be email or phone number. Part of information is hidden. | N | 138****0011 |
currency | String(8) | Settlement currency. Same as the input. | N | CNY |
trans_currency | String(8) | Pricing currency for the transaction. Same as the input. | N | CNY |
forex_rate | String | Exchange rate between foreign currency and CNY. | N | 6.0939 |
total_fee | Number | Total transaction amount of the order in CNY. | N | 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 | N | 10.00 |
detail_error_code | String(48) | Give cause description to the response code returned. Please refer to Business errors. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned. | N | TRADE_BUYER_NOT_MATCH |
detail_error_des | String(64) | Give literal statement as to the detailed error code. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned. | N | Trade does not match with buyer |
display_message | String(64) | Give literal statement as to the detailed error message. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned. | N | Trade does not match with buyer |
Asynchronous response
Parameter | Type(length) | Description | Required | Example |
Basic parameter | ||||
notify_time | Date | Time of sending notify. Format: yyyy-MM-dd HH:mm:ss | Y | 2013-11-27 15:45:58 |
notify_type | String | Notigy type | Y | trade_status_sync |
notify_id | String | Notify authencitation ID | Y | ac05099524730693a8b 330c5ecf72da978 |
sign_type | String | Sign type. DSA, RSA, and MD5 are supported. Use uppercase. | Y | MD5 |
sign | String | Sign value | Y | 601510b7970e52cc63d b0f44997cf70e |
notify_action_type | String | Notify action type: Create: createDirectPayTradeBy BuyerAction Pay: payByAccountAction Refund: refundFPAction Cancel: reverseAction Close: closeTradeAction Finish: finishFPAction | N | payByAccountAction |
Business parameter | ||||
out_trade_no | String(64) | Unique order ID in order system in ccorresponding 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 orginal shape. | N | 5431395578198135 |
subject | String(256) | Goods title/trade tile/order subject/order key word etc. This pramater is in the first column in Alipay trade details and is important for account checking. This is a parameter transmitted upon corresponding request, which shall be returned in its orginal shape. | N | soundwave_pay-royalty distribution-sky |
trade_no | String(64) | Trade number of the trade in Alipay system 16 bits at least, 64 bits at most | N | 2013112711001004940 000394507 |
trade_status | String | Please refer to Trade Status for the value range of current trade status | N | WAIT_BUYER_PAY |
gmt_create | Date | Time of creating this trade. Format: yyyy-MM-dd HH:mm:ss. | N | 2013-11-27 15:45:57 |
gmt_payment | Date | Time of paying for this trade by buyer. Format: yyyy-MM-dd HH:mm:ss. | N | 2013-11-27 15:45:57 |
seller_email | String(100) | Seller’s Alipay account, may be email and phone number | N | test@alitest.com |
buyer_email | String(100) | Buyer’s Alipay account, may be email or phone number | N | 13882390011 |
seller_id | String(30) | Unique Alipay user ID corresponding to Seller’s Alipay account 16 numbers beginning with 2088 | N | 2088101106499364 |
buyer_id | String(30) | Unique Alipay user ID corresponding to buyer’s Alipay account 16 numbers beginning with 2088 | N | 2088102105236945 |
price | Number | This is a price parameter transmitted upon corresponding request, which shall be returned in its orginal shape. | N | 1.00 |
quantity | Number | This is a quantity parameter transmitted upon corresponding request, which shall be returned in its orginal shape. | N | 10 |
total_fee | Number | Total transaction amount of the order in CNY. | N | 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 | N | 10.00 |
currency | String(8) | Settlement currency | N | CNY |
trans_currency | String(8) | Pricing currency | N | CNY |
forex_rate | String | Exchange rate between foreign currency and CNY | N | 6.0939 |
body | String(400) | Remark, description and details of the order. This is a body parameter transmitted upon corresponding request, which shall be returned in its orginal shape. | N | Hello |
refund_fee | Number | Refunded amount returned in refund notify. Unit: Yuan. | N | 1.00 |
out_biz_no | String(64) | Merchant’s business ID, mainly refers to the refund application number returned in refund notify. | N | HZRF001 |
paytools_pay_amount | String(512) | Information about the amount successfully paid through each channel; please refer to paytools_pay_amount. | N | [{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANK CARD":"5.55"}] |
extra_common_param | String(256) | This parameter returned upon corresponding request parameter:passback_parameters | N | test |
paytools_pay_amount
Parameter | Type(length) | Description | Required | Example |
ALIPAYA CCOUNT | String | Represent the amount paid by balance in Alipay account; unit: Yuan | N | 1.23 |
MCARD | String | Represent the amount paid by merchant’s prepaid card; unit: Yuan | N | 7.94 |
MDISCOUNT | String | Represent the amount paid by merchant’s discount coupon; unit: Yuan | N | 1.23 |
TMPOINT | String | Represent the amount paid by Tmall point; unit: Yuan | N | 1.69 |
COUPON | String | Represent the amount paid by coupon; unit: Yuan | N | 1.23 |
POINT | String | Represent the amount paid by Point Treasury; unit: Yuan | N | 1.23 |
DISCOUNT | String | Represent the amount paid by account discount; unit: Yuan | N | 1.23 |
BANKCARD | String | Represent the amount paid by bank card; unit: Yuan | N | 5.55 |
MONEYFUND | String | Represent the amount paid by Balance Treasury; unit: Yuan | N | 1.23 |
BAITIAO | String | The payment amount which use blank note. Unit: RMB. | N | 1.23 |
MCOUPON | string | The payment amount which use red envelope. Unit: RMB | N | 2.21 |
PCARD | String | The payment amount which use Alipay card. Unit: RMB. | N | 2.13 |
PCREDIT | string | The payment amount which use Alipay credit. Unit: RMB | N | 1.23 |
Result codes
Business response code
Response code | Description |
ORDER_FAIL | The ordering fails. |
ORDER_SUCCESS_PAY_SUCCESS | Both the ordering and the payment succeed. |
ORDER_SUCCESS_PAY_FAIL | The ordering succeeds, but the payment fails. |
ORDER_SUCCESS_PAY_INPROCESS | The ordering succeeds and the payment is under processing. |
UNKNOWN | The processing result is unknown. |
Business errors
Error code | Description |
TRADE_SETTLE_ERROR | Verification of royalty distribution information fails. |
TRADE_BUYER_NOT_MATCH | The buyer is unmatched. |
CONTEXT_INCONSISTENT | Trade information has been altered. |
TRADE_HAS_SUCCESS | The payment of trade has been made. |
TRADE_HAS_CLOSE | The trade has been closed. |
REASON_ILLEGAL_STATUS | The trade status is illegal. |
EXIST_FORBIDDEN_WORD | Banned words are included in order information. |
PARTNER_ERROR | Partner information is incorrect. |
ACCESS_FORBIDDEN | Has no right to use the product. |
SELLER_NOT_EXIST | The seller does not exist. |
BUYER_NOT_EXIST | The buyer does not exist. |
BUYER_ENABLE_STATUS_FORBID | The buyer status is illegal and the trade cannot be continued. |
BUYER_SELLER_EQUAL | The seller and the buyer have the same account and the trade cannot be conducted. |
INVALID_PARAMETER | Parameter is invalid. |
UN_SUPPORT_BIZ_TYPE | Unsupported business type |
INVALID_RECEIVE_ACCOUNT | The seller is not included in receiving account list. |
BUYER_PAYMENT_AMOUNT_DAY_LIMIT_ERROR | The buyer’s payment on the payment day exceeds limit. |
ERROR_BUYER_CERTIFY_LEVEL_LIMIT | The buyer fails to pass verification conducted by People’s Bank of China. |
ERROR_SELLER_CERTIFY_LEVEL_LIMIT | The seller fails to pass verification conducted by People’s Bank of China. |
CLIENT_VERSION_NOT_MATCH | The wallet version is obsolete. Please update it to the latest version before use. |
AUTH_NO_ERROR | Authorization number is wrong for which the possible reasons include:
The receiver owning the authorization number is not the same as the request receiver. |
BUYER_BANKCARD_BALANCE_NOT_ENOUGH | Buyer bankcard balance is not enough. |
PULL_MOBILE_CASHIER_FAIL | Fail to pull mobile cashier. |
PAYMENT_FAIL | Fail to payment. |
MOBILE_PAYMENT_SWITCH_OFF | Wireless switch is closed, unable to pay. |
SOUNDWAVE_PARSER_FAIL | Soundwave/barcode parse fail. |
ERROR_BALANCE_PAYMENT_DISABLE | Balance payment function is closed. |
ORDER_UN_SUPPORT_PROMOTE | This order does not support the specified discount. |
BUYER_BALANCE_NOT_ENOUGH | Buyer balance is not enough. |
SELLER_BEEN_BLOCKED | Seller account is blocked. |
BEYOND_PAY_RESTRICTION | Beyond pay restriction. |
BEYOND_PER_RECEIPT_RESTRICTION | The seller amount receivable more than month restriction. |
TOTAL_FEE_EXCEED | Order amount exceed the limit. |
VOUNCHER_NOT_EXIST | Merchant coupons does not exist. |
BUYER_PAYMENT_COUNT_DAY_LIMIT_ERROR | Buyer payment count of one day exceed the limit. |
BUYER_PAYMENT_COUNT_MONTH_LIMIT_ERROR | Buyer payment count of one month exceed the limit. |
CLIENT_NOT_ONLINE | User client is not online, so that unable pull mobile cashier. |
TRADE_STATUS_ERROR | Trade status error. |
BUYER_PAYMENT_AMOUNT_MONTH_LIMIT_ERROR | Buyer payment amount of one month exceed the limit. |
PRODUCT_AMOUNT_LIMIT_ERROR | Product amount exceed the limit. |
PAYMENT_REQUEST_HAS_RISK | Payment has risk. |
DUPLICATE_PAY_CURRENCY_NOT_EQUAL | Duplicate payment currency is inconsistent with the first payment currency. |
AGREEMENT_NOT_EXIST | Agreement information is not exist. |
AGREEMENT_INVALID | Agreement is invalid. |
AGREEMENT_ERROR | Abnormal agreement information. |
NO_PAYMENT_INSTRUMENTS_AVAILABLE | There is not available payment instruments. |
USER_LOGONID_DUP | The user’s logonid is duplicated with other people (special case when a user is using cell phone number as logon id) |
EXCHANGE_AMOUNT_OR_CURRENCY_ERROR | The exchange amount or currency is error |
Access errors
Error code | Description |
ILLEGAL_SIGN | Illegal signature. |
ILLEGAL_DYN_MD5_KEY | Dynamic key information is incorrect. |
ILLEGAL_ENCRYPT | Encryption is incorrect. |
ILLEGAL_ARGUMENT | Parameter is incorrect. |
ILLEGAL_SERVICE | Service parameter is incorrect. |
ILLEGAL_USER | User ID is incorrect. |
ILLEGAL_PARTNER | Partner ID is incorrect. |
ILLEGAL_EXTERFACE | Interface configuration is incorrect. |
ILLEGAL_PARTNER_EXTERFACE | Partner’s interface information is incorrect. |
ILLEGAL_SECURITY_PROFILE | Matching private key configuration has not been found. |
ILLEGAL_AGENT | Agency ID is incorrect. |
ILLEGAL_SIGN_TYPE | The signature type is incorrect. |
ILLEGAL_CHARSET | The character set is illegal. |
HAS_NO_PRIVILEGE | Has no right to visit. |
INVALID_CHARACTER_SET | The character set is invalid. |
System errors
Error code | Description |
SYSTEM_ERROR | Alipay system error |
SESSION_TIMEOUT | Session timeout |
ILLEGAL_TARGET_SERVICE | Wrong target_service |
ILLEGAL_ACCESS_SWITCH_SYSTEM | Merchant is not allowed to visit system of this type. |
EXTERFACE_IS_CLOSED | The interface has been closed. |
Trade status
Code | Description |
WAIT_BUYER_PAY | The trade has been established and is waiting for the buyer to make payment. |
TRADE_CLOSED |
|
TRADE_SUCCESS | The trade succeeds and is operable, such as multi-level royalty distribution, refund, etc. |
TRADE_PENDING | Wait for the seller to collect payment (if the seller’s account is frozen after the buyer has made the payment). |
TRADE_FINISHED | The trade succeeds and finishes and is not operable. |
Payment channel
Code | Payment channel |
00 | Alipay Coupon |
10 | Alipay balance |
60 | Alipay pre-deposit card |
30 | Points |
70 | Credit payment |
40 | Discount coupon |
80 | Prepaid card |
90 | Credit payment (consumption credit) |
100 | Special Alipay account for financial management |
101 | Merchant’s shop card |
102 | Merchant’s discount coupon |
103 | Blank note |
104 | Red envelope |
Samples
Request sample
Response sample
Synchronous response sample
Business is accepted and processed normally, and acquiring is created successfully:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request><param name="body">soundwave_pay-royalty-sky</param>
<param name="operator_id">55</param><param name="subject">soundwave_pay-royalty-sky</param>
<param name="sign_type">MD5</param>
<param name="out_trade_no">7085502131376415</param>
<param name="dynamic_id">kfylrwezsbeqhh553e</param>
<param name="royalty_parameters"> [{"serialNo":"1","transOut":"2088101126765726","transIn":"208810112670840
2","amount":"1.00","desc":"royalty distribution test 1"}]
</param>
<param name="royalty_type">ROYALTY</param>
<param name="total_fee">10</param>
<param name="partner">2088101106499364</param>
<param name="quantity">10</param>
<param name="dynamic_id_type">soundwave</param>
<param name="alipay_ca_request">2</param>
<param name="sign">a1cb41a4019351965d4418c9cb933f0f</param>
<param name="_input_charset">UTF-8</param>
<param name="price">1</param>
<param name="it_b_pay">1d</param>
<param name="product_code">SOUNDWAVE_PAY_OFFLINE</param>
<param name="service">alipay.acquire.createandpay</param>
<param name="seller_id">2088101106499364</param>
</request>
<response>
<alipay>
<buyer_logon_id>138****0011</buyer_logon_id>
<buyer_user_id>2088102105236945</buyer_user_id>
<out_trade_no>7085502131376415</out_trade_no>
<result_code>ORDER_SUCCESS_PAY_SUCCESS</result_code>
<trade_no>2013112311001004940000384027</trade_no></alipay>
</response>
<sign>ea489fc31da63253bab52ed77fb45eb7</sign>
<sign_type>MD5</sign_type>
</alipay>
Request succeeds, business processing fails:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request><param name="body">soundwave_pay-royalty distribution-sky</param>
<param name="operator_id">55</param><param name="subject">soundwave_pay-royalty distribution-sky</param>
<param name="sign_type">MD5</param>
<param name="out_trade_no">7085502131376415</param>
<param name="dynamic_id">kfylrwezsbeqhh553e</param>
<param name="royalty_parameters"> [{"serialNo":"1","transOut":"2088101126765726","transIn":"208810112670840
2", "amount":"1.00", "desc":"royalty distribution test 1"}]
</param>
<param name="royalty_type">ROYALTY</param>
<param name="total_fee">10</param>
<param name="partner">2088101106499364</param>
<param name="quantity">10</param>
<param name="dynamic_id_type">soundwave</param>
<param name="alipay_ca_request">2</param>
<param name="sign">a1cb41a4019351965d4418c9cb933f0f</param>
<param name="_input_charset">UTF-8</param>
<param name="price">1</param>
<param name="it_b_pay">1d</param>
<param name="product_code">SOUNDWAVE_PAY_OFFLINE</param>
<param name="service">alipay.acquire.createandpay</param>
<param name="seller_id">2088101106499364</param>
</request>
<response>
<alipay>
<result_code>ORDER_FAIL</result_code>
<detail_error_code>TRADE_BUYER_NOT_MATCH</detail_error_code><detail_error_des>trade does not match with buyer</detail_error_des>
<trade_no>2013112311001004940000384027</trade_no>
</alipay>
</response>
<sign>ea489fc31da63253bab52ed77fb45eb7</sign>
<sign_type>MD5</sign_type>
</alipay>
Output when Request fails or the data accessed is wrong:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Asynchronous response sample
http://address defined by merchant/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_email=zhuzhanghu%40alitest.com¬ify_type=trade_status_sync&buyer_email=13882390011&sign=601510b7970e52cc63db0f44997cf70e&trade_no=2013112711001004940000394507&buyer_id=2088102105236945&quantity=10&total_fee=10.00&price=1.00&gmt_create=2013-11-27+15%3A45%3A57&out_trade_no=5431395578198135&seller_id=2088101106499364¬ify_time=2013-11-27+15%3A45%3A58&subject=%E5%A3%B0%E6%B3%A2%E6%94%AF%E4% BB%98-%E5%88%86%E8%B4%A6-sky&trade_status=WAIT_BUYER_PAY&sign_type=MD5