WLAN/LAN模式API列表
通信协议
WiseCashier使用WebSocket协议在服务器端实现。WebSocket是一种用于客户端和服务器之间任意双向数据传输的技术。WebSocket协议是基于TCP协议实现的，由初始握手和随后的多个数据帧的双向传输组成。其目的是在WebSocket客户端和WebSocket服务器之间进行频繁的双向通信，可以使服务器避免打开多个HTTP连接来工作，以节省资源，提高效率和资源利用率。
消息结构
字段格式
POS应用 程序和WiseCashier以JSON格式通信
输入参数结构图
输出参数结构图
公共字段
本文件根据以下约定对每个字段的不同方面进行了定义。
- M：所需参数
- C：满足某些条件时所需的参数
- O：可选参数
- -：不存在 常见参数如下：
| 参数 | 类型 | 请求 | 响应 | 说明 |
|---|---|---|---|---|
| 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 Gateway, 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. |
业务字段
1. 提交交易请求
消息主题
ecrhub.pay.order
参数列表
| 参数 | Type | 请求 | 响应 | 说明 |
|---|---|---|---|---|
| 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 gateway to call back the server address, and only when the transaction goes through the PayCloud payment gateway 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 |
forecourt_data数据结构如下：
| 参数 | Type | 请求 | 响应 | 说明 |
|---|---|---|---|---|
| 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. 查询交易
消息主题
ecrhub.pay.query
参数列表
| 参数 | Type | 请求 | 响应 | 说明 |
|---|---|---|---|---|
| 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. 关闭交易
消息主题
ecrhub.pay.close
参数列表
| 参数 | Type | 请求 | 响应 | 说明 |
|---|---|---|---|---|
| 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 |