mobile.securitypay.pay

Call this interface to initiate an app payment request.

Request

Service address

Request parameters

trade_information

Notes:

1、Extra parameters to seller/merchant's request parameter attached by sellers should not be duplicated with the stipulated key (see table 6 below) in Alipay system, otherwise it will lead to unknown exceptions. For example, in the request parameters with a format of out_trade_no="1234566"&total_fee="123.5"&rn_check="TRE", out_trade_no, total_fee, and rn_check are all reserved payment processing keys. If sellers take out_trade_no and total_fee as parameters from Alipay and rn_check="TRE" as sellers' own business data, an analysis error will be caused because rn_check is a reserved key of Alipay and Alipay regards rn_check as the parameter from Alipay. The analysis error will lead to an unexpected exception of payment.

2、Alipay suggests that sellers do not add any keys to the request parameters except the reserved key specified by Alipay All keys should be connected via &. For example, out_trade_no="1234566"&total_fee="123.5"&homepage="http://www.***.com" , where homepage is sellers' own business key; Alipay do not advise to attach any keys related to the data of business system that is irrelevant to the payment in the request parameters.

3、Reserved key of Alipay should not appear in the values of all keys (Alipay reserved key or sellers' own key) such as out_trade_no, total_fee, and seller_id. Otherwise the relevant transactions will be intercepted by Alipay and payment will be prohibited. Take the request below as an example,

out_trade_no="1234566"&total_fee="123.5"&homepage="http://www.***.com"&body="testout_trade_no=123 total_fee=123.5"&memo="memo seller_id=2088123213"

In this request, Alipay's reserved keys out_trade_no ,  total_fee, and seller_id are included in the memo field, therefore, this type of business requests will be intercepted by Alipay.

4、If the parameter with String type has no limitation of length, the system doesn't verify the length of this parameter.

5、The decimal place accuracy of amounts, such as the values of total_fee, depends on the value of currency. If the value of currency isJPY, then the amount must be an integer. For example, 100 JPY. For other currencies, the amount is of two decimal place accuracy. For example, 100.00 USD. Amounts in other formats will cause error, for example, 100.999 USD. The value of rmb_fee is also of two decimal places because the currency is CNY.

Response

Synchronous response

After the synchronous notification is processed by Alipay SDK, the payment result will be synchronously fed back to the merchant app.

The data returned by the synchronous notification must be verified by the merchant on the server side. After the verification is passed, the payment can be considered successful. In some cases, the synchronous result cannot be received correctly. Then, the payment result can be completely dependent on the asynchronous notification received in merchant server.

Note:

Both the synchronous notification and asynchronous notification can be used as the payment completion certificate. The asynchronous notification will be surely sent to the merchant server from Alipay. However, to simplify the integration process, merchants can only use the synchronous result as a notification of the end of payment (ignore the verification), and completely rely on the server-side received asynchronous notification to decide whether the payment is successful.

To get the iOS synchronous response parameters, refer to "iOS->Callback API".

To get the Android synchronous response parameters, instantiate PayTask object in new thread, call pay method, and notify main thread via Handler object to obtain payment result. The alipay_sdk_demo project implementation can be referred.

Asynchronous response

After processing the request data, Alipay will notify seller's website of the processed result data in a server-actively-notifying manner. These processed result data are the asynchronous response parameters of the server.

Notification trigger condition

Description: 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

Things to know about the asynchoronous response from Alipay:

• Ensure that the Notification Page (notify_url) is absolutely blank, without space, html tag, or any error messages threw from the program system.

• Alipay sends the notification information in POST method, you can retrieve the parameter details by using, for example, 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" (without quote). If not, Alipay server keeps re-sending notification for the next 24 hours and 22 minutes. Generally, there are eight notifications within 25 hours (Frequency: 2m, 10m, 15m, 1h, 2h, 6h, 15h).

• After the program is executed, the page will not be redirected if Alipay doesn't recognize a "success" string. The Alipay system would regard it as an error and keep sending notification.

• 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 internet.

• The asynchronous notification prevents loss of transactions even if the synchronous redirection fails, therefore, with the asynchronous notification, 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 becomes invalid. This means when Alipay sends the same asynchronous notification (including the re-sending notifications because of no "success"), the parameter notify_id doesn't change.

• Alipay might add new parameters (existing parameters will not change) along the way. When doing notification verification, merchants must use all parameters returned from Alipay.

Validation of notification

Alipay sends processed result data to sellers. After receiving these result data, sellers must validate the notification parameters by following the these steps:

1. Verify the signature.
2. Verify whether the notification is sent by Alipay.
3. Process business data: 

1. Sellers need to check whether out_trade_no in the notice data is the order number created in seller's system, and judge whether total_fee is the actual amount of this order (i.e. the amount when seller's order is created), and meanwhile needs to verify whether seller_id (or seller_email) in the notification is the correct operator of this order of out_trade_no (sometimes, one seller may have several seller_id/seller_email). Failure in verifying any of the above indicates that this notification is abnormal and should be ignored.
2. After successfully verifying the above, sellers must conduct different business processing in accordance with different types of business notification of Alipay, and filter repeated notification result data. Only when the trade notification status is TRADE_FINISHED, Alipay can recognize the successful payment of the seller. If sellers need 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 at their own cost. 

Note:

The notification of a trade status TRADE_FINISHED is triggered when the products/services signed by sellers fail to support the refund function but the buyer has paid successfully; or when the products/services signed by sellers support the refund function and the transaction has been made successfully, but the refund period is over.

Trade status

Verifying the notification

The verification relates to the parameter notify_id, which is used to verify the legitimacy of the Alipay asynchronous notification by calling the notify verification API (notify_verify). This API request uses simulation of the remote HTTP submission; the callback mode is "output result at the current page directly"; the return data are in the text format.

The full request link is shown below:

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

There are two types of outcome from processing results:

• Successful: true

• Unsuccessful: report the corresponding error

Codes returned to client end

Business logic management

Merchants' business logic for processing

Generally, it is suggested that the important processing codes of merchants' business logic are to be 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 are changed successfully, the current page "success" can be printed. The page redirect function should not exist.

Notes:

• It is compulsory to check the verification signature and verify the legitimacy of notify_id.
• It is compulsory to 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, it is recommended to 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

• About the signature: during the integration process, the signature needs to be used at the server side and the private key needs to be properly kept. Remember not to place the private key at the client side.
• About the notification address: the notification address needs to adopt the format of HTTPS to ensure that the order information of seller is not disclosed.
• About the testing scenario of sellers' payment process: test the system with Alipay wallet installed and the system without Alipay wallet installed. Ensure that both scenarios can enable successful payments.

Error codes

A list of error codes and description is shown below:

Samples

Request

Request sample for merchants directly integrated with Alipay

_input_charset="UTF-8"&appenv="system=android^version=3.0.1.2"&currency="USD"&forex_biz="FP"&notify_url="http://www.mikascoffee.com/notify"&out_trade_no="out_trade_no_20190826_204550"&partner="208xxxxxxxxx6931"&payment_type="1"&product_code="NEW_WAP_OVERSEAS_SELLER"&refer_url="http://www.mikascoffee.com"&return_url="http://www.mikascoffee.com/return"&seller_id="2088021017666931"&service="mobile.securitypay.pay"&sign="gFXGKhF4Tdh%2FRppQUKn62AaYB3kEz03Wi3nuKlgCrO49B8UpJvHl9oAGgsKyKyz5RPUoqa1dttjZkYmpJr4YgLot9LLIq8sWbKi0n7LnlwNAfXTaTdcETV75muoEAQgrfzLNVttoPti%2BJF075fXUOPCBYo2cBQIZehE4fZQxPbaMplwQrU6rprNutJFl%2B56uy73B6VT9o8lwU%2FNgjRgIZgYhJGVtLCNUbiHM4PwPSQJrAovzDVbQOsOcS%2BViHe5wgQjk8BrkqbgcZ5aMVRWQjg3HzvJ8jog3AaYjtehx2TaMFcugL%2BoZv2MOjeVHpczNqhkYmSdj1ttIOL2v92cZZQ%3D%3D"&sign_type="RSA"&subject="Mika's capsule coffee"&total_fee="12"&trade_information="{"business_type":"4","goods_info":"Mika's capsule coffee^1","total_quantity":"1"}"

Request sample for acquirers and system integrators with secondary merchants

_input_charset="UTF-8"&appenv="system=android^version=3.0.1.2"&currency="USD"&forex_biz="FP"&notify_url="http://www.mikascoffee.com/notify"&out_trade_no="out_trade_no_20190826_204550"&partner="208xxxxxxxxx6931"&payment_type="1"&product_code="NEW_WAP_OVERSEAS_SELLER"&return_url="http://www.mikascoffee.com/return"&secondary_merchant_id="1314520"&secondary_merchant_industry="5499"&secondary_merchant_name="China Substation"&seller_id="208xxxxxxxxx6931"&service="mobile.securitypay.pay"&sign="b8tOyjuPOun3idy1f%2BBDZHMDo0F68mfcqILD%2FatSZ7BXbK1yRJx6YxfJKYzarUtb%2BE9g6NwRitwxCM2qhotkP%2F8zeGd8iTabhr2fX810VoPkyJkxYchnHbZmQyxCI%2FwZDTKqYjpSstIUN1ZBkOUbzt4B%2FKi1MgdyK5qTw0ianipRVK%2BNWxDUr5wgG0IZ4rvxxOsk4CqQXaLbM2OV2yA24qQrQuy9zYyax387fDfOTxEU3tKHu82BCVnP1kWjcngaKM5ZYvSpD56GyrTwLTHEIhm2KMRV3wdV7AasOOOH1xkRJIoOMiMZz0HiLO%2FPMninaT4zYnUVsinbZqwKw0HzyA%3D%3D"&sign_type="RSA"&subject="Mika's capsule coffee"&total_fee="12"

Response

Synchronous response sample

{resultStatus=9000, result=_input_charset="UTF-8"&appenv="system=android^version=3.0.1.2"&currency="USD"&forex_biz="FP"&notify_url="http://www.mikascoffee.com/notify"&out_trade_no="out_trade_no_20190826_204539"&partner="208xxxxxxxxx6931"&payment_type="1"&product_code="NEW_WAP_OVERSEAS_SELLER"&refer_url="http://www.mikascoffee.com"&return_url="http://www.mikascoffee.com/return"&seller_id="208xxxxxxxxx6931"&service="mobile.securitypay.pay"&subject="Mika's capsule coffee"&total_fee="0.01"&trade_information="{"business_type":"4","goods_info":"Mika's capsule coffee^1","total_quantity":"1"}"&success="true"&sign_type="RSA"&sign="ZL7835QAkmm66hSQKQ5dPhT7ECtljq6sZltmu8AMb8Cu1bbY6/4nsGtbwbn/VieWn4851zkFHviMq9ze+N5eRUJYYG2hW8pfd5V2jpGcaeIV8GNY0/E02u0fMILrcV/hj/nPHtIsdi2cPOHMCeCyU4NeVUkZt9BxiTffWxqpjIk=", memo=}

resultStatus=9000
result=
    _input_charset="UTF-8"
    appenv="system=android^version=3.0.1.2"
    currency="USD"
    forex_biz="FP"
    notify_url="http://www.mikascoffee.com/notify"
    out_trade_no="out_trade_no_20190826_204539"
    partner="208xxxxxxxxx6931"
    payment_type="1"
    product_code="NEW_WAP_OVERSEAS_SELLER"
    refer_url="http://www.mikascoffee.com"
    return_url="http://www.mikascoffee.com/return"
    seller_id="208xxxxxxxxx6931"
    service="mobile.securitypay.pay"
    subject="Mika's capsule coffee"
    total_fee="0.01"
    trade_information="{"business_type":"4","goods_info":"Mika's capsule coffee^1","total_quantity":"1"}"
    success="true"
    sign_type="RSA"
    sign="ZL7835QAkmm66hSQKQ5dPhT7ECtljq6sZltmu8AMb8Cu1bbY6/4nsGtbwbn/VieWn4851zkFHviMq9ze+N5eRUJYYG2hW8pfd5V2jpGcaeIV8GNY0/E02u0fMILrcV/hj/nPHtIsdi2cPOHMCeCyU4NeVUkZt9BxiTffWxqpjIk="
memo=

Asynchronous response sample

http://www.mikascoffee.com/notify?notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx2208&notify_type=trade_status_sync&sign=$$$&trade_no=201xxxxxxxxxxxxxxxxxxxxx7415&buyer_id=208xxxxxxxxx6535&total_fee=0.01&forex_rate=7.20211000&out_trade_no=out_trade_no_20190826_204539&rmb_fee=0.07&seller_id=208xxxxxxxxx6931&currency=USD&notify_time=2019-08-26 22%3A11%3A32&trade_status=TRADE_FINISHED&sign_type=RSA

http://www.mikascoffee.com/notify
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx2208
notify_type=trade_status_sync
sign=$$$
trade_no=201xxxxxxxxxxxxxxxxxxxxx7415
buyer_id=208xxxxxxxxx6535
total_fee=0.01
forex_rate=7.20211000
out_trade_no=out_trade_no_20190826_204539
rmb_fee=0.07
seller_id=208xxxxxxxxx6931
currency=USD
notify_time=2019-08-26 22:11:32
trade_status=TRADE_FINISHED
sign_type=RSA