mobile.securitypay.pay

2025-01-20 08:29

Call this interface to initiate an app payment request.

Request

Service address

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

Request parameters

Parameter Description

service

String

Required

Interface name

Example:mobile.securitypay.pay

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********662

_input_charset

String Required

The charset with which the request data is encoded. UTF-8 is supported.

Example:UTF-8

sign_type

String Required

Sign type. RSA and RSA2 are supported. Use uppercase.

Note: RSA2 cannot be used for synchronous notification verification.

Example:RSA

sign

String Required

Sign value

Example:lBBK%2F0w5LOajrMrji7DUgEqNjIhQbidR13GovA5r3TgIbNqv231yC1NksLdw%2Ba3JnfHXoXuet6XNNHtn7VE%2BeCoRO1O%2BR1KugLrQEZMtG5jmJIe2pbjm%2F3kb%2FuGkpG%2BwYQYI51%2BhA3YBbvZHVQBYveBqK%2Bh8mUyb7GM1HxWs9k4%3D

return_url

URL(200)

After the payment is completed, the web page is redirected to this URL.

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

notify_url

URL(200)

The URL for receiving asynchronous notifications after the payment is completed.

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

payment_inst

String

Indicates the type of wallet this QR code can be scanned. If this field is set to ALIPAYHK, then the QR code can only be scanned by Alipay HK Wallet. If this field is set to ALIPAYCN, then the QR code can only be scanned by Alipay Wallet. If this field is set to null, then the QR code can only be scanned by Alipay Wallet.

Example:ALIPAYHK

appenv

String

A string used to identify client source. Parameter value is agreed as follows: appenv="system=client platform name ^version=business system version".

Example:appenv=”system=android^version=3.0.1.2”

out_trade_no

String(64) Required

Unique Alipay order ID on the merchant website

Example:990xxxxxxx8989

subject

String(256) Required

Brief description of the transaction. Special characters are not supported.

Note: The value of this field will be displayed to customers.

Example:kids clothing

payment_type

String(4) Required

Payment type. The default value is 1, which stands for purchase of goods.

Example:1

seller_id

String(16) Required

Seller's Alipay account number (email or mobile number format) or the corresponding unique Alipay user number (16 single digits beginning with 2088).

Example:xxx@alipay.com

total_fee

Number(9,2) Required

The transaction amount, which is a floating number in the range 0.01 - 1000000.00. If total_fee is not null, the transaction uses a currency that is not CNY and the product price is to be calculated in RMB based on the exchange rate. If total_fee is specified, don't specify rmb_fee at the same time.

Example:0.01

body

String(1000) Required

Detailed description about the goods. Special characters are not supported.

Example:Glitter leggings

currency

String(10) Required

Settlement currency that the merchant specifies in the contract. Only HKD is supported.

Example:HKD

forex_biz

String(10) Required

The value of this field is FP.

Example:FP

it_b_pay

String

Specifies the expiration time of unpaid transactions. The trade is closed automatically once the time is up. The value of this field is in the range of 1m - 15d or can be an absolute time such as 2014-06-13 16:00:00.

Notes:

1、The following abbreviations are used to present units of time:

m: minute

h: hour

d: day

c: current day (Whenever the trade is created, it will be closed at 0:00).

2、Decimal point of the numerical value of this parameter is rejected, for example, 1.5h need to be transformed to 90m.

Example:30m

extern_token

String(32)

The token that includes account information, returned by open platform. With the authorization token, merchants can access some services of Alipay within a specified period.

Example:1b258b84ed2faf3e88b4d979ed9fd4db

refer_url

URL(200) Required

The URL of the merchant website homepage. If the merchant doesn't have a website, the merchant app download address can be used for this field.

Note: This field is required for merchants that are directly integrated with Alipay, and is optional for acquirers.

Example:http://testmerchant.com

product_code

String(32) Required

Product code of the Alipay product that you use, with a value of NEW_WAP_OVERSEAS_SELLER for this interface.

Example:NEW_WAP_OVERSEAS_SELLER

secondary_merchant_id

String(32)

The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.

Note: This field is required for acquirers and system integrators with secondary merchants, and is not required for merchants that are directly integrated with Alipay.

Example:A80001

secondary_merchant_name

String(32)

Registration legal name of the secondary merchant, shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant.

Note: This field is required for acquirers and system integrators with secondary merchants, and is not required for merchants that are directly integrated with Alipay.

Example:Muku

secondary_merchant_industry

String(4)

Industry classification identifier of the secondary merchant, which is assigned by Alipay. For more information about the MCC code, see MCC list.

Note: This field is required for acquirers and system integrators with secondary merchants, and is not required for merchants that are directly integrated with Alipay.

Example:7011

trade_information

String(6000) Required

Note: This field is required for merchants that are directly integrated with Alipay, and is optional for acquirers. Besides, if you are a merchant that is directly integrated with Alipay, 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.

Example:{"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"}

trade_information

Parameter Description

business_type

String Required

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, use the vertical bar to seperate type values.

Example:1|2|3|4|5 or 1

hotel_name

String Required

Hotel name that consists of numbers, letters, spaces, and special characters including ,.<>()[]/\-,. If more than one hotel name exists, separate values with vertical bar (|). Specify this field only when business_type is 1 (Hotel).

Example:zlidu, sluhg-987, 889utng

check_in_time

Date Required

Check-in time. Format: yyyy-MM-dd. Timezone: GMT +8. Specify this field only when business_type is 1 (Hotel).

Example:2018-10-20

check_out_timeDate Required

Check-out time. Format: yyyy-MM-dd. Timezone: GMT +8. Specify this field only when business_type is 1 (Hotel).

Example:2018-10-22

flight_number

String Required

Flight number. If flight transfer exists, separate flight numbers with vertical bar (|). Specify this field only when business_type is 2 (AIR).

Example:NWS 996|TWF 8854

departure_timeDate Required

Departure time.Format: yyyy-MM-dd HH:mmTimezone: GMT +8. If flight transfer exists, separate time values with vertical bar (|). Specify this field only when business_type is 2 (AIR).

Example:2018-10-22 20:49

admission_notice_url

String Required

If business_type is 3 (Overseas study consulting), the URL of admission notice (image) must be specified.

Example:https://www.iconfont.cn/search/index?test

goods_info

String Required

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 vertical bar (|). Specify this field only when business_type is 4 (Sales of goods).

Example:pencil^2|eraser^5|iPhone XS 256G^1

total_quantity

Number Required

Total quantities of all goods in one order. Specify this field only when business_type is 4 (Sales of goods).

Example:8

other_business_type

String Required

If business_type is 5 (Others), specify the business type in details.

Example:Airport pick up service

Note:

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

Response

Synchronous response

Parameter Description

resultStatus

String Required

Status code, which is returned from the operation. For more details, see Codes returned to the client end.

Example:9000

result

String Required

Result data returned from the operation. The part before &success="true"&sign_type="RSA"&sign="xxx" is the original request data of the merchant. The value of “success” is used to indicate the result of the payment. The value of "sign" is the signature of Alipay for the result of the payment. The merchant needs to verify this signature with the Alipay public key.

Example:_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_20190826_204539"&partner="2088021017666931"&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"&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

String

Parameter reserved. Normally there is no content.

Codes returned to the client end

Return code	Description
9000	Successful order payment
8000	Under processing, with unknown payment result. The payment might have been made successfully or not. Inquiry the order payment status in the sellers' order list. This code is returned from Alipay server side.
4000	Failed order payment
6001	Cancelled by the user during the process
6002	Error occurred in the network connection
6004	Unknown payment result, which means the payment might have been made successfully or not. Inquiry the order payment status in the sellers' order list. This code is usually returned when the network issue prevents the Alipay client to receive a response from the Alipay server side.
Others	Other payment errors

Asynchronous response

Parameter	Description
notify_type String	Notification type, with a value of forex_trade_status_sync
notify_id String(34)	Notification ID, used by the partner system to verify the notification
notify_time Timestamp	The time in GMT+8 when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss.
sign String	Sign value
sign_type String	Sign type
out_trade_no String(64)	Unique order ID in the merchant system
trade_statusString(32)	Trade status, with a value of TRADE_FINISHED or TRADE_CLOSED. See Trade status for details.
trade_no String(16)	Unique order ID in the Alipay system
currency String(10)	The settlement currency
total_fee Number(9,2)	The transaction amount, which is a floating number in the range 0.01 - 1000000.00.

Notification trigger condition

Trigger condition name	Description on trigger condition	Note
TRADE_FINISHED	Trade successfully	true (trigger notification)
WAIT_BUYER_PAY	Trade creation	false (does not trigger notification)
TRADE_CLOSED	Trade 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

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:

Verify the signature.
Verify whether the notification is sent by Alipay. See Verify The Notification Is Sent by Alipay for more details.
Process business data:

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

Enumeration name	Enumeration description
WAIT_BUYER_PAY	The trade is created and waits for buyer to pay
TRADE_CLOSED	The trade is closed due to absence of payment in the specified time.
TRADE_FINISHED	The trade has been made successfully and refund can be requested.

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 is in the text format.

The full request link is shown below:

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

Error codes（error_code）	Meanings
ILLEGAL_SIGN	Incorrect signature
ILLEGAL_DYN_MD5_KEY	Dynamic private key information error
ILLEGAL_ENCRYPT	Incorrect encryption
ILLEGAL_ARGUMENT	Incorrect parameter
ILLEGAL_SERVICE	Incorrect API name
ILLEGAL_PARTNER	Incorrect cooperating partner ID
ILLEGAL_EXTERFACE	Incorrect API configuration
ILLEGAL_PARTNER_EXTERFACE	Incorrect cooperating partner API configuration
ILLEGAL_SECURITY_PROFILE	Private key configuration without matching detected
ILLEGAL_AGENT	Incorrect agency ID
ILLEGAL_SIGN_TYPE	Incorrect signature type
ILLEGAL_CHARSET	Illegal character set
ILLEGAL_CLIENT_IP	No right integration service of customer’s IP address
ILLEGAL_DIGEST_TYPE	Incorrect abstract type
ILLEGAL_DIGEST	Incorrect file abstract
ILLEGAL_FILE_FORMAT	Incorrect file format
ILLEGAL_ENCODING	The coding type is not supported.
ILLEGAL_REQUEST_REFERER	Anti-phishing inspection does not support the request resource.
ILLEGAL_ANTI_PHISHING_KEY	Illegal timestamp parameter of anti-phishing inspection
ANTI_PHISHING_KEY_TIMEOUT	Overtime of anti-phishing inspection timestamp
ILLEGAL_EXTER_INVOKE_IP	Illegal callback IP of anti-phishing inspection
ILLEGAL_NUMBER_FORMAT	Illegal digital format
ILLEGAL_INTEGER_FORMAT	Illegal “int” type format
ILLEGAL_MONEY_FORMAT	Illegal amount format
ILLEGAL_DATA_FORMAT	Wrong data format
REGEXP_MATCH_FAIL	Failed matching of regular expression
ILLEGAL_LENGTH	Illegal parameter value length
PARAMTER_IS_NULL	Null parameter
HAS_NO_PRIVILEGE	No privilege to use the service
SYSTEM_ERROR	Wrong Alipay system
SESSION_TIMEOUT	Session overtime
ILLEGAL_TARGET_SERVICE	Wrong “target_service”
ILLEGAL_ACCESS_SWITCH_SYSTEM	“partner” does not allow the system of the type.
ILLEGAL_SWITCH_SYSTEM	Abnormal switching system
EXTERFACE_IS_CLOSED	Closed API

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

copy
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

copy
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