mobile.securitypay.pay

Call this interface to initiate an app payment request.

Request

Service address

Request parameters

trade_information

Note:

Do not use the halfwidth quotation mark (") in parameter values.

Response

Synchronous response

Codes returned to the client end

Asynchronous response

Notification trigger condition

Description: the detailed value of true (trigger nofitication) / false (does not trigger nofitication) 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.
• Parameters on this page can be acquired with the 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” (without quote). If not, Alipay server keeps re-sending notification for the next 24 hour 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 will not be redirected as Alipay does not 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 lost 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 would be invalid. This means when Alipay sends same asynchronous notification (including the re-sending notifications because of no “success”), the parameter notify_id doesn't change.
• Alipay may add new parameters (existing parameters will not change) along the way. When doing notification verification, merchant 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 following the steps below:

1. Verify the signature.
2. Verify whether the notification is sent by Alipay. See Verify The Notification Is Sent by Alipay for more details.
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 notificaiton

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 is 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

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="HKD"&forex_biz="FP"&notify_url="http://www.mikascoffee.com/notify"&out_trade_no="out_trade_no_20190910_141444"&partner="208xxxxxxxxx5500"&payment_inst="ALIPAYHK"&payment_type="1"&product_code="NEW_WAP_OVERSEAS_SELLER"&refer_url="http://www.mikascoffee.com"&return_url="http://www.mikascoffee.com/return"&seller_id="2088021966645500"&service="mobile.securitypay.pay"&sign="3v0t8CPxvNrZazSPhIFO0mR0hNS3Ph%2BwSOqlx0C4LRDjlgVShCW85omoT9wP4CpHfUdksTlgAoKaj1VWrzlkMXPyOhbW3Ex0euS1jczIBt47hK4105lcXIREzd7LGyg8uA8gxmQ49CQ8Zr9ZPEAbYRIlAsbN4yyAZHqYKPugnYM%3D"&sign_type="RSA"&subject="Mika's coffee shop"&total_fee="0.01"&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="HKD"&forex_biz="FP"&notify_url="http://www.mikascoffee.com/notify"&out_trade_no="out_trade_no_20190910_140255"&partner="208xxxxxxxxx5500"&payment_inst="ALIPAYHK"&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="Mika's coffee shop"&seller_id="208xxxxxxxxx5500"&service="mobile.securitypay.pay"&sign="8mAZ4DZo3USCmOmHtjpqt9yswfwZJT%2FmnChDjVZzno3X0vnsisch78ut%2BXiF7sOs5YPZgAexpa6MaFGRAN1i9euFuKqa4wglZcHB85Swtfz8%2FRHLY3NMAnJh4z9a%2BTJATVLDPLy7OP7nu%2BvefVUeci3zssCm9aYIDnt7eVbJXDs%3D"&sign_type="RSA"&subject="Mika's coffee shop"&total_fee="0.01"

Response

Synchronous response

resultStatus=9000
result=
    _input_charset="UTF-8"
    appenv="system=android^version=3.0.1.2"
    currency="HKD"
    forex_biz="FP"
    it_b_pay="1h"
    notify_url="http://www.mikascoffee.com/notify"
    out_trade_no="out_trade_no_20190910_141442"
    partner="208xxxxxxxxx5500"
    payment_inst="ALIPAYCN"
    payment_type="1"
    product_code="NEW_WAP_OVERSEAS_SELLER"
    refer_url="http://www.mikascoffee.com"
    return_url="http://www.mikascoffee.com/return"
    seller_id="208xxxxxxxxx5500"
    service="mobile.securitypay.pay"
    subject="Mika's coffee shop"
    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="GWWdENlqkRvlgXGxC2ucdnRYKe8ta2bsvgZSuo37jD6pp1e3yyy2f3/NVL7Qkv1poxxX7IYczk56ijo11c27Gi/lkn4QYJ9DcpYcdv469YA+WdHjOw0EkkXWZTMhCznO7psXAqeXleBkDHoE7KyqhddPrloOgIZ6aSfl6Tjc+qI="
memo=

Asynchronous response

http://www.mikascoffee.com/notify
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx2954
notify_type=trade_status_sync
sign=$$$
trade_no=201xxxxxxxxxxxxxxxxxxxx7004
total_fee=0.01
out_trade_no=out_trade_no_20190910_140255
notify_time=2019-09-10 14:23:31
currency=HKD
trade_status=TRADE_FINISHED
sign_type=RSA