Payment

Unified order

The merchant business system initiates payment and collection orders through the unified order placement interface. The easylink payment gateway will route the payment channel according to the payment channel configured by the merchant to complete the payment order placement. The payment gateway returns the corresponding payment parameters according to different ways of payment, and the business system uses the payment parameters to initiate collection.

Interface description

Request URL: /api/pay/unifiedOrder

Request method: POST

Request type: application/json or application/x-www-form-urlencoded

Request parameters

Field name	Variable name	Required	Type	Example value	Description
Merchant No.	mchNo	Yes	String(30)	M1621873433953	Merchant No.
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Merchant order No	mchOrderNo	Yes	String(30)	20160427210604000490	Order No. generated by the merchant
Way of payment	wayCode	Yes	String(30)	WX_LITE	Way of payment, such as WeChat mini program WX_LITE
Amount of payment	amount	Yes	int	100	Amoun of payment (unit: cents)
Currency code	currency	Yes	String(3)	HKD	Three-digit currency code: HKD
Client IP	clientIp	No	String(32)	210.73.10.148	Client IPV4 address
Product title	subject	Yes	String(64)	Product title test	Product title
Product description	body	Yes	String(256)	Product description test	Product description
Notify URL	notifyUrl	No	String(128)	https://www.gnete.com.hk/notify.htm	Asynchronous callback URL for payment result. A callback will only be initiated if this value is input
Return URL	returnUrl	No	String(128)	https://www.gnete.com.hk/return.htm	Synchronous jump notification URL for payment result
Expired time	expiredTime	No	int	3600	Expired time of order (unit: seconds, 2 hours by default). The order will expire after (created time + expired time)
Channel parameter	channelExtra	No	String(256	{"auth_code", "13920933111042"}	Extra parameter initiated by a specific channel, in json format string. For details, see the channel parameter description
Extended parameter	extParam	No	String(512)	134586944573118714	Merchant extended parameter. It will be returned as it is during callback
Request time	reqTime	Yes	long	1622016572190	Request interface time, 13-digit timestamp
Interface version	version	Yes	String(3)	1.0	Interface version No., fixed: 1.0
Signature	sign	Yes	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature value. For details, see the signature algorithm
Signature type	signType	Yes	String(32)	MD5	Signature type. Currently, only MD5 is supported

Request example data

{
  "amount": 8,
  "extParam": "",
  "mchOrderNo": "mho1624005107281",
  "subject": "Product title",
  "wayCode": "WX_H5",
  "sign": "84F606FA25A6EC4783BECC08D4FDC681",
  "reqTime": "1624005107",
  "body": "Product description",
  "version": "1.0",
  "channelExtra": "{\"authCode\":\"280812820366966512\"}",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "clientIp": "192.166.1.132",
  "notifyUrl": "https://www.gnete.com.hk/notify.html",
  "signType": "MD5",
  "currency": "HKD",
  "returnUrl": "",
  "mchNo": "M1623984572"
}

Return parameters

Field name	Variable name	Required	Type	Example value	Description
Return status	code	Yes	int	0	0- Successful processing. Others - Processing error. For details, see the error code
Return message	msg	No	String(128)	Signature failed	Specific cause of error, for example, signature failed or parameter format verification error
Signature message	sign	No	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	Data signature. If data is empty, it will not be returned
Return data	data	No	String(512)	{}	Return the order placement data, in JSON format

Data format

Field name	Variable name	Required	Type	Example value	Example value
Payment order No.	payOrderId	Yes	String(30)	U12021022311124442600	Return the payment system order No.
Merchant order No.	mchOrderNo	Yes	String(30)	20160427210604000490	Return the order No. input by the merchant
Order status	orderState	Yes	int	2	Payment order status 0-Order generated 1-Payment in progress 2-Payment success 3-Payment failure 4-Cancelled 5-Refunded 6-Order closed
Payment data type	payDataType	Yes	String	payUrl	Payment parameter type `payUrl` - Way to jump link `form` - Form mode `wxapp` - WeChat payment parameters (for WeChat official accounts, mini programs, and app payments ( 1、SDK download URL： IOS：https://developers.weixin.qq.com/doc/oplatform/Downloads/iOS_Resource.html Android：https://developers.weixin.qq.com/doc/oplatform/Downloads/Android_Resource.html 2、SDK access guide： IOS：https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Access_Guide/iOS.html Android：https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Access_Guide/Android.html)) `aliapp` - Alipay app payment parameters ( 1、SDK download URL：https://docs.alipay.hk/alipayhkdocs/hk/app_hk/download 2、SDK document URL：https://global.alipay.com/docs/ac/hkapi/securitypay_pay#WLtXX) `ysfapp` - YSF app payment parameters `codeUrl` - QR code URL `codeImgUrl` - QR code image URL `none` - Empty payment parameter
Payment data	payData	No	String	http://www.gnete.com.hk/pay.html	Payment parameters used for initiating payment, such as for WeChat official account payment
Channel error code	errCode	No	String	ACQ.PAYMENT_AUTH_CODE_INVALID	Error code returned by upstream channel
Channel error description	errMsg	No	String	Business Failed	Error description returned by upstream channel

Response example data

{
  "code": 0,
  "data": {
    "errCode": "ACQ.PAYMENT_AUTH_CODE_INVALID",
    "errMsg": "Business Failed [Payment failed. Failed to obtain customer account information. Please ask the customer to refresh the payment code and collect the payment again. If the collection fails again, please contact the administrator for processing.[SOUNDWAVE_PARSER_FAIL]]",
    "mchOrderNo": "mho1624005752661",
    "orderState": 3,
    "payOrderId": "P202106181642329900002"
  },
  "msg": "SUCCESS",
  "sign": "F4DA202C516D1F33A12F1E547C5004FD"
}

{
  "code": 0,
  "data": {
    "mchOrderNo": "test-mho20240920000007",
    "orderState": 1,
    "payOrderId": "P1836962928310382593",
    "payDataType": "codeImgUrl",
    "payData": "https://ts-api-pay.gnete.com.hk/api/scan/imgs/ac755a50c32d42a7b32f1e854568bdd0104e2ec22fb915cccef3c7c9e7032364e6b24f838537eb38ab6f7b90072b63fa2edf2431e52cdb40c45e68976cc5c15dd9cd262fde7a1c88d4178d2d4f9b1c63cd4598a7b73734bbd72db7d0a23c90e8.png"
  },
  "msg": "SUCCESS",
  "sign": "F1EB2047E9256859A3F8E0372F328217"
}

{
  "code": 0,
  "data": {
    "mchOrderNo": "test-mho20240920000008",
    "orderState": 1,
    "payData": "secondary_merchant_industry=5977&payment_inst=ALIPAYHK&_input_charset=UTF-8&subject=%E9%A6%99%E6%B8%AFAPP%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7&refer_url=https%3A%2F%2Fiqr-test.chinaums.com&sign=S8UVmAI5ILCsRd4zVqraFEqraxR9R1m6ySMY9yEIm8oQKU6wLl8kzLt%2F%2FaJ1iSzR6oYtN7v41rxLV1sgcqa2nGHgn39mK0mVHRDwByVs9ZLaOrNcCxNfolzfmh3ebf0XiZGFd5oeauBau0cZjhcMjmQaMAnSC6pVWIWrOOzbD7ZDmPoZFU6HrJMJy%2FO%2FGf5o96HzskhDQfpHAu94lfZMRPyWrOwyCpjrUi2v5eN6DNAiyzs2jlwRxiuZJm2jnX5IVURdaWkFIFem6%2BFMgPdU7cXXTo5wSlVXF8t3tNgl70pLDtvHdbEmO2Pd6LbuOuDdqaTIpNkS9PIPCTt%2BbzeNQA%3D%3D&it_b_pay=30m&notify_url=https%3A%2F%2Fiqr-test.chinaums.com%2Finetpay-portal%2Fali%2F2024092000007314337921233579%2Fc086f913dad04f8d833864ff90a6aa82%2Fnotify.do&body=%E9%A6%99%E6%B8%AFAPP%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7&product_code=NEW_WAP_OVERSEAS_SELLER&secondary_merchant_id=mid001&payment_type=1&out_trade_no=2024092000007314337921233579&trans_currency=HKD&partner=2088741022806721&service=mobile.securitypay.pay&trade_information=%7B%22other_business_type%22%3A%22%E9%A6%99%E6%B8%AFAPP%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7%22%2C%22business_type%22%3A5%7D&total_fee=0.02&secondary_merchant_name=%E9%A6%99%E6%B8%AFAPP%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7&currency=HKD&sign_type=RSA2&seller_id=2088741022806721&forex_biz=FP&timestamp=1726803339743",
    "payDataType": "payInfo",
    "payOrderId": "P1836970923073236993"
  },
  "msg": "SUCCESS",
  "sign": "81DAF4D7CF3A5B2F4AB65D8AAD20BA09"
}

{
  "code": 0,
  "data": {
    "mchOrderNo": "test-mho20240920000009",
    "orderState": 1,
    "payData": "https://ts-api-pay.gnete.com.hk/api/unionpay/upop/cashier?orderId=P1836971522141483010&mchOrderId=test-mho20240920000009",
    "payDataType": "payurl",
    "payOrderId": "P1836971522141483010"
  },
  "msg": "SUCCESS",
  "sign": "3ED0B97A15186A892ED56349C9C06E96"
}

Way of payment

WayCode	Way of payment
ALI_JSAPI	Alipay Life Account
ALI_APP	Alipay APP
ALI_H5	Alipay H5
ALI_QR	Alipay Scan (Main)
WX_JSAPI	WeChat Official Account
WX_LITE	WeChat Mini Program
WX_APP	WeChat APP
WX_H5	WeChat H5
WX_QR	WeChat Scan (Main)
UP_OP	UnionPay Online Payment
UP_EXPRESS	UnionPay Express Payment
UP_APP	UnionPay APP
YSF_QR	YSF Scan (Main)
NUVEI_H5	NUVEI H5 (Visa, Master)

channelExtra parameter description

When wayCode=WX_JSAPI or wayCode=WX_LITE, channelExtra must be subAppid or openid. The example data of channelExtra is as follows:

{"subAppid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI", "openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}

When wayCode=WX_H5 or wayCode=WX_APP, channelExtra can be subAppid. The example data of channelExtra is as follows:

{"appid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}

When wayCode=ALI_H5，channelExtra can be walletType. Set the wallet type. At this time, walletType can be: CN-Chinese Mainland wallet,HK-Hong Kong Wallet，If walletType is not input,HK is returned by default, The example data of channelExtra is as follows:

{"walletType": "CN"}

When wayCode=ALI_QR or wayCode=WX_QR or wayCode=YSF_QR, channelExtra can be payDataType. Set the returned payment data type. At this time, payDataType can be: codeUrl-QR code URL,codeImgUrl-QR code image URL. If payDataType is not input, codeUrl type is returned by default. The example data of channelExtra is as follows:

{"payDataType": "codeImgUrl"}

When wayCode=UP_OP or wayCode=UP_APP, channelExtra can be accNo. Lock the transaction of bank card number. The example data of channelExtra is as follows:

{"accNo": "6250******0016"}

When wayCode=UP_EXPRESS, channelExtra can be customerInfo. Input the cardholder verification information. The example data of channelExtra is as follows:

{"customerInfo": "aN89IpTVcF7EoN9aBbDwjc1BN0nFrcz22trbqalSn4YJzCW3muyO70gIRX9KUblQP57bIJ+/Cg+VacE0r2l82ghRQfAGQTaO3K+Dzj3t97k7p4cl8QtdvbzQBAqIS3O905PMmDsezZmm1Ag5HEjCjfzZke1TZmieof2uRzIO0DD4yWOZu0Qx3VePGt+yrPihwlaK/raXYjKuXSA38sWrKg98B3e7Ie/cilDgYwxvXlRAjABO+ecJq844Kc7v7Dnus7FC0cwu+OLnGT4BJTsXa5ywl4IbUvrvsKBvvxAfMDwkDwgio1+hPORVyDSUpOd/9XSXC9spu+GhkBbWQgXlfA=="}

customerInfo generation rules：RSA({"accNo":"6250******0016","expired":"2412","cvn2":"123"})。accNo：bank card number，expired：expired YYMM，cvn2：3 digit CVN2

Order query

Merchants query orders through this interface. The payment gateway will return the latest data of the order.

Interface description

Request URL：/api/pay/query

Request method：POST

Request type：application/json or application/x-www-form-urlencoded

Request parameters

Field name	Variable name	Required	Type	Example value	Description
Merchant No.	mchNo	Yes	String(30)	M1621873433953	Merchant No.
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Payment order No.	payOrderId	Yes	String(30)	P20160427210604000490	Input either the order No. generated in the payment center or mchOrderNo
Merchant order No.	mchOrderNo	Yes	String(30)	20160427210604000490	Input either the order No. generated by the merchant or payOrderId
Request time	reqTime	Yes	long	1622016572190	Request interface time, 13-digit timestamp
Interface version	version	Yes	String(3)	1.0	Interface version No., fixed: 1.0
Signature	sign	Yes	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature value. For details, see the signature algorithm
Signature type	signType	Yes	String(32)	MD5	Signature type. Currently, only MD5 is supported

Request example data

{
  "payOrderId": "P202106181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}

Field name	Variable name	Required	Type	Example value	Description
Return status	code	Yes	int	0	0- Successful processing. Others - Processing error. For details, see the error code
Return message	msg	No	String(128)	Signature failed	Specific cause of error, for example, signature failed or parameter format verification error
Signature message	sign	No	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	Data signature. If data is empty, it will not be returned
Return data	data	No	String(512)	{}	Return the order placement data, in json format

Data format

Field name	Variable name	Required	Type	Example value	Description
Payment order No.	payOrderId	Yes	String(30)	P12021022311124442600	Return the payment system order No.
Merchant No.	mchNo	Yes	String(30)	M1621873433953	Merchant No.
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Merchant order No.	mchOrderNo	Yes	String(30)	20160427210604000490	Return the order No. input by the merchant
Payment interface	ifCode	Yes	String(30)	wxpay	Payment interface code
Way of payment	wayCode	Yes	String(30)	WX_LITE	Way of payment, such as WeChat mini program WX_LITE
Amount of payment	amount	Yes	int	100	Amoun of payment (unit: cents)
Currency code	currency	Yes	String(3)	HKD	Three-digit currency code: HKD
Order status	state	Yes	int	2	Payment order status 0-Order generated 1-Payment in progress 2-Payment success 3-Payment failure 4-Cancelled 5-Refunded 6-Order closure
Client IP	clientIp	No	String(32)	210.73.10.148	Client IPV4 address
Product title	subject	Yes	String(64)	Product title test	Product title
Product description	body	Yes	String(256)	Product description test	Product description
Channel order No.	channelOrderNo	No	String	20160427210604000490	Order No. of corresponding channel
Channel error code	errCode	No	String	1002	Error code returned by the channel when placing an order
Channel error description	errMsg	No	String	Business exception error	Error description returned by the channel when placing an order
Extended parameter	extParam	No	String(512)	134586944573118714	Merchant extended parameter. It will be returned as it is during callback
Created time	createdAt	Yes	long	1622016572190	Order creation time, 13-digit timestamp
Success time	successTime	No	long	1622016572190	Order payment success time, 13-digit timestamp

Response example data

{
  "code": 0,
  "data": {
    "amount": 58,
    "appId": "60cc09bce4b0f1c0b83761c9",
    "body": "Product description",
    "channelOrderNo": "2021061822001423031419593035",
    "clientIp": "192.166.1.132",
    "createdAt": 1623985457705,
    "currency": "HKD",
    "extParam": "",
    "ifCode": "alipay",
    "mchNo": "M1623984572",
    "mchOrderNo": "mho1623985457320",
    "payOrderId": "P202106181104177050002",
    "state": 2,
    "subject": "Product title",
    "successTime": 1623985459000,
    "wayCode": "WX_H5"
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

Order closure

Merchants close orders through this interface. The payment gateway will complete the closing process for the orders.

Interface description

Request URL：/api/pay/close

Request method：POST

Request type：application/json or application/x-www-form-urlencoded

Request parameters

Field name	Variable name	Required	Type	Example value	Description
Merchant No.	mchNo	Yes	String(30)	M1621873433953	Merchant No.
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Payment order No.	payOrderId	Yes	String(30)	P20160427210604000490	Input either the order No. generated in the payment center or mchOrderNo
Merchant order No.	mchOrderNo	Yes	String(30)	20160427210604000490	Input either the order No. generated by the merchant or payOrderId
Request time	reqTime	Yes	long	1622016572190	Request interface time, 13-digit timestamp
Interface version	version	Yes	String(3)	1.0	Interface version No., fixed: 1.0
Signature	sign	Yes	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature value. For details, see the signature algorithm
Signature type	signType	Yes	String(32)	MD5	Signature type. Currently, only MD5 is supported

Request example data

{
  "payOrderId": "P202106181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}

Field name	Vairable name	Required	Type	Example value	Description
Return status	code	Yes	int	0	0- Successful processing. Others - Processing error. For details, see the error code
Return message	msg	No	String(128)	Signature failed	Specific cause of error, for example, signature failed or parameter format verification error
Signature message	sign	No	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	Data signature. If data is empty, it will not be returned
Return data	data	No	String(512)	{}	Return the order placement data, in json format

Data format

Field name	Vairable name	Required	Type	Example value	Description
Channel error code	errCode	No	String	1002	Error code returned by the channel when closing an order
Channel error description	errMsg	No	String	Closure exception	Error description returned by the channel when closing an order

Response example data

{
  "code": 0,
  "data": {
    "errCode": "",
    "errMsg": ""
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

Payment notification

When the order is successfully paid, the payment gateway will send a callback notification to the merchant system. If the merchant system does not return correctly, the payment gateway will delay and send the notification again.

Interface description

Request URL：This link is set through the parameter notifyUrl submitted by the unified order placement interface. If the link cannot be accessed, the merchant system will not be able to receive notifications from the payment center.

Request method：POST

Request type：application/x-www-form-urlencoded

Notification parameters

Field name	Variable name	Required	Type	Example value	Description
Payment order No.	payOrderId	Yes	String(30)	P12021022311124442600	Return the payment system order No.
Merchant No.	mchNo	Yes	String(30)	M1621873433953	Merchant No.
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Merchant order No.	mchOrderNo	Yes	String(30)	20160427210604000490	Return the order No. input by the merchant
Payment interface	ifCode	Yes	String(30)	wxpay	Payment interface code
Way of payment	wayCode	Yes	String(30)	WX_LITE	Way of payment, such as WeChat mini program WX_LITE
Amount of payment	amount	Yes	int	100	Amoun of payment (unit: cents)
Currency code	currency	Yes	String(3)	HKD	Three-digit currency code: HKD
Order status	state	Yes	int	2	Payment order status 0-Order generated 1-Payment in progress 2-Payment success 3-Payment failure 4-Cancelled 5-Refunded 6-Order closure
Client IP	clientIp	No	String(32)	210.73.10.148	Client IPV4 address
Product title	subject	Yes	String(64)	Product title test	Product title
Product description	body	Yes	String(256)	Product description test	Product description
Channel order No.	channelOrderNo	No	String	20160427210604000490	Order No. of corresponding channel
Channel error code	errCode	No	String	1002	Error code returned by the channel when placing an order
Channel error description	errMsg	No	String	134586944573118714	Error description returned by the channel when placing an order
Extended parameter	extParam	No	String(512)	134586944573118714	Merchant extended parameter
Created time	createdAt	Yes	long	1622016572190	Order creation time, 13-digit timestamp
Success time	successTime	No	long	1622016572190	Order payment success time, 13-digit timestamp
Notification request time	reqTime	Yes	long	1622016572190	Notification request time, 13-digit timestamp
Signature	sign	Yes	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature value. For details, see the signature algorithm

Return result

After being processed by the business system, it is synchronously returned to the payment center. Returning the string "success" indicates success. Returning anything other than "success" indicates processing failure. The payment center will notify the business system again. (The notification frequency is 0/30/60/90/120/150s)

Note: The returned string is case-insensitive and there cannot be spaces or line breaks before or after the string.

Notification example data

{
  "amount": 5,
  "body": "Product description",
  "clientIp": "192.166.1.132",
  "createdAt": "1622016572190",
  "currency": "HKD",
  "extParam": "",
  "ifCode": "wxpay",
  "mchNo": "M1621873433953",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "mchOrderNo": "mho1621934803068",
  "payOrderId": "20210525172643357010",
  "state": 3,
  "subject": "Product title",
  "wayCode": "WX_H5",
  "sign": "C380BEC2BFD727A4B6845133519F3AD6"
}