create_forex_trade

Environment

HTTPS request URL

Production environment

https://intlmapi.alipay.com/gateway.do

Test environment

https://mapi.alipaydev.com/gateway.do

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

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 specified by the currency parameter. When the currency 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)

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)

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"}

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

sign_type

String

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

Example:RSA

sign

String

Sign value 

Example:e5815a4556db338ed237f7d3fd222184

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

sign_type

String

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

Example:RSA

sign

String

Sign value 

Example:e5815a4556db338ed237f7d3fd222184

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

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)

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.

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.

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.