create_forex_trade

Environment

HTTPS request URL

Production environment

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

Test environment

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

Parameter

Description

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

Example:UTF-8

sign_type

String Required

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

Example:RSA2

sign

String Required

Sign value

Example:_p_w_l_h_j0b_gd_aejia7n_ko4_m%2Fu_w_jd3_nx_s_k_mxus9_hoxg_y_r_lunli_pmma29_t_q==

notify_url

URL(200)

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

Example:http://www.test.com/alipay/notify_url.php

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

Example:800.00

order_gmt_create

Date

This parameter can only be used with order_valid_time to control the valid time from redirection to login. 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

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

qr_pay_mode

String Required

QR code payment mode. Forward QR code mode and redirecting mode are supported. Forward mode is the mode of placing the QR code to the merchant's order confirmation page. Fixed value: 4 

Example:4

qrcode_width

Integer Required

The merchant customized QR code width. When qr_pay_mode=4, this parameter takes effect. 

Example:200

payment_inst

String

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

Example:ALIPAYHK, ALIPAYCN

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

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

NumberRequired

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

Parameter

Description

Basic parameter

notify_type

String

Notification type, with a value of trade_status_sync 

Example:trade_status_sync

notify_id

String

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

sign_type

String

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

Example:RSA

sign

String

Sign value

Example:p_w_l_h_j0b_gd_aejia7n_ko4_m%2Fu_w_jd3_nx_s_k_mxus9_hoxg_y_r_lunli_pmma29_t_q==

Business parameter

trade_status

String

Alipay transaction status. The value can be TRADE_FINISHED, WAIT_BUYER_PAY, or TRADE_CLOSED. 

Example:TRADE_FINISHED

trade_no

String

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

Example:2015070800001000100080029361

out_trade_no

String

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

The settlement currency 

Example:HKD

total_fee

Number(9,2)

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

Example:11.00

Trigger condition name

Description

Note

TRADE_FINISHED

Trade successfully

true (trigger nofitication)

WAIT_BUYER_PAY

Trade creation

false (does not trigger nofitication)

TRADE_CLOSED

Trade closed

true (trigger nofitication)

Returned Result

Description

FOREX_MERCHANT_NOT_SUPPORT_THIS_CURRENCY

This 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

The currency parameter is incorrect.

ILLEGAL_TIMEOUT_RULE

The timeout_rule parameter is incorrect.

SYSTEM_EXCEPTION

Alipay system error

ILLEGAL_ARGUMENT

Incorrect parameter

Returned Result

Description

ILLEGAL_SIGN

Illegal signature

ILLEGAL_SERVICE

The service parameter is incorrect.

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

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