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

      create_forex_trade

      Call this interface to initiate a website 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

      ParameterDescription
      Basic parameter

      service

      String Required

      Interface name

      Example:create_forex_trade

      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 are encoded. GBK and UTF-8 are supported. 

      Example:UTF-8

      sign_type

      String Required

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

      Example:RSA

      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

      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 merchant. 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. Use upper case. For more information about supported currencies, see Supported Currencies.

      Example:USD

      total_fee

      Number(9,2)

      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

      rmb_fee

      Number(9,2)

      The transaction amount in RMB, which is a floating number in the range 0.01 - 1000000.00. This parameter is used to replace the total_fee parameter when merchants want to price their product in RMB. If total_fee is used, don't specify the rmb_fee parameter because they are mutually exclusive. 

      Example:100.30

      timeout_rule

      String(10)

      This parameter specifies the valid time from login to completion. The default value is 12h. Contact Alipay Technical Support if you need to use other values. 

      Example:5m 10m 15m 30m 1h 2h 3h 5h 10h 12h.

      order_gmt_create

      Date

      The time when the payment transaction is created. This field is used together with order_valid_time to control the transaction valid time. The format is yyyy-MM-dd HH:mm:ss. Use Beijing time to synchronize with Alipay system. 

      Example:2013-11-27 15:45:57

      order_valid_time

      String(5)

      Order valid time in seconds, with a maximum value of 2592000. This field can only be used with the order_gmt_create field to control the valid time. The payment transaction is to be closed after the order valid time from the order creation time specified by the order_gmt_create field. 

      Example:3600

      supplier

      String(16)

      Supplier name, which is used for page display.

      secondary_merchant_id

      String(64)

      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(64)

      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

      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 not required 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_OVERSEAS_SELLER for this interface.

      Note: This field is not required for the old cross-border website payment product. Contact technical support if you are not sure about your product type.

      Example:NEW_OVERSEAS_SELLER

      split_fund_info

      String(1600)

      Split fund information, which is in the JSON format. For more details, see Split detail info.
      trade_information

      String(6000) Required

      Information about the trade industry. See trade_information for details. 

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

      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, separate type values with vertical bar (|).

      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_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_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_time

      Date Required

      Departure time. Format: yyyy-MM-dd HH:mm Timezone: 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


      Notes:

      • When the merchant wishes to price their products in RMB, the merchant can put the CNY payment amount in the rmb_fee field. In the same time, the total_fee field needs to be ignored. The payment amount will be displayed in RMB to the user.
        • The merchant must not change the value of the currency field, which is the settlement currency that Alipay pays the merchant in.
        • The total_fee or rmb_fee field are mutually exclusive. One and only one of them can be used.
      • 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.
      • If both order_gmt_create + order_valid_time and timeout_rule are specified, order_gmt_create + order_valid_time will be used for order timeout control. Alipay suggests to use order_gmt_create + order_valid_time for order timeout control.
      • The merchant cannot attach parameters to return_url in order to pass them to Alipay. Alipay will remove all extra parameters in the return_url field.

      #Response

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

      trade_status

      String(32)

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

      Example:TRADE_FINISHED

      trade_no

      String(64)

      The serial number assigned by Alipay to identify a trade in the Alipay system, 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 merchant. This parameter is transmitted by the corresponding request and needs to be returned with the original value. 

      Example:990xxxxxxx8989

      currency

      String(3)

      Settlement currency code 

      Example:USD

      total_fee

      Number(9,2)

      The transaction amount. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

      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)

      Alipay transaction status. See Trade status for details.

      Example:TRADE_FINISHED

      trade_no

      String(64)

      The serial number assigned by Alipay to identify a trade in the Alipay system, 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 merchant. This parameter is transmitted by the corresponding request and needs to be returned with the original value. 

      Example:990xxxxxxx8989

      currency

      String(3)

      Settlement currency code 

      Example:USD

      total_fee

      Number(9,2)

      The transaction amount. This parameter is transmitted by the corresponding request and needs to be returned with its original value.

      Example:11.00

      #Notification trigger condition

      Trigger condition name

      Description

      Note

      TRADE_FINISHED

      Trade is completed successfully

      true (trigger notification)

      WAIT_BUYER_PAY

      Trade creation

      false (does not trigger notification)

      TRADE_CLOSED

      Trade closed

      true (trigger notification)


      Please pay attention to the specifications when you use asynchronous notifications:

      • Ensure that the Notification Page (as configured by 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.
      • Asynchronous notification is only sent when a transaction exists in Alipay system and the transaction status is changed. For example, if the status of a real-time transaction is WAIT_BUYER_PAY, no notification is sent.
      • For some interfaces, if both return_url and notify_url are passed, both synchronous redirection and asynchronous notification are used when a transaction reaches a final state.
      • Asynchronous notification is the interaction between servers, which, unlike interaction between websites, is usually not visible.
      • After the notification is processed, the notification 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, 10m, 1h, 2h, 6h, 15h).
      • After the notification is processed, the notification page must not redirect. Otherwise, Alipay will not recognize a "success" string. Alipay system will then regard it as an error and keep sending notification.
      • Cookies and sessions are invalid on the notification page, which means these data cannot be captured.
      • The configuration and testing of asynchronous notification must be on a server that is connected to internet.
      • The main purpose of the asynchronous notification is to prevent loss of transaction orders. Even if a synchronous redirection fails, asynchronous notification can ensure that the merchant can still obtain the transaction information.
      • Alipay uses notify_id for idempotence control of asynchronous notifications. When the merchant receives the asynchronous notification and prints "success", the parameter notify_id becomes invalid.
      • 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, excluding sign_type and sign.

      #Error codes

      #Business errors

      Returned Result

      Description

      FOREX_MERCHANT_NOT_SUPPORT_THIS_CURRENCY

      The currency is not supported.

      ILLEGAL_SECURITY_PROFILE

      This kind of encryption is not supported.

      REPEAT_OUT_TRADE_NO

      The out_trade_no parameter is duplicated.

      ILLEGAL_CURRENCY

      Incorrect currency parameter

      ILLEGAL_TIMEOUT_RULE

      Incorrect timeout_rule parameter

      SYSTEM_EXCEPTION

      Alipay system error

      ILLEGAL_ARGUMENT

      Incorrect parameter

      SECONDARY_MERCHANT_ID_BLANK

      The secondary merchant ID is not provided to Alipay.

      SECONDARY_MERCHANT_ID_INVALID

      The secondary merchant is not registered with Alipay.

      SECONDARY_MERCHANT_STATUS_ERROR

      The status of secondary merchant is abnormal in the Alipay system.

      #Access errors

      Returned Result

      Description

      ILLEGAL_SIGN

      Illegal signature

      ILLEGAL_SERVICE

      Incorrect service parameter

      ILLEGAL_PARTNER

      Incorrect partner ID

      ILLEGAL_SIGN_TYPE

      Signature is of wrong type.

      ILLEGAL_PARTNER_EXTERFACE

      Service is not activated for this account.

      ILLEGAL_DYN_MD5_KEY

      Dynamic key information is incorrect.

      ILLEGAL_ENCRYPT

      Encryption is incorrect.

      ILLEGAL_USER

      User ID is incorrect.

      ILLEGAL_EXTERFACE

      Interface configuration is incorrect.

      ILLEGAL_AGENT

      Agency ID is incorrect.

      HAS_NO_PRIVILEGE

      Not authorized to visit.

      INVALID_CHARACTER_SET

      The character set is invalid.

      #System errors

      Returned result

      Description

      SYSTEM_ERROR

      Alipay system error

      SESSION_TIMEOUT

      Session timeout

      ILLEGAL_TARGET_SERVICE

      Wrong  target service

      ILLEGAL_ACCESS_SWITCH_SYSTEM

      Merchant is not allowed to visit system of this type.

      EXTERFACE_IS_CLOSED

      The interface has been closed.

      #Samples

      #Request

      Request sample for merchants directly integrated with Alipay

      https://intlmapi.alipay.com/gateway.do?service=create_forex_trade&partner=208xxxxxxxxx6931&_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=USD&product_code=NEW_OVERSEAS_SELLER&subject=Mika's%20capsule%20coffee&out_trade_no=out_trade_no_20190826_204550&total_fee=12&refer_url=http%3A%2F%2Fwww.mikascoffee.com&trade_information=%7B%22business_type%22%3A%224%22%2C%22goods_info%22%3A%22Mika's%20capsule%20coffee%5E1%22%2C%22total_quantity%22%3A%221%22%7D&sign=2f269efd5b601babfa8a698e65253ea3


      Request sample for acquirers and system integrators with secondary merchants

      https://intlmapi.alipay.com/gateway.do?service=create_forex_trade&partner=208xxxxxxxxx6931&_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=USD&product_code=NEW_OVERSEAS_SELLER&subject=Mika's%20capsule%20coffee&out_trade_no=out_trade_no_20190826_204550&total_fee=12&secondary_merchant_id=1314520&secondary_merchant_name=China%20Substation&secondary_merchant_industry=5499&sign=0ef10a4855cfbd82d2c5865414104823


      #Response

      Synchronous response sample

      http://www.mikascoffee.com/return?out_trade_no=out_trade_no_20190826_204553&total_fee=0.01&trade_status=TRADE_FINISHED&sign=777dac430d4177aa4683877951512613&trade_no=2019082622001336530599785994&currency=USD&sign_type=MD5


      copy
      http://www.mikascoffee.com/return
      out_trade_no=out_trade_no_20190826_204553
      total_fee=0.01
      trade_status=TRADE_FINISHED
      sign=777dac430d4177aa4683877951512613
      trade_no=2019082622001336530599785994
      currency=USD
      sign_type=MD5


      image.png

      image.png


      Asynchronous response sample

      http://www.mikascoffee.com/notify?notify_id=2019082600222210609036530579173208&notify_type=trade_status_sync&sign=$amp;trade_no=2019082622001336530599785994&total_fee=0.01&forex_rate=7.20211000&notify_reg_time=2019-08-26 21%3A06%3A09.149&out_trade_no=out_trade_no_20190826_204553&rmb_fee=0.07&currency=USD&notify_time=2019-08-26 21%3A06%3A09&trade_status=TRADE_FINISHED&sign_type=MD5


      copy
      http://www.mikascoffee.com/notify
      notify_id=2019082600222210609036530579173208
      notify_type=trade_status_sync
      sign=$$
      trade_no=2019082622001336530599785994
      total_fee=0.01
      forex_rate=7.20211000
      notify_reg_time=2019-08-26 21:06:09.149
      out_trade_no=out_trade_no_20190826_204553
      rmb_fee=0.07
      currency=USD
      notify_time=2019-08-26 21:06:09
      trade_status=TRADE_FINISHED
      sign_type=MD5