Place an Order

Create a pre-order transaction and make payment through the returned information.

Info

{domain}/Servlet/JSAPIService.do

https://vmp.eftpay.com.cn/VMP/Servlet/JSAPIService.do

Name	Type	Description
service	String	Interface name, see Supported service
user_confirm_key	String(12)	User Key, provided by eftPay
transaction_amount	String(8)	Amount. Requires digits, maximum decimal length is 2
out_trade_no	String(28)	Merchant order number
payType	String(6)	Payment type, see Supported payType
buyerType	String(7)	Device type `ios`，`android`，`others`
subject	String(256)	Transaction information
wallet	String(20)	Wallet type, see Supported wallet
body	String(128)	In the case of needing to describe various goods, it is recommended to accumulate the description of the goods
pay_scene	String	Payment scene, please pass `WEB` by default, see Supported pay_scene
fee_type	String(5)	Currency type, `HKD`，`CNY` Default：`HKD`
tid	String(20)	Merchant terminal number
notify_url	String(240)	Notification address, production environment only supports `80` and `443` ports, other ports need to apply
return_url	String(240)	The return address after payment is completed. Cannot carry parameters, production environment only supports `80` and `443` ports, other ports need to apply
active_time	String	Valid time, in seconds. Default 30 minutes, i.e. `1800`
lang	String	Language, fixed value：`cn`，`en`，`hk`，see Supported lang
customerInfo	Object	Customer information, valid when payment type is `ATOME`, see ATOME parameter description
shippingAddress	Object	Shipping address, valid when payment type is `ATOME`, see ATOME parameter description
billingAddress	Object	Billing address, valid when payment type is `ATOME`, see ATOME parameter description
items	Object[]	Detailed information about the order items, valid when payment type is `ATOME`, see ATOME parameter description
scheme	String	APP application scheme, useful when APP uses webview nested payment method. Valid when payment type is `UnionPay`
packageName	String	APP application package name, useful when APP uses webview nested payment method. Valid when payment type is `UnionPay`
app_link	String	APP link, return to APP after payment. Valid when wallet type is `BOCVMPUPI`
time	String	Time, format：`yyyyMMddHHmmss`
sign	String(64)	Signature

View the supported services and their corresponding payType and wallet

Below is the correspondence between service, payType and wallet

service	payType	wallet	Description
service.alipay.wap.PreOrder	`Alipay`	`ALIPAYCN` `ALIPAYHK`	Alipay wap interface
service.wechat.web.MobileH5	`WeChat`	`WECHATCN` `WECHATHK`	Non-WeChat mobile browser H5 interface
service.wechat.oauth2.Authorize	`WeChat`	`WECHATCN` `WECHATHK`	WeChat public H5 interface
service.icbc.wap.PreOrder	`ICBC`	`ICBCWAP`	ICBC wap interface
service.atome.v2.wap.PreOrder	`ATOME`	`ATOME`	ATOME online interface
service.unionpay.online.web.PreOrder	`UnionPay`	`UNIONPAY`	UnionPay online cashier interface
service.oct.online.PreOrder	`OCT`	`OCT`	Octopus online payment interface
service.fdms.web.PreOrder	`Fdms`	`FDMS`	FDMS's VISA, Master payment
service.mpgs.web.PreOrder	`Mpgs`	`MPGS`	MPGS's VISA, Master payment
service.ae.web.PreOrder	`AE`	`AE`	AE payment
service.jetco.wap.PreOrder	`Jetco`	`JETCOHK`	Jetco wap interface
service.payme.web.PreOrder	`PAYME`	`PAYME`	PayMe web payment interface
service.bocvmp.upi.wap.PreOrder	`BOCVMP`	`BOCVMPUPI`	BOCPay wap interface

View the supported services and their corresponding pay_scene

Please pass WEB by default. When using the following interfaces, pay attention to the corresponding payment scenarios

service	pay_scene
service.wechat.oauth2.Authorize	`WXWEB`
service.alipay.wap.PreOrder	`WAP`
service.jetco.wap.PreOrder	`WAP`
service.unionpay.online.web.PreOrder	`ONLINE_WEB`
service.payme.web.PreOrder	`WEB`/`APP`
service.bocvmp.upi.wap.PreOrder	`H5`/`APP`

Tips

When pay_scene= WEB , the PayMe web payment interface returns a QR code payment page link for PC.
When pay_scene= APP , the PayMe web payment interface returns a PayMe APP invocation link for mobile.
When pay_scene= H5 , the BOCPay wap interface will return a BOCPay APP launch link. After payment is completed, the default browser will open and redirect to the return_url.
When pay_scene= APP , the BOCPay wap interface will return a BOCPay APP launch link. After payment is completed, it will redirect to the app_link, and the parameters need to be verified by yourself.
For launching the BOCPay APP, refer to BOCPay Integration Guide v1.1.1

View the services that support lang

cn is Simplified Chinese, hk is Traditional Chinese, and en is English

service	lang
service.oct.online.PreOrder	`cn`，`en`，`hk`
service.mpgs.web.PreOrder	`cn`，`en`，`hk`
service.ae.web.PreOrder	`cn`，`en`，`hk`
service.jetco.wap.PreOrder	`cn`，`en`，`hk`

transaction_amount

In PAYME UAT environment, the transaction status can be controlled by the two decimal places of the transaction_amount

Decimal Places	Description	Example
81	Creates a [successful] transaction	transaction_amount=0.81
80	Creates a [timeout] transaction	transaction_amount=0.80
77	Creates a [failed] transaction	transaction_amount=0.77
44	Creates a [server error - no payment QR code]	transaction_amount=0.44
45	Creates a [server error - no state] transaction	transaction_amount=0.45

customerInfo

Name	Type	Description	Requirement
mobileNumber	String	Customer's mobile number in E.164 format. For example, the international format for Chinese phone numbers (mobile and landline) is +8610123456. +861xxxxxxxxxx
fullName	String	Customer's full name

Example

"customerInfo": {
	"mobileNumber": "+8613344445555",
	"fullName": "Atome Developer"
}

shippingAddress

Name	Type	Description
countryCode	String	Shipping address, two-digit country/region code in ISO-3611 format. For example, "SG" "HK" "MY" "ID" "TH" "TW" "VN" "PH"
lines	Array	Shipping address, address lines. For example, ["China", "Hong Kong", "Kowloon", ...]
postCode	String	Shipping address, postal code

Example

"shippingAddress": {
	"countryCode": "HK",
	"lines": ["China", "Hong Kong"],
	"postCode": "999077"
}

billingAddress

Name	Type	Description
countryCode	String	The country/region code of the delivery address in ISO-3611 format. For example, "SG" "HK" "MY" "ID" "TH" "TW" "VN" "PH"
lines	Array	The lines of the delivery address. For example, ["China", "Hong Kong", "Kowloon", ...]
postCode	String	The postal code of the delivery address

Example

"shippingAddress": {
	"countryCode": "HK",
	"lines": ["China", "Hong Kong"],
	"postCode": "999077"
}

items

Name	Type	Description
itemId	String	The ID of this product/SKU
name	String	The name of the item
quantity	Int	The quantity of the item
price	Int	The price of the item in cents

Example

"items": [{
	"itemId": "P100",
	"name": "iPhone 12 pro max",
	"price": 11020,
	"quantity": 1
}, {
	"itemId": "P101",
	"name": "iPhone SE case",
	"price": 1000,
	"quantity": 1
}]

The translation of the Chinese text in the document is as follows:

Name	Type	Description
return_status	String(3)	Return status code, represents . Note: This parameter cannot be used as a judgment of whether the transaction status is successful Other status codes see Appendix 3
return_char	String(100)	Return description, may change, cannot be used as a condition judgment
Return when return_status is greater than 00
time	String	Time, format: `yyyyMMddHHmmss` `return_status` >= `00` return
sign	String(64)	Signature `return_status` >= `00` return

Name	Type	Description
pay_apptrade	String	Transaction initiation information
user_confirm_key	String	User Key, provided by eftPay
out_trade_no	String(28)	Merchant order number
payType	String(6)	Payment type
buyerType	String(7)	Device type
wallet	String(20)	Wallet type
eft_trade_no	String(28)	Yifude order number
fee_type	String(5)	Currency
transaction_amount	String(8)	Transaction amount
tid	String(20)	Terminal number, returned when the consumption request is sent

{
	"pay_scene": "WAP",
	"user_confirm_key": "12345678",
	"wallet": "ALIPAYHK",
	"subject": "中文测试 test",
	"transaction_amount": "0.02",
	"sign": "af8f9f9d60019ce649af1ddfefd2aae98fa71656278a6edf439948cab7dc69d9",
	"body": "中文测试 test",
	"tid": "",
	"payType": "Alipay",
	"out_trade_no": "20190824010716",
	"service": "service.alipay.wap.PreOrder",
	"buyerType": "andriod",
	"return_url": "https://vmp.eftpay.com.cn/VMP/notify/testing",
	"time": "20190824010716"
}

{
	"user_confirm_key": "12345678",
	"wallet": "ALIPAYHK",
	"pay_apptrade": "https://vmp.eftpay.com.cn/VMP/wap/payPage?userkey=12345678&outTradeNo=20190824010716&sign=5c24f30f758d86e2ba1cc1a291aa6d392f563180584f071d2d725eff52947f05",
	"return_char": "",
	"transaction_amount": "0.02",
	"sign": "11c2d25ad95a8849a7598ca57b83731d0e2c2019710c7dd3feccbd8895d6d01c",
	"fee_type": "HKD",
	"tid": "",
	"eft_trade_no": "08520005269190824010701722",
	"out_trade_no": "20190824010716",
	"payType": "Alipay",
	"buyerType": "andriod",
	"return_status": "00",
	"time": "20190824010717"
}