Construct orderStr
Request
Request parameters
Parameter | Type (length) | Description | Required | Example |
service | String | Interface name. Fixed value. | Y | mobile.securitypay.pay |
partner | String(16) | The unique Alipay user number corresponding to authorized Alipay account number. The unique Alipay user number typically contains 16 digits beginning with 2088. | Y | 2088101568358171 |
_input_charset | String | Encoding format used on merchant's website, the fixed format is utf-8. | Y | utf-8 |
sign_type | String | The signature type, currently only supports RSA. | Y | RSA |
sign | String | See Digital signature for details. | Y | lBBK%2F0w5LOajrMrji7DUgEqNjIhQbidR13GovA5r3TgIbNqv231yC1NksLdw%2Ba3JnfHXoXuet6XNNHtn7VE%2BeCoRO1O%2BR1KugLrQEZMtG5jmJIe2pbjm%2F3kb%2FuGkpG%2BwYQYI51%2BhA3YBbvZHVQBYveBqK%2Bh8mUyb7GM1HxWs9k4%3D |
return_url | String(200) | The URL that is redirected to after payment. | N | |
notify_url | String(200) | Alipay server takes the initiative to notify the page HTTP path designated by the merchant's website. | N | |
payment_inst | String | The type of wallet that this QRCode can be scanned. If this field is set to ALIPAYHK, then the QR code can only be scanned by the AlipayHK wallet. If this field is set to ALIPAYCN, then the QR code can only be scanned by the Alipay wallet. If this field is set to null, then the QR code can only be scanned by the Alipay wallet. | N | ALIPAYHK |
appenv | String | A string used to identify the client. The parameter value is agreed as follows: appenv=”system=client platform name ^version=business system version”, for example: appenv=”system=iphone^version=3.0.1.2” | N | appenv=”system=android^version=3.0.1.2” |
out_trade_no | String(64) | The unique Alipay order ID on the merchant's website. | Y | 0819145412-6177 |
subject | String(256) | Brief description of the transaction. Special characters are not supported. | Y | Baby cloth |
payment_type | String(4) | Payment type. The default value is 1 (stands for purchase of goods). | Y | 1 |
seller_id | String(16) | The seller's Alipay account number (email or mobile number format) or the corresponding unique Alipay user number (16 single digits beginning with 2088). | Y | |
total_fee | Number | A floating number ranging from 0.01 to1000000.00, specifies the foreign price of the items. If the total_fee is called, the rmb_fee can not be called at the same time. | Y | 0.01 |
body | String(1000) | A detailed description of the goods. Special characters are not supported. | Y | Baby cloth in red, large size. |
currency | String(10) | Please refer to the abbreviation set out in Currency List. | Y | HKD |
forex_biz | String(10) | "FP" is the only input value | Y | FP |
it_b_pay | String | This parameter is to set the overtime of non-payment transactions. The transaction will be closed automatically once the time is up. | N | 30m |
extern_token | String(32) | Token (including account information) returned by open platform (authorization token, a right for merchant to access to some services of Alipay within a specified period). | N | 1b258b84ed2faf3e88b4d979ed9fd4db |
refer_url | String(200) | Website of the secondary merchant | Y | |
product_code | String(32) | Identifier of product | Y | NEW_WAP_OVERSEAS_SELLER |
secondary_merchant_id | String(32) | Used to differentiate the secondary merchant of the merchant, which is assigned by the merchant, not interfered by Alipay. | N | A80001 |
secondary_merchant_name | String(32) | Secondary merchant name, assigned by the merchant, not interfered by Alipay. | N | Muku |
secondary_merchant_industry | String(4) | Industry classification identifier of sub-merchant assigned by Alipay. For example: | N | 7011 |
trade_information | String(6000) | When the Alipay wallet is used, you must specify this field. When the AlipayHK wallet is used, you don't need to specify this field. (The wallet type is identified by the value of the payment_inst field. ) This field is about the trade industry information. 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. | Y | 1|2|3|4|5 |
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 a 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 a vertical bar (|). Specify this field only when business_type is 2 (AIR). | Y | NWS 996|TWF 8854 |
departure_time | Date | Departure time. | Y | 2018-10-22 20:49 |
admission_notice_url | String | If business_type is 3 (Overseas study consulting), the URL of the admission notice (image) must be specified. | Y | |
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 a vertical bar (|). Specify this field only when business_type is 4 (Sales of goods). | Y | pencil2|eraser5|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 detail. | Y | Airport pick up service |
Note:
Do not use a halfwidth quotation mark (") in parameter values.
Server asynchronous notification parameters
Parameter | Type | Description |
notify_type | String | Unique value: forex_trade_status_sync |
notify_id | String(34) | The unique ID used for authenticating notification |
notify_time | Timestamp | System notification time (Beijing time): YYYY-MM-DD hh:mm:ss |
sign | String | Please refer to the signature algorithm |
sign_type | String | MD5 |
out_trade_no | String(64) | The unique order ID in the merchant system |
trade_status | String(32) | There is two status as follows: |
trade_no | String(16) | The unique order ID in the Alipay system |
currency | String(10) | The currency that the merchant uses to settle. Please refer to enumeration value of currency as set out in Appendix. |
total_fee | Number(8,2) | Range: 0.01~1000000.00 |
Notification trigger condition
Trigger condition name | Description of trigger condition | Note |
TRADE_FINISHED | Trade is successfully | true (trigger notification) |
WAIT_BUYER_PAY | Trade is created | false (does not trigger notification) |
TRADE_CLOSED | Trade is closed | true (trigger notification) |
Description: The detailed value of true (trigger notification) / false (does not trigger notification) remains synchronous with the value at the time of signing and configuration.
Acquisition of server asynchronous response parameters
- Make sure the notification page (notify_url) is absolutely blank, without space, HTML tag or any error messages threw from the program system.
- Parameters on this page can be acquired with GET method, such as request.Form("out_trade_no"), $_POST['out_trade_no'].
- This response will be used if Alipay actively notifies.
- Interaction between servers, unlike interaction between websites, is usually not visible.
- After the program is executed, the page must print success. If not, the Alipay server would keep re-sending notifications for the next 24 hours and 22 minutes. Generally, there would be 8 notifications within 25 hours (Frequency: 2m,10m,10m,1h,2h,6h,15h).
- After the program is executed, the page would not be redirected as Alipay would not recognize a success string. The Alipay system would regard it as an error and keep sending notifications.
- Cookies and sessions would be invalid on this page, which means these data would not be captured.
- The configuration and testing of this system must be on a server via the internet.
- Asynchronous notification is to present transaction lost, so even if the synchronous redirection fails, the order on the partner system can still be updated.
- As long as the partner receives the server's asynchronous response and prints success, the parameter notify_id would be invalid. This means when Alipay sends the same asynchronous notification (include the re-sending notifications because of no success), the parameter notify_id would not change.
- Alipay may add new parameters (existing parameters will not change) along the way. When verifying the notification, merchants must use all parameters returned from Alipay.
Validation of notification parameters
Alipay will send processed result data to sellers. After receiving these result data, sellers should validate the notification parameters following the steps below:
- Verify signature
- Verify whether the notification is sent by Alipay
Please see Verify the Asynchronous Notification for more details. - Requirement on business data processing
Seller needs to check whether out_trade_no_total_fee_seller_id_seller_email_out_trade_no_seller_id/seller_email) is failed in verifying any of the above that indicates this notification is abnormal and should be ignored. After successfully filter repeated notification result data. Only when the trade notification status is TRADE_FINISHED, then Alipay can recognize successful payment by the seller. If the seller needs to verify the signature of synchronously returned data, it must be implemented via signature verification code logic at the server. If sellers fail to process business notice correctly, potential risks may exist, and sellers will bear all loss therein at their own cost. - Note:
Trigger condition of notification of trade status TRADE_FINISHED is that under the premise that the products/services signed by sellers fail to support refund function and the buyer has paid successfully; or under the premise that the products/services signed by sellers support refund function, meanwhile transaction has been made successfully and has already overrun refund period.
Trade status
Enumeration name | Enumeration description |
WAIT_BUYER_PAY | Trade is created and wait for the buyer to pay. |
TRADE_CLOSED | Trade has been closed due to the absence of payment at a specified time. |
TRADE_FINISHED | Trade has been made successfully and a refund can be requested. |
Verification of notifications sent by Alipay
The verification here refers to the parameter notify_id which verifies the legitimacy of the Alipay asynchronous notification. This verification action actually calls for another API, notify verification API (notify_verify). This API request uses a simulation of remote HTTP submission, the callback mode is to output result at the current page directly, the return data is in text format.
The full request link is shown below:
There are two types of processing results:
- Successful: true
- Unsuccessful: report the corresponding error
Business logic management
1. Merchants' business logic processing code
Generally, we suggested that the processing codes of merchants' business logic are written in the following ways:
Signature verification and notify_id legitimacy verification are true.
In the page file of active callback (asynchronous notification notify_url), only if the business logic processing codes are executed and the business logic is changed successfully, the current page success can be printed. The page redirect function should not exist.
2. Matters to be noted in the case of merchant business logic processing
- Must check the verification signature and verify the legitimacy of notify_id.
- Must check the possibility of repetitive calling.
- Perform different codes according to the actual business logic conditions. Particularly execute different parts of codes according to the different transaction status.
- In the page files of active callback mode, check if success is successfully printed and other information exists.
- The page files under the active callback mode do not exist in cookie and session.
- Page redirecting action cannot be implemented on page files that are required to print success under the active callback mode.
Attentions
Specification issues | Attentions |
Matters require attention upon signature | During the integration process, signature should happen at the server side (private key needs to be properly kept), remember not to place private key at client side. |
Notification address | It is recommended that the notification address adopts the format of HTTPS, which ensures that the order information of the seller is not disclosed. |
Testing scenario | Scenarios testing of sellers' payment process: System with Alipay wallet installed and system without Alipay wallet installed, it is important to ensure that both scenarios can enable successful payment. |
Samples
Asynchronous response sample
http://notify.java.jpxx.org/index.jsp?discount=0.00&payment_type=1&subject=test&trade_no=2013082244524842&buyer_email=d*****@gmail.com&gmt_create=2013-08-22 14:45:23¬ify_type=trade_status_sync&quantity=1&out_trade_no=082215222612710&seller_id=2088501624816263¬ify_time=2013-08-22 14:45:24&body=testtest&trade_status=TRADE_FINISHED&is_total_fee_adjust=N&total_fee=1.00&gmt_payment=2013-08-22 14:45:24&seller_email=xxx@alipay.com&price=1.00&buyer_id=2088602315385429¬ify_id=64ce1b6ab92d00ede0ee56ade98fdf2f4c&use_coupon=N&sign_type=RSA&sign=1glihU9DPWee+UJ82u3+mw3Bdnr9u01at0M/xJnPsGuHh+JA5bk3zbWaoWhU6GmLab3dIM4JNdktTcEUI9/FBGhgfLO39BKX/eBCFQ3bXAmIZn4l26fiwoO613BptT44GTEtnPiQ6+tnLsGlVSrFZaLB9FVhrGfipH2SWJcnwYs=