上海翻譯公司完成電子系統(tǒng)“手機(jī)網(wǎng)頁(yè)即時(shí)到賬接口”英文翻譯
 

Alipay (China) Network Technology Co., Ltd.  All Rights Reserved

1 Document Description 

1.1 Function Description 

"Mobile Web Instant Payment Authorization Interface(alipay.wap.trade.create.direct)" and supporting the use of "Mobile Web Immediate Payment Transaction Interface(alipay.wap.auth.authAndExecute)" complete the instant payment transactions together.  

Authorization interface is used to store the information needed for merchants to create trades, and returns an authorization token (request_token); the value of authorization token (request_token) returned by transaction interface using authorization interface redirects page to the payment page of Alipay, so that the payer can directly deposit payment to another payee who has the Alipay account.  

Authorization interface does not actually create the instant payment transaction, the creation of instant payment transaction and the process of payment completion are completed by the transaction interface.    

1.2 Readers 

The document is prepared for the personnel who have the website development capability, learn about one of ASP, PHP, JAVA, ASP.NET development language and the website development, maintenance and management of SQL database language. 

1.3 Business terms 

Table 1-1 Business terms

Terms Explanation

Demand The process of transmitting the data requiring for delivery to the receiver 

Notification  Server aynchronous notice. After Alipay completes the data processing, Alipay will issue notice to the website of commercial user and give feedback to the commercial user website on the completed message after processing.  

Returning  Page Skipping synchronous notice. After Alipay completes the data processing, Alipay will skip from the current Alipay page to the website of commercial user and give feedback to the commercial user website on the completed message after processing.  

Payment Failure  Insufficient balances, exceeded credit limits, frozen trades, frozen accounts, paid orders, and the inconsistency of order amount and payment amount will result in payment failure.  

 

2 Function Demonstration

 

Figure 2-1 Mobile Web Instant Payment Transaction Flow Diagram

Step 1:  Obtain the authorization token 

Merchants call the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)", send order information to Alipay in order to obtain the authorization token. 

Step 2:  Instant Transaction Payment 

Merchants call the "Mobile Web Instant Payment Transaction Interface (alipay.wap.auth.authAndExecute)", verify the token value, complete payment after the creation of Alipay transaction, notify merchants and jump back to the specified page links. 

3 Data Interaction

 

Figure 3-1 Commercial user system requirement-Payment affects interactional mode

合作商戶(hù)系統(tǒng) System of commercial user in cooperation 

支付寶系統(tǒng) Alipay system 

構(gòu)造請(qǐng)求數(shù)據(jù) Structure request data

發(fā)送請(qǐng)求數(shù)據(jù) Issuing requirement data

請(qǐng)求的交易 Requested transaction 

返回相應(yīng)數(shù)據(jù) Return he corresponding data 

對(duì)相應(yīng)的數(shù)據(jù)進(jìn)行處理 Process the corresponding data 

 

(1) Structure request data

Commercial users obtain the data set with signature results transmitted to Alipay through the program according to the interface rule provided by Alipay. 

(2) Issuing requirement data 

Transmit the dataset in completed structure to Alipay through page link skipping or form list submitting. 

(3) Process the corresponding data 

After obtaining this set, at fist, adopt the safety verification. After a series of verification, the data request sent will be processed. 

(4) Return the processed result data 

 Authorization Interface 

Alipay will return the processed result data to merchants in the form of html. 

 Transaction Interface 

As for the transaction after completing processing, Alipay will give feedback to commercial user website in the following ways.

– The program automatically reconstructs the URL address link, and redirect to the page path address which is set at request time by merchants on the user's current page through auto-redirecting (parameter call_back_url is specified in the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)"; 

– Alipay server gives a notice actively to invoke the page path address designated in request (Parameter “return_url”, if the commercial user fails to set up, the operation will not be adopted.

(5) Process the obtained returned result data

 

 Authorization Interface 

Merchants use the programming methods to simulate http requesting the remote parsing of html, and carry out data processing based on the business logic of their own websites after accessing the result data returned by Alipay.  

 Transaction Interface 

After the synchronous notification processing page (parameter call_back_url specified page file) or the asynchronous notification page of server (parameter notify_url specified page file) receives the result data returned by Alipay, merchants can carry out data processing based on the business logic of their own websites (eg. order updates, automatically recharge to member accounts).  

4 Request Parameters

4.1 Descriptions of Request Parameters in Authorization Interface 

4.1.1 Meanings 

Request parameters are the request data provided for Alipay when commercial users have data interaction with Alipay, so as to benefit for Alipay to make further processing these data.

4.1.2 List 

Table 4-1 Description request parameter

Parameters Parameter name Type (field length) Parameter description Null or not Samples

Basic parameters 

service  Interface name  String  Interface name  Not Full  alipay.wap.trade.create.direct 

format  Request parameter format  String Request parameter format.  

Fixed value xml.  Not Full xml 

v  Interface version number  String  Interface version number.  

Fixed value 2.0.  Not Full 2.0 

partner  Cooperator ID  String(16)  Only user name of corresponding Alipay of signed Alipay account, composed of 16-bit pure number headed with 2088  Not Full 2088101000137799 

req_id  Request number  String(32)  Used for correlating request and response to prevent the replay of request.  

Alipay limits the request number  from the same partner must be unique.   Not Full 1282889689836 

sec_id  Signing method  The signing method to parameter.  

Value range:  

0001: RSA signature algorithm 

MD5: MD5 signature algorithm 

Not Full 0001

sign  Signature  String  The value from the signature to parameter in request or response.   Not Full VRVr7adPfsHblFjiBkGWryhKIKt+CaI4Cq2MA2wG1ENVuBAyFDlp3FbttndmID0USlfn22a9/6fQ+X+KPDE09hcTNz3gJ1edUiDWxHXY/ahTexCP79SDtoHx29uepXsHBe32DP0k9jZbfhpT8Ly0+ksuo5VJO0iymxQ87hQPjJw= 

Business parameters

 

Parameters Parameter name Type (field length) Parameter description Null or not Samples

req_data  Request business parameter  String  Please refer to the "Table 4-2 req_data Request Business Parameters List" for the request business parameters. 

<direct_trade_create_req>: Root node 

<subject>: Commodity name 

<out_trade_no>: The only order number of merchant website 

<total_fee>: Transaction amount

<seller_account_name>: The Alipay account of seller

<call_back_url>: The redirected page path after successful payment 

<notify_url>: The asynchronous notification page path of server

<out_user>: The unique identification for user in merchant system 

<merchant_url>: The return address of operation interrupt 

<pay_expire>: The automatic closing time of transaction Not Full <direct_trade_create_req><subject>Lottery</subject><out_trade_no>1282889603601</out_trade_no><total_fee>10.01</total_fee><seller_account_name>[email protected]</seller_account_name><call_back_url>http://www.yoursite.com/waptest0504/servlet/CallBack</call_back_url><notify_url>http://www.yoursite.com/waptest0504/servlet/NotifyReceiver</notify_url><out_user>123456789</out_user><merchant_url>http://www.yoursite.com</merchant_url><pay_expire>3600</pay_expire></direct_trade_create_req> 

 

Table 4-2 req_data Request Business Parameters List

Parameters Parameter name Type ( field length) Parameter description Null or not Samples

subject Commodity name String(256)  The commodity name purchased by user.   Not Full Lottery 

out_trade_no Sole order number of commercial website  String(64)  Sole order number of Alipay cooperator commercial website. Not Full 1282889603601 

total_fee Transaction amount String(15)  The total amount of this order, in the unit RMB-Yuan. The value range is [0.01，100000000.00], with up to two digits after the decimal point.   Not Full 10.01 

seller_account_name  Seller Alipay account String(100)  The Alipay account of seller. After the success of transaction, the funds of buyer will be transferred to this account.  Not Full [email protected] 

call_back_url  The redirected page path after successful payment  String(200)  The redirected page link after successful payment.   

The redirection will be made after successful payment.   Not Full http://www.yoursite.com/waptest0504/servlet/CallBack 

notify_url  The asynchronous notification page path of server  String(200)  The Alipay server actively notify the specified page http path in the merchant website.   Full http://www.yoursite.com/waptest0504/servlet/NotifyReceiver 

out_user  The unique identification for user in merchant system  String(32)  The unique identification for user in merchant system.   

After buyer successfully complete the payment for the first time, and next payment amount is within 30 RMB, the buyer needs not to input the password again.  Full 123456789 

merchant_url  The return address of operation interrupt  String  The returned merchant address after user drops out from payment.   Full http://www.yoursite.com 

pay_expire  The automatic closing time of transaction  String  The automatic closing time of transaction, in the unit minute.   

Default value 21600 (15 days). Full 3600 

 

Notes: 

 The value of parameter req_data cannot include the "&" character in full-width or half-width; 

 Part of the parameter types are String, without the specified length range, which indicate the system doesn't check the length of this parameter.  

 

4.1.3 Samples 

Notes: 􀁺 

 This sample is for reference only, and gateway of Alipay is http://wappaygw.alipay.com/service/rest.htm. 

 Blue color indicates the required parameters, green color indicates the parameters of fixed values, and red color indicates the optional parameters.  

 

http://wappaygw.alipay.com/service/rest.htm?req_data=<direct_trade_create_req><subject>Lottery</subject><out_trade_no>1282889603601</out_trade_no><total_fee>10.01</total_fee><seller_account_name>[email protected]</seller_account_name><call_back_url>http://www.yoursite.com/waptest0504/servlet/CallBack</call_back_url><notify_url>http://www.yoursite.com/waptest0504/servlet/NotifyReceiver</notify_url><out_user>123456789</out_user><merchant_url>http://www.yoursite.com</merchant_url><pay_expire>3600</pay_expire></direct_trade_create_req>&service=alipay.wap.trade.create.direct&sec_id=0001&partner=2088101000137799&req_id=1282889689836&sign=VRVr7adPfsHblFjiBkGWryhKIKt+CaI4Cq2MA2wG1ENVuBAyFDlp3FbttndmID0USlfn22a9/6fQ+X+KPDE09hcTNz3gJ1edUiDWxHXY/ahTexCP79SDtoHx29uepXsHBe32DP0k9jZbfhpT8Ly0+ksuo5VJO0iymxQ87hQPjJw=&format=xml&v=2.0 

4.2 Descriptions of Request Parameters in Transaction Interface 

4.2.1 Meaning 

Request parameters are the request data provided to Alipay when merchants are exchanging data with Alipay, in order for Alipay to carry out further processing based on these data.  

4.2.2 List  

Table 4-3 Descriptions of Request Parameters  

 

Parameters Parameter name Type (field length) Parameter description Null or not Samples

Basic parameters 

service  Interface name  String  Interface name  Not Full alipay.wap.auth.authAndExecute 

format  Request parameter format  String  Request parameter format.  

Fixed value xml.  Not Full xml 

v  Interface version number  String  Interface version number.  

Fixed value 2.0.  Not Full 2.0 

partner  Partner ID  String(16)  The unique Alipay user number corresponding to the Alipay account signed by merchant.  

The 16-bit pure number started with 2088.   Not Full 2088101000137799 

sec_id  Signing method  String  The signing method to parameter.  

Value range: 

0001: RSA signature algorithm 

MD5: MD5 signature algorithm  Not Full 0001 

sign  Signature  String  The value from the signature to parameter in request or response.   Not Full LdXbwMLug8E4UjfJMuYv2KoD5X5F3vHGQsQbZ/rdEQ3eaN4FPal7rhsbZZ/+ZUL1kAKzTQSDdMk87MEWtWO1Yq6rhnt2Tv8Hh6Hb16211VXKgbBCpq861+LopRwegPbGStcwBuAyE4pi6fYlJ6gxzL4tMyeLe+T5XZ0RKRUk00U= 

Business parameters

req_data  Request business parameter  String  Please refer to the "Table 4-4 req_data Request Business Parameters List" for the request business parameters. 

<auth_and_execute_req>: Root node 

<request_token>: Authorization token Not Full <auth_and_execute_req><request_token>201008309e298cf01c58146274208eda1e4cdf2b</request_token></auth_and_execute_req> 

 

Table 4-4 req_data Request Business Parameters List

Parameters Parameter name Type (field length) Parameter description Null or not Samples

request_token  Authorization token  String(40)  Authorization token. After successfully calling the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)", this value is returned. This parameter value cannot be changed.   Not Full 201008309e298cf01c58146274208eda1e4cdf2b 

 

Notes:  

 It can be redirected to call_back_url only if the payment is successful, while it is redirected to merchant_url when the payment fails (no parameter is returned). Redirection addresses are set in the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)". 

 Part of the parameter types are String, without the specified length range, which indicate the system doesn't check the length of this parameter. 

4.2.3 Samples

Notes:  

 This sample is for reference only, and gateway of Alipay is http://wappaygw.alipay.com/service/rest.htm. 

 All the parameters can be passed, blue color indicates the parameters of variable values, and green color indicates the parameters with fixed values.  

http://wappaygw.alipay.com/service/rest.htm?req_data=<auth_and_execute_req><request_token>201008309e298cf01c58146274208eda1e4cdf2b</request_token></auth_and_execute_req>&service=alipay.wap.auth.authAndExecute&sec_id=0001&partner=2088101000137799&sign=LdXbwMLug8E4UjfJMuYv2KoD5X5F3vHGQsQbZ/rdEQ3eaN4FPal7rhsbZZ/+ZUL1kAKzTQSDdMk87MEWtWO1Yq6rhnt2Tv8Hh6Hb16211VXKgbBCpq861+LopRwegPbGStcwBuAyE4pi6fYlJ6gxzL4tMyeLe+T5XZ0RKRUk00U=&format=xml&v=2.0 

5. Parameter Return 

5.1 Descriptions of html Synchronous Return Parameters in Authorization Interface 

5.1.1 Meaning 

After Alipay processes the request data provided by merchant, it will return the result data in order for the merchant to carry out further processing based on these data.  

5.1.2 List  

Table 5-1 html Descriptions of Synchronous Return Parameters 

Parameters Parameter name Type (length scope) Parameter description Null or not Samples

Basic parameters 

partner  Partner ID  String(16)  The unique Alipay user number corresponding to the Alipay account signed by merchant.  

The 16-bit pure number started with 2088.   Not Full 2088101000137799 

req_id  Request number  String(32)  Used for correlating request and response to prevent the replay of request.  

Alipay limits the request number  from the same partner must be unique.   Not Full 1282889689836 

sec_id  Signing method  String  The signing method to parameter.  

Value range:  

0001: RSA signature algorithm

MD5: MD5 signature algorithm Not Full MD5 

service  Interface Name  String  Interface Name.   Not Full alipay.wap.trade.create.direct 

v  Interface version number  String  Interface version number.  

Fixed value 2.0.  Not Full 2.0 

sign Signature String The value from the signature to parameter in request or response.  

No signature is required if the request fails, and there is no such parameters.  Nullable  72a64fb63f0b54f96b10cefb69319e8a

Business parameters

res_data  Return business parameter  String  Please refer to the "5.1.2 1. res_data Return Business Parameters".  

This value can only be returned when the request is successful.  

The most important authorization token request_token , which includes interface returns.  

<direct_trade_create_req>: Request root node 

<request_token>: Authorization token value Full <?xmlversion="1.0" encoding="utf-8"?><direct_trade_create_res><request_token>20100830e8085e3e0868a466b822350ede5886e8</request_token></direct_trade_create_res> 

res_error  Return parameter errors   String  Please refer to the "2. res_error Return Parameter Errors". 

This value can only be returned when the request fails.  

Including the error codes and error reasons of failed request.  

<err>: Return Error Root Node 

<code>, <sub_code>: Error code (the two values are the same at present)

<msg>: Error message  <detail>: Detailed description of error 

Please refer to "9.1 Mobile Web Instant Payment Transaction Error Code".   Full <?xml version="1.0" encoding="utf-8"?><err><code>0005</code><sub_code>0005</sub_code><msg>partner illegal</msg><detail>Partners have not open the interface access permissions</detail></err> 

 

1. res_data Return Business Parameter 

 

Table 5-2 res_data Return Business Parameters List

Parameters Parameter name Type (length scope) Parameter description Null or not Samples

request_token  Authorization token  String  Authorization token, this value can only be returned when the request is successful.    Not Full 20100830e8085e3e0868a466b822350ede5886e8 

 

2. res_error Return error parameter  

 

Table 5-3 res_error Return Error Parameters List

Parameters Parameter name Type (length range)  Parameter description Null or not Samples

code  Error code  String  When request fails, the error code is returned, corresponding to the "Error code (code)" in the "9.1 Mobile Web Instant Payment Transaction Error Code".   Not Full 0005 

sub_code  Error subcode  String  Reserved parameter, which is consistent with the parameter value of code currently.   Not Full 0005 

msg  Cause of error  String  The cause of error, corresponding to the "cause of error (msg)" in the "9.1 Mobile Web Instant Payment Transaction Error Code".   Not Full partner illegal 

detail  Detailed description of error  String  The detailed description of error, corresponding to the "detailed error description (detail)" in the " 9.1 Mobile Web Instant Payment Transaction Error Code". Not Full Partners have not open the interface access permissions 

 

 

5.1.3 Samples

 Normal Output:  

partner=2088101000137799&req_id=1282889689836&res_data=<?xmlversion="1.0" encoding="utf-8"?><direct_trade_create_res><request_token>20100830e8085e3e0868a466b822350ede5886e8</request_token></direct_trade_create_res>&sec_id=MD5&service=alipay.wap.trade.create.direct&v=2.0&sign=72a64fb63f0b54f96b10cefb69319e8a 

 Output when an error occurs:  

partner=208810100013779&req_id=1282889689836&res_error=<?xml version="1.0" encoding="utf-8"?><err><code>0005</code><sub_code>0005</sub_code><msg>partner illegal</msg><detail>Cooperating partner fails to open access right</detail></err>&sec_id=0001&service=alipay.wap.trade.create.direct&v=2.0 

5.2 Descriptions of Page Redirection Synchronous Notification Parameters in Transaction Interface 

5.2.1 Meaning 

After Alipay complete processing the request data of commercial users, it will notify the commercial user website through the way of automatic skipping of systemic controlling client end page. These processing result data is the page skipping synchronous notification parameter.

Alipay uses the GET method to access merchant websites (parameter call_back_url is specified in the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)".  

5.2.2 List table 

Table 5-4 Synchronous notification parameter description of page skipping

 

Parameters Parameter name Type (length scope) Parameter description Null or not Samples

sign  Signature String  The value from the signature to parameter in request or response.   Not Full 49a330fee069465c64e561a25bf31c78 

result  Payment Result  String  Judge the payment result and transaction status.   

Only if the payment is successful (namely result=success), it is redirected to the page of successful payment, result has one and only one transaction status of success.   Not Full success 

out_trade_no  The only order number of merchant website   String(64)  The only order number of the Alipay cooperated merchant websites.   Not Full 1320742949342 

trade_no  Alipay Transaction Number   String(32)  The transaction serial number of this transaction in the Alipay system.  

The shortest is 16 bits, while the longest is 64 bits.   Not Full 2011110823389231 

request_token  Authorization token  String(40)  Authorization token. After successfully calling the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)", this value is returned.   Not Full 201008309e298cf01c58146274208eda1e4cdf2b 

 

 

4.2.3 Samples 

http://www.xxx.com/alipay/call_back_url.php?out_trade_no=1320742949342&request_token=201008309e298cf01c58146274208eda1e4cdf2b&result=success&trade_no=2011110823389231&sign=49a330fee069465c64e561a25bf31c78 

Notes:  

 This sample is for reference only, and actual gateway of is the merchant domain name. 

 If the payment fails, it will be redirected to the passed parameter merchant_url in the "Mobile Web Instant Payment Authorization Interface (alipay.wap.trade.create.direct)", and it doesn't pass parameters when redirecting to merchant_url.  

 

5.3 Descriptions of Server Asynchronization Notification Parameters in Transaction Interface 

5.3.1 Meaning 

After Alipay completes the processing of merchant's request data, it will notify the processed result data to merchant website through the active notification method of server. These processing result data is the server asynchronization notification parameter. 

5.3.2 List table 

Table 5-5 Server asynchronous notification parameter description

Parameters Parameter name Type (field length) Parameter description Null or not Samples

Basic parameters 

service  Interface Name  String  Interface Name.   Not Full alipay.wap.trade.create.direct 

v  Interface version number  String  Interface version number.  

Fixed value 1.0.  Not Full 1.0 

sec_id  Signature way String  The signing method to parameter.  

Value range:  

0001: RSA signature algorithm

MD5: MD5 signature algorithm  Not Full 0001 

sign  Signature String  The value from the signature to parameter in request or response.   Not Full Rw/y4ROnNicXhaj287Fiw5pvP6viSyg53H3iNiJ61D3YVi7zGniG2680pZv6rakMCeXX++q9XRLw8Rj6I1//qHrwMAHS1hViNW6hQYsh2TqemuL/xjXRCY3vjm1HCoZOUa5zF2jU09yG23MsMIUx2FAWCL/rgbcQcOjLe5FugTc=

Business parameters

notify_data  Notify business parameter  String  Please refer to the "Table 5-6 notify_data Notify Business Parameters List" for the notified business parameters. 

<notify>: Notify root node 

<payment_type>: Payment type 

<subject>: Commodity name 

<trade_no>: Alipay transaction number

<buyer_email>: Buyer's Alipay account 

<gmt_create>: Transaction creation time 

<notify_type>: Notification type 

<quantity>: Purchase quantity 

<out_trade_no>: The only order number of merchant website 

<notify_time>: Notification time 

<seller_id>: Alipay account of seller

<trade_status>: Transaction status

<is_total_fee_adjust>: Adjust the total price or not 

<total_fee>: Transaction amount 

<gmt_payment>: Transaction payment time 

<seller_email>: Alipay account of seller 

<gmt_close>: Transaction closing time 

<price>: Unit price of commodity 

<buyer_id>: Buyer's Alipay user number 

<notify_id>: Notification verification ID 

<use_coupon>: Whether to use red envelope buyers Not Full <notify><payment_type>1</payment_type><subject>Cashier desk{1283134629741}</subject><trade_no>2010083000136835</trade_no><buyer_email>[email protected]</buyer_email><gmt_create>2010-08-30 10:17:24</gmt_create><notify_type>trade_status_sync</notify_type><quantity>1</quantity><out_trade_no>1283134629741</out_trade_no><notify_time>2010-08-30 10:18:15</notify_time><seller_id>2088101000137799</seller_id><trade_status>TRADE_FINISHED</trade_status><is_total_fee_adjust>N</is_total_fee_adjust><total_fee>1.00</total_fee><gmt_payment>2010-08-30 10:18:26</gmt_payment><seller_email>[email protected]</seller_email><gmt_close>2010-08-30 10:18:26</gmt_close><price>1.00</price><buyer_id>2088102001172352</buyer_id><notify_id>509ad84678759176212c247c46bec05303</notify_id><use_coupon>N</use_coupon></notify> 

 

Table 5-6 notify_data Notification Business Parameters List

Parameters Parameter name Type (field length) Parameter description Null or not Samples

payment_type  Payment Method  String  The payment method of user:   

1: Commodity purchasing;  

 4: Donation.  Not Full 1 

subject  Commodity name  String(256)  Commodity title/transaction title/order title/order keyword.  

It is in the first column of the Alipay transaction details, which is particularly important for financial reconciliation. The corresponding parameters in request are notified back in the original sample.   Not Full Cashier desk {1283134629741} 

trade_no  Alipay Transaction Number   String(32)  The transaction serial number of this transaction in the Alipay system.  

The shortest is 16 bits, while the longest is 64 bits.   Not Full 2010083000136835 

buyer_email  Buyer's Alipay account   String(100)  Buyer's Alipay account, which can be email or mobile phone number.   Not Full [email protected] 

gmt_create  Transaction creation time  String  The creation time of this transaction  

The format is yyyy-MM-dd HH:mm:ss.   Not Full 2010-08-30 10:17:24 

notify_type  Notification type  String  Notification type. Fixed value.   Not Full trade_status_sync 

quantity  Purchase quantity  String  The quantity of purchased commodity.   Not Full 1 

out_trade_no  The only order number of merchant website   String(64)  The unique order number in the order system of corresponding merchant website, not the Alipay transaction number.  

The uniqueness  in merchant website needs to be ensured. It is the corresponding parameter in request and returned in the original sample.   Not Full 1283134629741 

notify_time  Notification time  String  The transmission time of notification.  

The format is yyyy-MM-dd HH:mm:ss.   Not Full 2010-08-30 10:18:15 

seller_id  Seller's Alipay user number  String  The unique Alipay user number corresponding to the Alipay account of seller.  

The 16-bit pure number started with 2088.   Not Full 2088101000137799 

trade_status  Transaction status  String  Please refer to the "9.2 Transaction status" for the transaction status and value range.   Not Full TRADE_FINISHED 

is_total_fee_adjust  Whether to adjust the total price   String  Whether the price is adjusted for this transaction.  

The total price will not be modified for the transaction created by this interface, and the fixed value is N.   Not Full N 

total_fee  Transaction amount  String(15)  The total amount of this order.  

The corresponding parameters in request are notified back in the original sample.   Not Full 1.00 

gmt_payment  Transaction payment time  String  The payment time of buyer in this transaction 

The format is yyyy-MM-dd HH:mm:ss.  

If the transaction is not paid, then this parameter will not be returned.   Full 2010-08-30 10:18:26 

seller_email  Seller's Alipay account   String(100)  Seller's Alipay account, which can be email  and mobile phone number.   Not Full [email protected] 

gmt_close  Transaction closing time   String  Transaction closing time.    

The format is yyyy-MM-dd HH:mm:ss.   Not Full 2010-08-30 10:18:26 

price  Unit price of commodity  String  It is the same as total_fee value currently.  

Unit: yuan.  

It shall not be lower than 0.01 yuan.   Not Full 1.00 

buyer_id  Buyer's Alipay user number  String  The unique Alipay user number corresponding to the Alipay account of buyer.  

The 16-bit pure number started with 2088.   Not Full 2088102001172352 

notify_id  Notification Verification ID  String  Notification Verification ID. Unique identification of notification content. When resending the notification of the same content, this value is not changed.   Not Full 509ad84678759176212c247c46bec05303 

use_coupon  Whether to use red envelope buyers  String  When the red envelopes were used in the transaction.   Not Full N 

 

5.3.3 Samples 

Note:

This sample is only for reference; the actual gateway shall be the commercial user domain name.

 The notification request sample received from Alipay when merchant uses the RSA signature is as follows:  

http://www.xxx.com/alipay/notify_url.php?service=alipay.wap.trade.create.direct&sign=Rw/y4ROnNicXhaj287Fiw5pvP6viSyg53H3iNiJ61D3YVi7zGniG2680pZv6rakMCeXX++q9XRLw8Rj6I1//qHrwMAHS1hViNW6hQYsh2TqemuL/xjXRCY3vjm1HCoZOUa5zF2jU09yG23MsMIUx2FAWCL/rgbcQcOjLe5FugTc=&sec_id=0001&v=2.0&notify_data=g3ivqicRwI9rI5jgmSHSU2osBXV1jcxohapSAPjx4f6qiqsoAzstaRWuPuutE0gxQwzMOtwL3npZqWO3Z89J4w4dXIY/fvOLoTNn8FjExAf7OozoptUS6suBhdMyo/YJyS3lVALfCeT3s27pYWihHgQgna6cTfgi67H2MbX40xtexIpUnjgxBkmOLai8DPOUI58y4UrVwoXQgdcwnXsfn2OthhUFiFPfpINgEphUAq1nC/EPymP6ciHdTCWRI6l1BgWuCzdFy0MxJLliPSnuLyZTou7f+Z5Mw24FgOacaISB+1/G+c4XIJVKJwshCDw9Emz+NAWsPvq34FEEQXVAeQRDOphJx8bDqLK75CGZX+6fx88m5ztq4ykuRUcrmoxZLJ+PiABvYFzi5Yx2uBMP/PmknRmj1HUKEhuVWsXR0t6EWpJFXlyQA4uxbShzncWDigndD7wbfNtkNLg5xMSFFIKay+4YzJK68H9deW4xqk4JYTKsv8eom9Eg9MrJZiIrFkFpVYPuaw0y/n61UEFYdzEQZz+garCmMYehEAQCGibYUQXBlf1iwTOZdqJIxdgCpSX21MIa9N9jicmFu8OXWZJkdN+UrSyvIcpzRori+U6522ovMz5Z8EzVTfcUENu+d 

 

Note: 

The parameter value of notify_data in the above example is encrypted content, merchants need to use their own RSA private keys to decode and then sign in confirmation.  

 The notification sample received from Alipay when merchant uses the MD5 signature is as follows:  

http://www.xxx.com/alipay/notify_url.php?service=alipay.wap.trade.create.direct%20&sign=Rw/y4ROnNicXhaj287Fiw5pvP6viSyg53H3iNiJ61D3YVi7zGniG2680pZv6rakMCeXX++q9XRLw8Rj6I1//qHrwMAHS1hViNW6hQYsh2TqemuL/xjXRCY3vjm1HCoZOUa5zF2jU09yG23MsMIUx2FAWCL/rgbcQcOjLe5FugTc=&v=2.0&sec_id=MD5&notify_data=%3Cnotify%3E%3Cpayment_type%3E1%3C/payment_type%3E%3Csubject%3E%E6%94%B6%E9%93%B6%E5%8F%B0{1283134629741}%3C/subject%3E%3Ctrade_no%3E2010083000136835%3C/trade_no%3E%3Cbuyer_email%[email protected]%3C/buyer_email%3E%3Cgmt_create%3E2010-08-3010:17:24%3C/gmt_create%3E%3Cnotify_type%3Etrade_status_sync%3C/notify_type%3E%3Cquantity%3E1%3C/quantity%3E%3Cout_trade_no%3E1283134629741%3C/out_trade_no%3E%3Cnotify_time%3E2010-08-3010:18:15%3C/notify_time%3E%3Cseller_id%3E2088101000137799%3C/seller_id%3E%3Ctrade_status%3ETRADE_FINISHED%3C/trade_status%3E%3Cis_total_fee_adjust%3EN%3C/is_total_fee_adjust%3E%3Ctotal_fee%3E1.00%3C/total_fee%3E%3Cgmt_payment%3E2010-08-3010:18:26%3C/gmt_payment%3E%3Cseller_email%[email protected]%3C/seller_email%3E%3Cgmt_close%3E2010-08-3010:18:26%3C/gmt_close%3E%3Cprice%3E1.00%3C/price%3E%3Cbuyer_id%3E2088102001172352%3C/buyer_id%3E%3Cnotify_id%3E509ad84678759176212c247c46bec05303%3C/notify_id%3E%3Cuse_coupon%3EN%3C/use_coupon%3E%3C/notify%3E 

The parameter value of notify_data in the above example is plaintext, which needs not to be decrypted.  

 The Alipay system notification and the formation rules of signature data are quite special, under the permanent order.  

For example, a merchant receives the following notification data:  

http://www.xxx.com/alipay/notify_url.php?service=alipay.wap.trade.create.direct&sign=Rw/y4ROnNicXhaj287Fiw5pvP6viSyg53H3iNiJ61D3YVi7zGniG2680pZv6rakMCeXX++q9XRLw8Rj6I1//qHrwMAHS1hViNW6hQYsh2TqemuL/xjXRCY3vjm1HCoZOUa5zF2jU09yG23MsMIUx2FAWCL/rgbcQcOjLe5FugTc=&v=1.0&sec_id=0001&notify_data=<notify><payment_type>1</payment_type></notify> 

Only the following data needs to be signed in confirmation:  

service=alipay.wap.trade.create.direct&v=1.0&sec_id=0001&notify_data=<notify>…</notify> 

6 Notification returning data processing 

6.1 html Synchronous Return Features  

(1) After Alipay completes the processing of requested data, the current interface will be automatically refreshed to display the results immediately;  

(2) The current interface will be redirected back once for processing one request, which means the processing results will be only returned once;  

(3) Since there is no parameter return_url to set the page redirected to the file path of synchronous notification page, therefore the location of page file which displays the processing results is located in the Alipay server, that is the path address of current page beginning with the Alipay domain name;  

(4) This step can be debugged on the local computer, without the use of server; 

(5) The display format of processing results is the html format;  

(6) This html format processing result can be remotely analyzed in html , so that it can get the relevant processing result data when Alipay processes the results, and carry out the business logic processing of merchant to this result interface;  

(7) The configurations of local computers and merchant servers need to support the html remote analysis, such as: the support of SSL; 

(8) After the page is redirected, the link in the browser address bar is only valid within one minute and will be invalid afterwards, causing the business logic programs written by merchants in this page cannot be processed.  

 

6.2 Page skipping synchronous notification page features 

(1) After the buyer pays successfully, a page prompt of successful trading will be seen; this page stops for several seconds, then the page will automatically skip to the designated synchronous page of commercial users (Parameter “call_back_url”). 

(2) The way of obtaining parameters at this page can be obtained in GET WAY, for example, request.QueryString("out_trade_no")、$_GET['out_trade_no']. 

(3) This way only automatically skip after the buyer completes payment, only once. 

(4) This way does not mean Alipay automatically recalling commercial users’ page, but Alipay program utilizes the function of page automatically skipping to make the user’s current page automatically skipping. 

(5) This way can be debugged on the machine, but not on the server; 

(6) Returning URL has only one-minute validity. The period more than one minute would make the link address invalid and the verification becomes failed. 

(7) When setting up page-skipping synchronous notification page path (call_back_url), page document shall not added with self-defined parameter. For example:

Wrong format: http://www.alipay.com/alipay/return_url.php?xx=11

Correct format: http://www.alipay.com/alipay/return_url.php 

(8) Alipay will check the legal validity of the domain name of synchronous notification page (call_back_url) of page skipping, thus when setting up page skipping synchronous notification page, the current computer domain shall not be set up. Special characters shall also not be affiliated with special characters (i.e. “!”), for example.

 Wrong format:

http://localhost/alipay/return_url.php

http://localhost:80/alipay/return_url.php

http://www.xxx.com/alipay/return!url.do 

 Correct format:

 Domain name addresses can be normally accessed: http://www.xxx.comalipay/return_url.php

 IP addresses can be normally accessed:  http://121.1.1.255/alipay/return_url.php 

6.3 Page features of server asynchronous notification 

(1) It is mandatory to guarantee that server asynchronous notification page (notify_url) does not have any characters, such as space, HTML label, and abnormal prompt information throwing in development system. 

(2) Alipay uses POST way to send notification information, thus the way of obtaining parameters on the page like follows, request.Form("out_trade_no")、$_POST['out_trade_no']. 

(3)Alipay actively issues notification. This way can be started. 

(4) Only the trading is occurred in the transaction management of Alipay and change the trading status, Alipay can issue the server notification of the way (that is, Fastpay trading status “Waiting seller payment” default can not sent notification). 

(5) Interaction between servers would not display on the page like page skipping synchronous notification. This interacting way is invisible. 

(6) When changing the first trading status (the trading status is completed through trading in Fastpay), not only the page skipping synchronous notification can be started, but also server asynchronous notification page can receive the processing results notification sent by Alipay. 

(7) After executing program, it is a must to print output “success”(quotation marks not included, no spaces and other redundant characters  before and after). If the characters given feedback from the commercial users are not “Success”, the Alipay server would repeatedly issue notification, until it exceeds 24 hours 22 minutes. Generally, eight notification will be completed within 25 hours (the interval frequency of notification is 2m,10m,10m,1h,2h,6h,15h generally) 

(8) After executing program, the page cannot execute page skipping. If executing page skipping, Alipay cannot receive “Success” Character, it will be judged by Alipay server as abnormal page program and resending the notification of processing results.

(9) It well returns “fail” when exceptions occur during the program processing, then the Alipay server will select the resend notification.  

(10) “Cookies, session” would become invalid on this page, that is, these data cannot be obtained. 

(11) The debugging and running of the way must be on the server, that is, can access on Internet. 

(12) The function of the way is aim to prevent order loss. That is, page skipping synchronous notification fails to process order upgrade, then it will process. 

(13) When the commercial users receives the asynchronous notification of server and prints “success”, the synchronous notification parameter “notify_id” would become valid. That is to say, when Alipay sends a same asynchronous notification (including commercial users failed to print “success” causing Alipay repeatedly sending several times of notification), server asynchronous notification parameter “notify_id” is unchangeable. 

(14) Asynchronous notifications will carry out the notification sending in both “successful transaction” and “successful payment” statuses, the transaction status in notification needs to be correctly handled, and the “success” needs to be returned after the completion of process, in order to avoid the repeated business processing errors resulted from the occurrences of repeated notifications.  

6.4 Triggering conditions of notification 

Table 6-1 notification triggering conditions

Triggering conditions name Description of triggering conditions Default value of triggering conditions

TRADE_FINISHED  Successful trading  true（triggered notification） 

TRADE_SUCCESS  Successful payment  true（triggered notification） 

WAIT_BUYER_PAY  Created trading  false（untriggered notification ） 

TRADE_CLOSED  Closed trading  false（untriggered notification） 

 

6.5  Matters needing attention for commercial tenants business 

  Authorized interface 

After Alipay processes completely, Alipay would give feedback to the commercial tenants website in the way of “html” synchronous returning data. Commercial tenants may utilize the programming method to analog “http” request remote analysis of “html” to get the processed result data, so as to increase the business logical processing procedure. At this time, the commercial tenants must judge whether website of “commercial tenants” has processed the resulting data. If it does not judge, the potential risks exist; commercial tenants shall bear all the loss from it. 

 Transaction interface 

After Alipay processes completely, Alipay would give feedback to the commercial tenants’ website in the way of “current page skipping” synchronous notice or Alipya server notifying commercial tenants website.  Commercial tenants may obtain these information from page skipping synchronous notifying page or asynchronous notifying page of server and increase the business logic treating procedure from the verified passed judge. When the commercial tenants have the delivery parameter “notify_url”  (server asynchronous webpage path), or “call_back_url” (Page skipping synchronous notifying page path). Commercial tenants must judge increase the business logical processing procedure. At this time, the commercial tenants must judge whether website of “commercial tenants” has processed the resulting data. If it does not judge, the potential risks exist; commercial tenants shall bear all the loss from it.

 

7 Signing mechanism 

7.1  Generated character string to be signed 

7.1.1  Parameters requiring signature 

 Among the request parameter list table, besides parameter “sign”, parameters used for other aspects are the parameters to be signed. 

 In the authorized interface “html” returned parameter list table, 

Under the normal returning conditions, apart from parameter “sign”, all the returned parameters are the parameters to be signed. 

In case of error, signature is not required. 

In the returned parameter list table of transaction interface notifying, apart from parameter “sign”, all the returned parameters are the parameters to be signed. 

 

7.1.2 Generated character string to be signed

 

As for the following parameter group:

 Authorized interface  

string[] parameters={ 

"service=alipay.wap.trade.create.direct", 

"req_data=<direct_trade_create_req><subject>lottery 

</subject><out_trade_no>1282889603601</out_trade_no><total_fee>10.01</total_fee><seller_account_name>[email protected]</seller_account_name><call_back_url>http://www.yoursite.com/waptest0504/servlet/CallBack</call_back_url><notify_url>http://www.yoursite.com/waptest0504/servlet/NotifyReceiver</notify_url><out_user>123456789</out_user><merchant_url>http://www.yoursite.com</merchant_url><pay_expire>3600</pay_expire></direct_trade_create_req>", 

"partner=2088101000137799", 

"req_id=1282889689836", 

"sec_id=0001", 

"format=xml ", 

"v=2.0" 

}; 

 Transaction interface 

string[] parameters={ 

"service=alipay.wap.auth.authAndExecute", 

"req_data=<auth_and_execute_req><request_token>201008309e298cf01c58146274208eda1e4cdf2b</request_token></auth_and_execute_req>", 

"partner=2088101000137799", 

"sec_id=0001", 

"format=xml", 

"v=2.0", 

}; 

 

Rank the values as per alphabetical order from a to z in the array; if the first letters are the same, then rank them from the second letter, and so son. After ranking, connect all the array value with “&”character 

 Authorized interface 

format=xml&partner=2088101000137799&req_data=<direct_trade_create_req><subject>Lottery </subject><out_trade_no>1282889603601</out_trade_no><total_fee>10.01</total_fee><seller_account_name>[email protected]</seller_account_name><call_back_url>http://www.yoursite.com/waptest0504/servlet/CallBack</call_back_url><notify_url>http://www.yoursite.com/waptest0504/servlet/NotifyReceiver</notify_url><out_user>123456789</out_user><merchant_url>http://www.yoursite.com</merchant_url><pay_expire>3600</pay_expire></direct_trade_create_req>&req_id=1282889689836&sec_id=0001&service=alipay.wap.trade.create.direct&v=2.0 

 Transaction interface  

format=xml&partner=2088101000137799&req_data=<auth_and_execute_req><request_token>201008309e298cf01c58146274208eda1e4cdf2b</request_token></auth_and_execute_req>&sec_id=0001&service=alipay.wap.auth.authAndExecute&v=2.0 

 

These character strings are the ones to be signed. 

Notes：  

 The parameter verification received from “notify_url” does not require ranking. Character strings can be connected as per the parameter order returned by Alipay, then be verified. If Alipay asynchronously notifies “POST”-returned parameter order as follows: service=alipay.wap.trade.create.direct&v=1.0&sec_id=0001&notify_data=<notify>…</notify>. 

 Parameters without values do not require transmitting, nor require containing to character data to be signed. 

 When converting characters as byte stream for signature, the designated character set shall keep identical to “_input_charset”. 

 If the parameter “_input_charset” is passed, this parameter shall be contained into the data to be signed. 

 According to the HPPT protocol requirement, if the value in transmitting parameters exist special characters (for example, & and @), then the value shall be under RL Encoding, then the two parties under request can receive the correct parameter value. Under this circumstance, the data to be signed shall be original value, but not the value after “encoding”. For example, calling some interface requires digital signature for request parameter email“, then the data to be signed should be [email protected], but not “email=test%40msn.com” . 

 

7.2 Signature 

7.2.1 MD5 signature 

In case of MD 5 signature, private key is required for participating in signature. The private key of MD5 is 32-byte character string composed of English letters and numbers. Commercial tenants shall log on commercial service center (https://b.alipay.com). Install digital certificate, click “Transaction safety verifying code” in the “Technical service” to check. 

 

 Signature in request 

After getting the character strings to be signed in request, it is required to directly splice the private key to the character strings to be signed to form new character string, make signature calculation to the new character string by using MD5 signed function, so as to obtain the 32-bit signed results (The character string is endowed with value of parameter “sign”).

 

  Verify signature when notifying returning 

After getting the character strings to be signed in request, it is required to directly splice the private key to the character strings to be signed to form new character string, make signature calculation to the new character string by using MD5 signed function, so as to obtain the 32-bit signed results. Then new character string requires shall be verified for equality of parameter “sign” value in the notified parameters in Alipay to judge whether the signature is passed. 

 

7.2.2 Signature of DSA and RSA  

In case of signature of DSA and RSA, private key and public key shall be signed together. Both private key and public key are derived from “OPENSSL”. Customers shall change the generated public key with the configured Alipay public key by Alipay technicians. Therefore, in signature, customers want to get their private key and the public key of Alipay. 

 

 Signature in request 

When getting the character string to be signed in getting request, put the character string to be signed with the private key of customers into the DSA and RSA signature functions for function calculation, so as to obtain the signature result character string. 

 

 Decryption 

 

When getting the original data noticed for returning, firstly make decryption of the parameters to be decrypted. 

 

 In the authorization interface, the returned parameter to be decrypted is “res_data”.  

 In the transaction interface,  interface, the returned parameter to be decrypted is “notify_data”. 

 

Put “res_data”, “notify_data”, commercial tenants private key into RSA decryption function for decryption calculation, so as to get the decryption result character string. 

 

   Verifying signature when notifying returning 

When getting the character string to be signed in getting request, put the character string to be signed, public key provided by Alipay, parameter “sign” value in returning parameter of Alipay into DSA and RSA signature function for unsymmetrical signature calculation, to judge whether the signature is verified for passing. 

 

8 Suggestions and opinions 

If you have any suggestions and opinions when reading the technical document, please click the following link follow-up reply, we will perfect the document contents according to the feedback. 

http://club.alipay.com/read.php?tid=8684674&fid=703

 

9 Attachments 

9.1  Mobile Web Instant Payment Business Error Code

 

Table 9-1 Mobile Web Instant Payment Business Error Code

Error code（code） Error reason （msg） Detailed description of errors（detail） Meaning

0000  system exception  Abnormal system  Abnormal system

0001  common params illegal  Absence of necessary parameters like “service”, “partner” in the general parameter  Absence of necessary parameters; please check whether non-empty parameters are transmitted. 

0002  sign illegal  Incorrect signature  Incorrect signature. Please check whether parameters to be signed meet the signing specification of Alipay. 

0003  service not exist  No corresponding service  Service interface error, please check whether “service” is correctly transmitted. 

0004  req_data illegal  “req_data” is not filled as per the format requirement of  <req>…<req>   Incorrect format “req_data”

0005  partner illegal  Cooperating partner fails to open the interface access right.  Commercial tenants fail to open the interface rights or contract has been overdued. 

0006  sec_id not exist  No corresponding “sec_id”  “sec_id（signature algorithm）”is incorrect, supporting 0001（RSA）and MD5. 

0007  biz params illegal  Absence of non-empty business parameter Absence of non-empty business parameter

0008  biz params too long  Business parameter exceeds the limitation of length.  Business parameter exceeds the limitation of length.

0009  seller_account_not_match  Mismatching of seller’s account number  Commercial tenants are not in the limited list table. 

 

9.2 Transaction status  

Table 9-2 Transaction status 

Name of examples   Description of examples  

WAIT_BUYER_PAY  Transaction is created, waiting for buyer’s payment. 

TRADE_CLOSED  Closed transactions without payment within the designated time section;

Closed transactions when transaction completes total amount refunding 

TRADE_SUCCESS  Trade succeeded; operation can be made for the transaction, like multi-level profit splitting and refunding. 

TRADE_PENDING  Waiting for seller’s amount collection (after the seller completes payment, if the seller’s account number is frozen)

TRADE_FINISHED  Transaction is completed successfully. Any operation shall not be made.