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

      create_forex_trade_wap

      Call this interface to initiate a wap 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
      Basic parameter

      service

      String Required

      Interface name 

      Example:create_forex_trade_wap

      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, RSA2 and MD5 are supported. Use uppercase. 

      Example:MD5

      sign

      String Required

      Sign value 

      Example:e5815a4556db338ed237f7d3fd222184

      notify_url

      URL(200)

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

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

      return_url

      URL(200)

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

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

      Business parameter

      payment_inst

      String(16)

      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

      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

      body

      String(400)

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

      Example:Glitter leggings

      out_trade_no

      String(64)

      Required

      The unique transaction ID that is assigned by the partner. If the ID is duplicated with the out_trade_no of a previous transaction, the payment fails and an error message is returned to indicate the payment is duplicated.

      Example:990xxxxxxx8989

      currency

      String(10)

      Required

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

      Example:HKD

      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.

      Example:100.30

      timeout_rule

      String(10)

      This parameter specifies the valid time from login to completion. The default value is 12h. If the time in hour is non-integer, convert the value to the time in minutes.

      Example:12h

      order_create

      long(10)


      The time when the payment transaction is created. This field is used together with timeout_rule to control the transaction valid time. The time is in milliseconds, which can be obtained by using the Java method System.currentTimeMillis(), since the epoch (January 1, 1970 00:00:00 GMT). Use Beijing time to synchronize with Alipay system.

      Example:1586497520310

      supplier

      String(16)

      Supplier name, which is used for page display.

      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_industryString(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

      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

      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_typeString

      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_timeDate

      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_time

      Date

      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_numberString

      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_time

      Date 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_quantityNumber

      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
      Basic parameter

      sign_type

      String

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

      Example:RSA

      sign

      String

      Signature value Example:e5815a4556db338ed237f7d3fd222184
      Business parameter

      trade_status

      String(32)

      Alipay transaction status. For each transaction, partner must ensure that the status is TRADE_FINISHED. See Trade status for details. Example:TRADE_FINISHED

      trade_no

      String(64)

      Alipay transaction ID, with a length in the range 16 - 64 bits.

      Example:2015070800001000100080029361

      out_trade_no

      String(64)

      The unique transaction ID that is assigned by the partner. This parameter is transmitted by the corresponding request and needs to be returned with the original value.

      Example:990xxxxxxx8989

      currency

      String(3)

      The settlement currency 

      Example:HKD

      total_fee

      Number(9,2)

      The payment amount

      Example:11.00

      #Asynchronous response

      ParameterDescription
      Basic parameter

      sign_type

      String

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

      Example:RSA

      sign

      String

      Sign value 

      Example:e5815a4556db338ed237f7d3fd222184

      Business parameter

      notify_type

      String

      Notification type, with a value of trade_status_sync 

      Example:trade_status_sync

      notify_id

      String(34)

      Notification ID, used by the partner system to verify the notification

      Example:92c60707dc43a5b2d648b7b4d3c2e1592g

      notify_time

      Timestamp

      The time in GMT+8 when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss.

      Example:2015-06-30 09:56:02

      trade_status

      String(32)

      Trade status, the value can be TRADE_FINISHED or TRADE_CLOSED. See Trade status for details.

      Example:TRADE_FINISHED

      trade_no

      String(64)

      Alipay transaction ID, with a length in the range 16 - 64 bits.

      Example:2015070800001000100080029361

      out_trade_no

      String(64)

      The unique transaction ID that is assigned by the partner. This parameter is transmitted by the corresponding request and needs to be returned with the original value.

      Example:990xxxxxxx8989

      currency

      String(3)

      The settlement currency 

      Example:HKD

      total_fee

      Number(9,2)

      The payment amount, which is a floating number in the range 0.01 - 1000000.00.

      Example:11.00


      #Nofitication trigger condition

      Trigger condition nameDescription Note
      TRADE_FINISHEDTrade successfullytrue (trigger nofitication)
      WAIT_BUYER_PAYTrade creationfalse (does not trigger nofitication)
      TRADE_CLOSEDTrade closedtrue (trigger nofitication)


      For more information about the asynchronous response, see Asynchronous notification.


      #Error codes

      #Business errors

      Returned ResultDescription
      FOREX_MERCHANT_NOT_SUPPORT_THIS_CURRENCYThis currency is not supported.
      ILLEGAL_SECURITY_PROFILEThis kind of encryption is not supported.
      REPEAT_OUT_TRADE_NOThe out_trade_no parameter is duplicated.
      ILLEGAL_CURRENCYThe currency parameter is incorrect.
      ILLEGAL_TIMEOUT_RULEThe timeout_rule parameter is incorrect.
      SYSTEM_EXCEPTIONAlipay system error
      ILLEGAL_ARGUMENTIncorrect parameter

      #Access errors

      Returned ResultDescription
      ILLEGAL_SIGNIllegal signature
      ILLEGAL_SERVICEService Parameter is incorrect.
      ILLEGAL_PARTNERIncorrect partner ID
      ILLEGAL_SIGN_TYPESignature is of wrong type.
      ILLEGAL_PARTNER_EXTERFACEThe service is not activated for this account.
      ILLEGAL_DYN_MD5_KEYThe dynamic key information is incorrect.
      ILLEGAL_ENCRYPTEncryption is incorrect.
      ILLEGAL_USERUser ID is incorrect.
      ILLEGAL_EXTERFACEInterface configuration is incorrect.
      ILLEGAL_AGENTThe agency ID is incorrect.
      HAS_NO_PRIVILEGENo right to visit
      INVALID_CHARACTER_SETThe character set is invalid.

      #System errors

      Returned resultDescription
      SYSTEM_ERRORAlipay system error
      SESSION_TIMEOUTSession timeout
      ILLEGAL_TARGET_SERVICEWrong target service
      ILLEGAL_ACCESS_SWITCH_SYSTEMMerchant is not allowed to visit system of this type.
      EXTERFACE_IS_CLOSEDThe interface has been closed.

      #Samples

      #Request

      Request sample for merchants directly integrated with Alipay

      https://intlmapi.alipay.com/gateway.do?service=create_forex_trade_wap&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=http%3A%2F%2Fwww.mikascoffee.com%2Fnotify&return_url=http%3A%2F%2Fwww.mikascoffee.com%2Freturn&currency=HKD&product_code=NEW_WAP_OVERSEAS_SELLER&payment_inst=ALIPAYHK&subject=Mika's coffee shop&out_trade_no=out_trade_no_20190910_140243&total_fee=0.01&refer_url=http%3A%2F%2Fwww.mikascoffee.com&trade_information={"business_type"%3A"4"%2C"goods_info"%3A"Mika's capsule coffee^1"%2C"total_quantity"%3A"1"}&sign=c74a6ab82817bd9a325cacaac2d67322


      Request sample for acquirers and system integrators with secondary merchants

      https://intlmapi.alipay.com/gateway.do?service=create_forex_trade_wap&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=http%3A%2F%2Fwww.mikascoffee.com%2Fnotify&return_url=http%3A%2F%2Fwww.mikascoffee.com%2Freturn&currency=HKD&product_code=NEW_WAP_OVERSEAS_SELLER&payment_inst=ALIPAYHK&subject=Mika's coffee shop&out_trade_no=out_trade_no_20190910_140243&total_fee=0.01&secondary_merchant_id=1314520&secondary_merchant_name=Mika's coffee shop&secondary_merchant_industry=5499&sign=82386d719493e90f17ac6e22f2e8de22

      #Response

      Synchronous response

      http://www.mikascoffee.com/return?currency=HKD&out_trade_no=out_trade_no_20190910_140255&total_fee=0.01&trade_no=201xxxxxxxxxxxxxxxxxxxx7004&trade_status=TRADE_FINISHED&sign=d9ab0ebb4d2cd4a3a4a83ccdc4c6e6da&sign_type=MD5

      copy
      http://www.mikascoffee.com/return
      currency=HKD
      out_trade_no=out_trade_no_20190910_140255
      total_fee=0.01
      trade_no=201xxxxxxxxxxxxxxxxxxxx7004
      trade_status=TRADE_FINISHED
      sign=d9ab0ebb4d2cd4a3a4a83ccdc4c6e6da
      sign_type=MD5


      Asynchronous response

      copy
      http://www.mikascoffee.com/notify
      notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx2953
      notify_type=trade_status_sync
      sign=$$
      trade_no=201xxxxxxxxxxxxxxxxxxxxx7003
      total_fee=0.01
      out_trade_no=out_trade_no_20190910_140243
      notify_time=2019-09-10 14:11:45
      currency=HKD
      trade_status=TRADE_FINISHED
      sign_type=MD5