create_forex_trade_wap

2020-11-09 09:09

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

Parameter Description

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

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

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

Example:NEW_WAP_OVERSEAS_SELLER

split_fund_info

String(1600)

Split fund information, which is in the JSON format. For more details, see Split Detail Info.

app_pay

String(1)

The flag that is used to identify whether the transaction activates Alipay wallet app to process the payment. If Alipay wallet app is not installed, the payment will be processed by the WAP page.

Example:app_pay=Y

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

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

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:

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.

#Response

#Synchronous response

Parameter Description

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

rmb_fee

Number(9,2)

The transaction amount in RMB.

Note: This parameter is returned only when merchants used this parameter in the request.

Example:1.00

#Asynchronous response

Parameter Description

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, with a value of TRADE_FINISHED or TRADE_CLOSED. 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)

Example:990xxxxxxx8989

currency

String(3)

Settlement currency code

Example:USD

total_fee

Number(9,2)

The transaction amount

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)

#Error codes

#Business errors

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 value of the out_trade_no parameter is duplicated.
ILLEGAL_CURRENCY	The value of the currency parameter is incorrect.
ILLEGAL_TIMEOUT_RULE	The value of the timeout_rule parameter is incorrect.
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	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.

#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_wap&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_WAP_OVERSEAS_SELLER&subject=Mika's%20capsule%20coffee&out_trade_no=out_trade_no_20190826_204554&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=7af72fa01f18138abe6f3911d9097089

Request sample for acquirers and system integrators with secondary merchants
https://intlmapi.alipay.com/gateway.do?service=create_forex_trade_wap&partner=2088021017666931&_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_WAP_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=11d87b484c623c771220001aa31705b5

#Response

Synchronous response sample

http://www.mikascoffee.com/return?currency=USD&out_trade_no=out_trade_no_20190826_204556&total_fee=0.01&trade_no=2019082622001336531050687821&trade_status=TRADE_FINISHED&sign=c2d0ad527e5937fdc8dd0f7dcc7f7ac2&sign_type=MD5

copy
http://www.mikascoffee.com/return
currency=USD
out_trade_no=out_trade_no_20190826_204556
total_fee=0.01
trade_no=2019082622001336531050687821
trade_status=TRADE_FINISHED
sign=c2d0ad527e5937fdc8dd0f7dcc7f7ac2
sign_type=MD5

Asynchronous response sample

http://www.mikascoffee.com/notify?notify_id=2019082600222214311036531048309837&notify_type=trade_status_sync&sign=69b24fbfdc570463897a15f75b321215&trade_no=2019082622001336531050687821&buyer_id=2088602333336535&total_fee=0.01&forex_rate=7.20211000&out_trade_no=out_trade_no_20190826_204556&rmb_fee=0.07&seller_id=2088021017666931&currency=USD&notify_time=2019-08-26 21%3A43%3A12&trade_status=TRADE_FINISHED&sign_type=MD5

copy
http://www.mikascoffee.com/notify
notify_id=2019082600222214311036531048309837
notify_type=trade_status_sync
sign=69b24fbfdc570463897a15f75b321215
trade_no=2019082622001336531050687821
buyer_id=2088602333336535
total_fee=0.01
forex_rate=7.20211000
out_trade_no=out_trade_no_20190826_204556
rmb_fee=0.07
seller_id=2088021017666931
currency=USD
notify_time=2019-08-26 21:43:12
trade_status=TRADE_FINISHED
sign_type=MD5