Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      mobile.securitypay.pay

      Call this interface to initiate an app payment request.

      #Request

      #Service address

      EnvironmentHTTPS request URL
      Production environmenthttps://intlmapi.alipay.com/gateway.do
      Test environmenthttps://mapi.alipaydev.com/gateway.do

      #Request parameters

      ParameterDescription

      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

      ParameterDescription

      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 (&verbar;). 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 (&verbar;). 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

      ParameterDescription

      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 codeDescription
      9000Successful order payment
      8000Under 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.
      4000Failed order payment
      6001Cancelled by the user during the process
      6002Error occurred in the network connection
      6004Unknown 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.
      OthersOther payment errors

      #Asynchronous response

      ParameterDescription

      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 nameDescription on trigger conditionNote
      TRADE_FINISHEDTrade successfullytrue (trigger nofitication)
      WAIT_BUYER_PAYTrade creationfalse (does not trigger nofitication)
      TRADE_CLOSEDTrade closedtrue (trigger nofitication)

      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

      Enumeration nameEnumeration description
      WAIT_BUYER_PAYThe trade is created and waits for buyer to pay
      TRADE_CLOSEDThe trade is closed due to absence of payment in the specified time.
      TRADE_FINISHEDThe trade has been made successfully and refund can be requested.

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

      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_SIGNIncorrect signature
      ILLEGAL_DYN_MD5_KEYDynamic private key information error
      ILLEGAL_ENCRYPTIncorrect encryption
      ILLEGAL_ARGUMENTIncorrect parameter
      ILLEGAL_SERVICEIncorrect API name
      ILLEGAL_PARTNERIncorrect cooperating partner ID
      ILLEGAL_EXTERFACEIncorrect API configuration
      ILLEGAL_PARTNER_EXTERFACEIncorrect cooperating partner API configuration
      ILLEGAL_SECURITY_PROFILEPrivate key configuration without matching detected
      ILLEGAL_AGENTIncorrect agency ID
      ILLEGAL_SIGN_TYPEIncorrect signature type
      ILLEGAL_CHARSETIllegal character set
      ILLEGAL_CLIENT_IPNo right integration service of customer’s IP address
      ILLEGAL_DIGEST_TYPEIncorrect abstract type
      ILLEGAL_DIGESTIncorrect file abstract
      ILLEGAL_FILE_FORMATIncorrect file format
      ILLEGAL_ENCODINGThe coding type is not supported.
      ILLEGAL_REQUEST_REFERERAnti-phishing inspection does not support the request resource.
      ILLEGAL_ANTI_PHISHING_KEYIllegal timestamp parameter of anti-phishing inspection
      ANTI_PHISHING_KEY_TIMEOUTOvertime of anti-phishing inspection timestamp
      ILLEGAL_EXTER_INVOKE_IPIllegal callback IP of anti-phishing inspection
      ILLEGAL_NUMBER_FORMATIllegal digital format
      ILLEGAL_INTEGER_FORMATIllegal “int” type format
      ILLEGAL_MONEY_FORMATIllegal amount format
      ILLEGAL_DATA_FORMATWrong data format
      REGEXP_MATCH_FAILFailed matching of regular expression
      ILLEGAL_LENGTHIllegal parameter value length
      PARAMTER_IS_NULLNull parameter
      HAS_NO_PRIVILEGENo privilege to use the service
      SYSTEM_ERRORWrong Alipay system
      SESSION_TIMEOUTSession overtime
      ILLEGAL_TARGET_SERVICEWrong “target_service”
      ILLEGAL_ACCESS_SWITCH_SYSTEM“partner” does not allow the system of the type.
      ILLEGAL_SWITCH_SYSTEMAbnormal switching system
      EXTERFACE_IS_CLOSEDClosed 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