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

http://notify.msp.hk/return.htm

notify_url

String(200)

Alipay server takes the initiative to notify the page HTTP path designated by the merchant's website.

N

http://notify.msp.hk/notify.htm

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”
appenv=”system=ipad^version=4.0.1.1”

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.
Note: The value of this field will be displayed to customers.

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

xxx@alipay.com

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.
Range of values: 1m~15d, or absolute time (for example: 2014-06-13 16:00:00).
m-minute, h-hour, d-day, 1c-current day (Whenever the transaction is created, it will be closed at 0:00).
To realize this function, Alipay needs to be advised to set the close time.

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

http://testmerchant.com

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:
catering industry: 5812
department stores: 5311
lodging industry: 7011
taxi industry: 4121

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.
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 a 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 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.
Format: yyyy-MM-dd HH:mm
Timezone: GMT +8. If flight transfer exists, separate time values with a 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 the 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 a vertical bar (|). Specify this field only when business_type is 4 (Sales of goods).

Y

pencil2&#124;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_FINISHED
TRADE_CLOSED

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:

https://mapi.alipaydev.com/gateway.do?service=notify_verify&partner=2088002396712354&notify_id=RqPnCoPT3K9%2Fvwbh3I%2BFioE227%2BPfNMl8jwyZqMIiXQWxhOCmQ5MQO%2FWd93rvCB%2BaiGg

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&notify_type=trade_status_sync&quantity=1&out_trade_no=082215222612710&seller_id=2088501624816263&notify_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&notify_id=64ce1b6ab92d00ede0ee56ade98fdf2f4c&use_coupon=N&sign_type=RSA&sign=1glihU9DPWee+UJ82u3+mw3Bdnr9u01at0M/xJnPsGuHh+JA5bk3zbWaoWhU6GmLab3dIM4JNdktTcEUI9/FBGhgfLO39BKX/eBCFQ3bXAmIZn4l26fiwoO613BptT44GTEtnPiQ6+tnLsGlVSrFZaLB9FVhrGfipH2SWJcnwYs=