Payment
Unified Order
The merchant business system initiates a payment collection order through the unified order interface, and the easylink payment gateway will route the payment through the configured payment channel. The payment gateway returns the corresponding payment parameters based on the different payment methods, which the business system uses to initiate the 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 Number | mchNo | Yes | String(30) | M1621873433953 | Merchant number |
App ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | App ID |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Merchant generated order number |
Payment Method | wayCode | Yes | String(30) | WX_LITE | Payment method, e.g., WeChat Mini Program WX_LITE |
Payment Amount | amount | Yes | int | 100 | Payment amount, in cents |
Currency Code | currency | Yes | String(3) | HKD | Three-letter currency code, HKD for Hong Kong Dollar |
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 |
Asynchronous Notification URL | notifyUrl | No | String(128) | https://www.gnete.com.hk/notify.htm | Asynchronous callback URL for payment results; callback will be initiated only if this value is provided |
Synchronous Redirect URL | returnUrl | No | String(128) | https://www.gnete.com.hk/return.htm | URL for synchronous redirect notification of payment results |
Expiry Time | expiredTime | No | int | 3600 | Order expiry time, in seconds, default is 2 hours. The order expires after (creation time + expiry time) |
Channel Parameters | channelExtra | No | String(256) | {"auth_code", "13920933111042"} | Additional parameters for specific channels, in JSON format string. Refer to channel parameter description |
Extension Parameters | extParam | No | String(512) | 134586944573118714 | Merchant extension parameters, returned as is during callback |
Request Time | reqTime | Yes | long | 1622016572190 | Request time in milliseconds timestamp |
API Version | version | Yes | String(3) | 1.0 | API version number, fixed: 1.0 |
Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, refer to 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"
}
Response Parameters
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Return Status | code | Yes | int | 0 | 0 - Success, other - Error, see error codes |
Return Message | msg | No | String(128) | Signature Failed | Specific error reason, e.g., Signature failed, parameter format check error |
Signature Information | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Signature of data inside, if data is empty, this will not be returned |
Return Data | data | No | String(512) | {} | Returned order data, in JSON format |
data Data Format
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Payment Order Number | payOrderId | Yes | String(30) | U12021022311124442600 | Returned payment system order number |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Returned merchant's order number |
Order Status | orderState | Yes | int | 2 | Payment order status 0 - Order created 1 - Payment in progress 2 - Payment successful 3 - Payment failed 4 - Revoked 5 - Refunded 6 - Order closed |
Payment Data Type | payDataType | Yes | String | payUrl | Payment parameter type payUrl - Redirect URL form - Form method wxapp - WeChat payment parameters (public account, mini program, app payment) aliapp - Alipay app payment parameters ysfapp - Cloud Flash payment app parameters codeUrl - QR code URL codeImgUrl - QR code image URL none - No payment parameters |
Payment Data | payData | No | String | http://www.gnete.com.hk/pay.html | Payment parameters used to initiate payment, if applicable for WeChat public account payment, etc. |
Channel Error Code | errCode | No | String | ACQ.PAYMENT_AUTH_CODE_INVALID | Error code returned by the upstream channel |
Channel Error Description | errMsg | No | String | Business Failed 失败 | Error description returned by the 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 refresh the payment code and try again. If payment fails again, please contact the administrator. [SOUNDWAVE_PARSER_FAIL]】",
"mchOrderNo": "mho1624005752661",
"orderState": 3,
"payOrderId": "P202106181642329900002"
},
"msg": "SUCCESS",
"sign": "F4DA202C516D1F33A12F1E547C5004FD"
}
Payment Methods
WayCode | Payment Method |
---|---|
ALI_JSAPI | Alipay Lifestyle Account |
ALI_APP | Alipay APP |
ALI_H5 | Alipay H5 |
ALI_QR | Alipay QR Code (Scan as Merchant) |
WX_JSAPI | WeChat Official Account |
WX_LITE | WeChat Mini Program |
WX_APP | WeChat APP |
WX_H5 | WeChat H5 |
WX_QR | WeChat QR Code (Scan as Merchant) |
UP_OP | UnionPay Online Payment |
UP_APP | UnionPay APP |
YSF_QR | UnionPay QR Code (Scan as Merchant) |
NUVEI_H5 | NUVEI H5 |
channelExtra Parameter Description
When wayCode=WX_JSAPI
or wayCode=WX_LITE
, channelExtra
must include subAppid
and openid
. Example data for channelExtra
:
{"subAppid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI", "openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}
When wayCode=WX_H5
or wayCode=WX_APP
, channelExtra
can include subAppid
. Example data for channelExtra
:
{"appid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}
When wayCode=ALI_QR
, wayCode=WX_QR
, or wayCode=YSF_QR
, channelExtra
can include payDataType
to set the type of payment data returned. The payDataType
can be: codeUrl
for QR code URL, codeImgUrl
for QR code image URL. If payDataType
is not provided, it defaults to codeUrl
. Example data for channelExtra
:
{"payDataType": "codeImgUrl"}
When wayCode=UP_OP
or wayCode=UP_APP
, channelExtra
can include accNo
to lock the bank card number for the transaction. Example data for channelExtra
:
{"accNo": "6222222222222222"}
Query Order
Merchants can use this interface to query an order, and 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 Number | mchNo | Yes | String(30) | M1621873433953 | Merchant number |
Application ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | Application ID |
Payment Order Number | payOrderId | Yes | String(30) | P20160427210604000490 | Order number generated by the payment center, either payOrderId or mchOrderNo should be provided |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Order number generated by the merchant, either payOrderId or mchOrderNo should be provided |
Request Time | reqTime | Yes | long | 1622016572190 | Request time, 13-digit timestamp |
Interface Version | version | Yes | String(3) | 1.0 | Interface version number, fixed: 1.0 |
Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see signature algorithm for details |
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 - Processing successful, other - Processing error, see error codes for details |
Return Message | msg | No | String(128) | Signature failure | Specific error reason, e.g., signature failure, parameter format validation error |
Signature Information | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Signature for the data inside, not returned if data is empty |
Return Data | data | No | String(512) | {} | Returned order data, in JSON format |
Data Format
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Payment Order Number | payOrderId | Yes | String(30) | P12021022311124442600 | Returned payment system order number |
Merchant Number | mchNo | Yes | String(30) | M1621873433953 | Merchant number |
Application ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | Application ID |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Returned merchant-provided order number |
Payment Interface | ifCode | Yes | String(30) | wxpay | Payment interface code |
Payment Method | wayCode | Yes | String(30) | WX_LITE | Payment method, e.g., WeChat Mini Program WX_LITE |
Payment Amount | amount | Yes | int | 100 | Payment amount, in cents |
Currency Code | currency | Yes | String(3) | HKD | Three-letter currency code, HKD for Hong Kong Dollar |
Order Status | state | Yes | int | 2 | Payment order status 0 - Order Created 1 - Payment in Progress 2 - Payment Successful 3 - Payment Failed 4 - Revoked 5 - Refunded 6 - Order Closed |
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 Number | channelOrderNo | No | String | 20160427210604000490 | Order number corresponding to the channel |
Channel Error Code | errCode | No | String | 1002 | Error code returned by the channel |
Channel Error Description | errMsg | No | String | Business Exception Error | Error description returned by the channel |
Extension Parameters | extParam | No | String(512) | 134586944573118714 | Merchant extension parameters, returned as-is in callbacks |
Creation Time | createdAt | Yes | long | 1622016572190 | Order creation time, 13-digit timestamp |
Success Time | successTime | No | long | 1622016572190 | Order payment success time, 13-digit timestamp |
Return 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"
}
Close Order
Merchants can use this interface to close an order. The payment gateway will handle the order closure.
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 Number | mchNo | Yes | String(30) | M1621873433953 | Merchant number |
Application ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | Application ID |
Payment Order Number | payOrderId | Yes | String(30) | P20160427210604000490 | Payment center generated order number, either this or mchOrderNo should be provided |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Merchant generated order number, either this or payOrderId should be provided |
Request Time | reqTime | Yes | long | 1622016572190 | Request interface time, 13-digit timestamp |
Interface Version | version | Yes | String(3) | 1.0 | Interface version number, fixed: 1.0 |
Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see signature algorithm for details |
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 - Success, other values indicate errors, see error codes for details |
Return Message | msg | No | String(128) | Signature failure | Specific error reason, e.g., signature failure, parameter format validation error |
Signature Information | sign | No | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | Signature of the data inside, if data is empty, signature is not returned |
Return Data | data | No | String(512) | {} | Returned order data, JSON format |
data Data Format
Field Name | Variable Name | Required | Type | Example Value | Description |
---|---|---|---|---|---|
Channel Error Code | errCode | No | String | 1002 | Channel close return error code |
Channel Error Description | errMsg | No | String | Close exception | Channel close return error description |
Return Example Data
{
"code": 0,
"data": {
"errCode": "",
"errMsg": ""
},
"msg": "SUCCESS",
"sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}
Payment Notification
When an order payment is successful, the payment gateway will send a callback notification to the merchant's system. If the merchant's system does not respond correctly, the payment gateway will delay and retry the notification.
Interface Description
Request URL: This link is set through the notifyUrl
parameter submitted via the unified order interface. If the link is inaccessible, the merchant's system will not 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 ID | payOrderId | Yes | String(30) | P12021022311124442600 | Payment system order number |
Merchant Number | mchNo | Yes | String(30) | M1621873433953 | Merchant number |
Application ID | appId | Yes | String(24) | 60cc09bce4b0f1c0b83761c9 | Application ID |
Merchant Order Number | mchOrderNo | Yes | String(30) | 20160427210604000490 | Merchant's order number |
Payment Interface | ifCode | Yes | String(30) | wxpay | Payment interface code |
Payment Method | wayCode | Yes | String(30) | WX_LITE | Payment method, WeChat Mini Program WX_LITE |
Payment Amount | amount | Yes | int | 100 | Payment amount, in cents |
Currency Code | currency | Yes | String(3) | HKD | Three-letter currency code, Hong Kong Dollar: HKD |
Order Status | state | Yes | int | 2 | Payment order status 0-Order Created 1-Payment In Progress 2-Payment Successful 3-Payment Failed 4-Canceled 5-Refunded 6-Order Closed |
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 Number | channelOrderNo | No | String | 20160427210604000490 | Order number in the corresponding channel |
Channel Error Code | errCode | No | String | 1002 | Error code returned by the channel |
Channel Error Description | errMsg | No | String | 134586944573118714 | Error description returned by the channel |
Extended Parameters | extParam | No | String(512) | 134586944573118714 | Merchant's extended parameters |
Creation 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, refer to the signature algorithm |
Response Result
The business system should synchronously return a string to the payment center. Returning "success" indicates successful processing; any other response indicates failure, and the payment center will notify the business system again. (Notification frequency: 0/30/60/90/120/150 seconds)
Note: The returned string is case-insensitive, and it should not contain leading or trailing spaces or newline characters.
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"
}