Place an order

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

#

Info

{domain}/Servlet/JSAPIService.do

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

#

Name	Type	Description	Requirement
service	String	Interface name, see supported service
user_confirm_key	String(12)	User Key, provided by eftPay
transaction_amount	String(8)	Amount. Requires numbers, the maximum length of decimal places is 2 PAYME test amount parameter description
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 goods
pay_scene	String	Payment scene, please pass WEB by default, others 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. It cannot carry parameters. The production environment only supports 80 and 443 ports, other ports need to apply. servie is not required for Alipay/WeChat online QR code interface
active_time	String	Valid time, in seconds. Default is 30 minutes, that is, 1800
lang	String	Language, fixed value：cn，en，hk，see service that supports lang
customerInfo	Object	Customer information, valid when payment type is ATOME, see ATOME parameter description
shippingAddress	Object	Delivery 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. Valid when payment type is UnionPay/PAYME
packageName	String	APP application package name, useful when APP uses webview nested payment. Valid when payment type is UnionPay
time	String	Time, format：yyyyMMddHHmmss
sign	String(64)	Signature

#

View supported services and their corresponding payType and wallet

Here is the mapping between service, payType, and wallet

service	payType	wallet	Description
service.alipay.web.PreOrder	Alipay	ALIPAYCN ALIPAYHK	Alipay web interface
service.alipay.wap.PreOrder	Alipay	ALIPAYCN ALIPAYHK	Alipay wap interface
service.alipay.web.QRCode	Alipay	ALIPAYCN ALIPAYHK	Alipay online QR code interface
service.wechat.web.PreOrder	WeChat	WECHATCN WECHATHK	WeChat web interface
service.wechat.web.MobileH5	WeChat	WECHATCN WECHATHK	WeChat H5 interface for non-WeChat mobile browsers
service.wechat.oauth2.Authorize	WeChat	WECHATCN WECHATHK	WeChat H5 interface for WeChat official accounts
service.wechat.web.QRCode	WeChat	WECHATCN WECHATHK	WeChat online QR code 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 cash register interface
service.oct.online.PreOrder	OCT	OCT	Octopus online payment interface
service.fdms.web.PreOrder	Fdms	FDMS	FDMS VISA, Master payment
service.mpgs.web.PreOrder	Mpgs	MPGS	MPGS VISA, Master payment
service.ae.web.PreOrder	AE	AE	AE payment
service.nuvei.web.PreOrder	NUVEI	NUVEI	NUVEI VISA, Master payment
service.jetco.wap.PreOrder	Jetco	JETCOHK	Jetco wap interface
service.payme.web.PreOrder	PAYME	PAYME	PayMe web payment interface
service.fps.web.PreOrder	FPS	FPS	FPS web payment interface
service.bocvmp.unionpay.web.PreOrder	BOCVMP	BOCVMPUPW	BOC web payment interface

Tips

• Alipay online QR code interface returns a QR code URL that can be embedded into the merchant's page. This interface does not require the return_url parameter.
• WeChat online QR code interface returns a QR code text that can be used to generate a QR code and then displayed on the merchant's page. This interface does not require the return_url parameter.
• Refund interface is not supported for FPS.
• NUVEI unable to control the active_time parameter, set default to 600 through configuration.

View supported services and their corresponding pay_scene

Please pass WEB as the default value. When using the following interfaces, pay attention to the corresponding payment scene

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

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.

View supported languages for service

cn for Simplified Chinese, hk for Traditional Chinese, en for English

service	lang
service.alipay.web.PreOrder	cn，en，hk
service.wechat.web.PreOrder	cn，en，hk
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
service.fps.web.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	The 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	The customer's full name

Example

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

shippingAddress

Name	Type	Description	Requirement
countryCode	String	The country/region code in ISO-3611 format for the shipping address. For example, "SG" for Singapore, "HK" for Hong Kong, "MY" for Malaysia, "ID" for Indonesia, "TH" for Thailand, "TW" for Taiwan, "VN" for Vietnam, "PH" for Philippines.
lines	Array	The address lines for the shipping address. For example, ["China", "Hong Kong", "Kowloon", ...]
postCode	String	The postal code for the shipping address

Example

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

billingAddress

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

Example

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

items

Name	Type	Description	Requirement
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
}]

#

Name	Type	Description	Requirement
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, which may change and 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	Requirement
pay_apptrade	String	Transaction initiation information, return a link for direct access, call the corresponding payment cashier or jump to the corresponding payment page (WeChat WEB only supports access to the payment page)
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)	eftPay order number
fee_type	String(5)	Currency
transaction_amount	String(8)	Transaction amount
tid	String(20)	Terminal number, return when the consumption request is sent

#

{
    "service": "service.wechat.web.PreOrder",
    "user_confirm_key": "S0003469",
    "payType": "WeChat",
    "wallet": "WECHATCN",
    "pay_scene": "WEB",
    "transaction_amount": "0.53",
    "out_trade_no": "rrn_1686280005998",
    "subject": "test",
    "body": "test",
    "time": "20230609110645",
    "sign": "9878e9445e4e138e5fed29f36eea229767d6263678ea4aa5e48d1b53aacbcff8",
    "tid": "",
    "buyerType": "others",
    "fee_type": "HKD",
    "notify_url": "https://www.merchant.com/notify/receive",
    "return_url": "https://www.merchant.com/return/page"
}

#

{
    "user_confirm_key": "S0003469",
    "return_status": "00",
    "return_char": "",
    "wallet": "ALIPAYHK",
    "pay_apptrade": "https://vmp.eftpay.com.cn/VMP/web/payPage?userkey=12345678&outTradeNo=20190824010716&sign=5c24f30f758d86e2ba1cc1a291aa6d392f563180584f071d2d725eff52947f05",
    "subject": "test测试",
    "transaction_amount": "0.04",
    "eft_trade_no": "08520005269190824010701722",
    "sign": "26c89dd6684dd6f60569a502c920793ca82bb39f86fe0250bdb2256db8100d11",
    "fee_type": "HKD",
    "tid": "tid_3378",
    "buyerType": "andriod",
    "out_trade_no": "rrn_1686280006002",
    "time": "20230609110646",
    "payType": "Alipay"
}

#

service.wechat.web.PreOrder

WeChat Web payment page

service.mpgs.web.PreOrder

MPGS payment page

service.unionpay.online.web.PreOrder

UPOP payment page

service.bocvmp.unionpay.web.PreOrder

BOCVMPUPW payment page