WLAN/LAN Mode API List

Communication Protocol

WiseCashier uses the WebSocket protocol to implement the server side. WebSocket is a technology used for arbitrary two-way data transfer between the client and the server. The WebSocket protocol is implemented based on the TCP protocol and consists of an initial handshake and subsequent two-way transfer of multiple data frames. Its purpose is in the WebSocket client and WebSocket server for frequent two-way communication, can make the server to avoid opening multiple HTTP connections to work to save resources, improve the efficiency and resource utilization.

Message Structure

Field Format

POS application and WiseCashier communicate in JSON format

Input Parameter Structure Diagram

Output Parameter Structure Diagram

Common Field

Different aspects of each field are defined in this document according to the following conventions.

• M: Required parameters
• C: Required parameters when some conditions are met
• O: Optional parameters
• -: Not Present The common parameters is as follows:

Key	Parameter type	Request	Response	Description
topic	string	M	M	Message topic identifier. Enum: ecrhub.pay.order ecrhub.pay.query ecrhub.pay.close
timestamp	string	M	-	Timestamp Example: 1698302992263
app_id	string	M	M	The payment app id registered in PayCloud, Please refer to the Payment gateway integration guide
biz_data	JSONObject	M	M	Business Data. each transaction type has own business data
response_code	string	-	M	The order payment status code returned by WiseCashier, 000 means the transaction was successful, other means the transaction failed.Please refer to Response code
response_msg	String	-	C	Failed transaction error message returned by WiseCashier

Biz Field

1. Submit Transaction

Message Topic

ecrhub.pay.order

Parameter list

Name	Type	Request	Response	Description
trans_type	String	M	M	Transaction type. Please refer to Transaction type Example: 1
merchant_order_no	String	M	M	Merchant order number.This field represents the order number for the refund request when refunded, different from the order number of the original consumer transaction. No more than 32 alphanumeric characters. Example: 121775014073233018
orig_merchant_order_no	String	C	C	Original merchant order number. If the transaction type is Void, Refund, Completion, it must be required. (trans_type = 2,3,6) Example: 121775014073233368018
order_amount	String	M	M	Order amount. This field represents the transaction ordered amount, For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	String	O	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 34.50
cashback_amount	String	O	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent Example: 10.00
pay_method_id	String	O	O	Payment method id. Please Refer to Payment method If the TransType is 3, this parameter will not required Example:Visa
pay_scenario	String	O	O	Payment scene, please refer to PayScenario Example: SWIPE_CARD
attach	String	O	O	Additional data.Allows merchants to submit additional data, which will be returned as is. Example: abc123
description	String	O	O	Description of ordered goods or services.A brief description of the goods or services purchased by the customer. Example: IPhone White X2
notify_url	String	O	O	Callback address for payment notification.Receive payment notifications from the PayCloud to call back the server address, and only when the transaction goes through the PayCloud will there be a callback. Example: http://www.abc.com/callback?id=12345
expires	Number	O	O	Order expires time, after the expires time is not allowed to be paid, unit: seconds Example: 180
confirm_on_terminal	boolean	O	O	Do you need terminal confirmation before proceeding with payment operations? The default is false. When set to true, you need to confirm the order first, otherwise you will directly enter the card reading interface
required_terminal_authentication	boolean	O	O	When refund or void a transaction, does the store manager role need to authorize this operation on the terminal? default value: false
trans_no	String	-	M	Transaction number of PayCloud. which uniquely identifies a transaction. Example: 5021000010210602000003
trans_status	String	-	M	Transaction status, please refer to Transaction status
trans_end_time	string	-	O	Transaction completed time. If trans_status is 2, the returned data will include this parameters. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51
forecourt_data	JSONArray	O	-	If the merchant is a gas station, use this parameter to set special gas station product information. forecourt_data is an array. The total sum of forecourt_data item amounts must be equal to the order amount order_amount

The data structure of forecourt_data is as follows.

Name	Type	Request	Response	Description
code	String	M	-	Product Code It is usually a two-digit numeric code, such as: 02
quantity	String	M	-	Quantity Litres (3 decimals) Keep three decimal places, for example: 1.050
amount	String	M	-	Amount (cents) An integer in cents, where 1 South African Rand is represented as 100 here. Its unit is different from order_amount. Example: 100

2. Query Transaction

Message Topic

ecrhub.pay.query

Parameter list

Name	Type	Request	Response	Description
merchant_order_no	String	M	M	Merchant order number.This field represents the order number for the refund request when refunded, different from the order number of the original consumer transaction. No more than 32 alphanumeric characters. Example: 121775014073233018
trans_type	String	-	M	Transaction type. Please refer to Transaction type Example: 1
order_amount	String	-	M	Order amount. This field represents the transaction ordered amount, For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	String	-	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 34.50
cashback_amount	String	-	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent Example: 10.00
attach	String	-	O	Additional data.Allows merchants to submit additional data, which will be returned as is. Example: abc123
trans_no	String	-	M	Transaction number of PayCloud. which uniquely identifies a transaction. Example: 5021000010210602000003
trans_status	String	-	M	Transaction status, please refer to Transaction status
pay_scenario	String	-	O	Payment scene, If trans_status is 2, the returned data will include the following parameters, please refer to Please Refer to PayScenario Example: SWIPE_CARD
pay_method_id	String	-	O	Payment method id. If trans_status is 2, the returned data will include the following parameters. Please Refer to Payment method If the TransType is 3, this parameter will not required Example:Visa
trans_end_time	string	-	O	Transaction completed time. If trans_status is 2, the returned data will include the following parameters. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51

3. Close Transaction

Message Topic

ecrhub.pay.close

Parameter list

Name	Type	Request	Response	Description
merchant_order_no	String	M	M	Merchant order number.This field represents the order number for the refund request when refunded, different from the order number of the original consumer transaction. No more than 32 alphanumeric characters. Example: 121775014073233018