WiseCashier-SDK for Windows

1. 简介

1.1 概述

本文档旨在帮助开发者在 Windows 主机上集成 WiseCashier 提供的支付 API，使商家的应用程序能够与支付终端或POS设备进行支付交互。两个设备通过 WLAN/LAN 连接，实现高效、稳定的通信。

在阅读本文档之前，请先阅读 跨终端应用集成-WLAN/LAN模式集成。

我们为 ECR 支付解决方案提供了专门设计的 Windows SDK，包含以下文件：

文件名	描述
wisesdk_ecr_win.h	此头文件包含 API 函数的定义。
error_code_ecr.h	此头文件包含错误代码的定义。
WiseSdk_EcrHost_Payment_X86.lib	Visual Studio 可能需要的导入库，适用于 x86 平台。
WiseSdk_EcrHost_Payment_X86.dll	ECR 程序依赖的动态库，适用于 x86 平台。
WiseSdk_EcrHost_Payment_X64.lib	Visual Studio 可能需要的导入库，适用于 x64 平台。
WiseSdk_EcrHost_Payment_X64.dll	ECR 程序依赖的动态库，适用于 x64 平台。

点此下载文件

1.2 软件架构

使用WLAN/LAN连接，ECR主机和支付终端需要在同一局域网上，并确保它们之间的网络通信是正常的。

2 开发环境设置

本节以C#语言为例，描述开发环境的搭建过程。

2.1 下载并安装Visual Studio

您可以从Microsoft的官网下载Visual Studio 2017或更高版本。推荐将Visual Studio的默认编码设置为"UTF-8 with signature"，如下图所示：

2.2 创建新项目

• 将dll文件复制到你的执行目录中，如下截图所示：

• 将指定的函数导入程序。

• 调用动态库中的函数来构建和运行项目。

2.3 导入演示项目

使用Visual Studio打开EcrHost_TransSdk.sln文件。

2.4 运行项目

单击“本地Windows调试器”按钮运行项目。

2.5 连接POS终端设备（通过Wi-Fi）

1. 选择“Wi-Fi”模式，点击“Start”按钮等待配对。日志区域显示扫描设备的IP地址。

2. 配对后，点击“连接”按钮。

3. 连接成功后，输入“商家订单号”和“金额”，点击“Sale”按钮。

3. 数据结构

3.1 终端信息

typedef struct
{
    char szTerminalMacAddr[18]; // The MAC address of the terminal, ending with ‘\0’. for example, "00:1A:2B:3C:4D:5E".

    char szTerminalName[65];    // The terminal name, ending with ‘\0’.
    BYTE bTerminalNameLen;      // The length of the terminal name which includes the ‘\0’ terminator.

    char szAliasName[65];       // The terminal alias name, ending with ‘\0’.
    BYTE bAliasNameLen;         // The length of the terminal alias name which includes the ‘\0’ terminator.

    char szTerminalIp[40];      // The IP address of the terminal, ending with ‘\0’. for example, "192.168.1.2".
    BYTE bTerminalIpLen;        // The length of IP address which includes the ‘\0’ terminator.

    DWORD dwPort;               // The IP port

    char szTerminalSn[33];     // The terminal serial number, ending with ‘\0’
    BYTE bTerminalSnLen;       // The length of the terminal serial number which includes the ‘\0’ terminator.
}ST_TERMINAL_INFO;

4. 流程说明

提示

请注意，此流程图旨在呈现通用流程，涵盖设备配对、网络连接、交易处理等关键点。在实际操作中，一些API调用和函数并不需要每次都执行。而且，还有一些API和函数在本流程图中没有展示。您可以根据自己的实际需求调整流程。

5. APIs

5.1 序列

5.2 ECR初始化

此函数用于初始化SDK，此函数在内部执行必要的初始化，应用程序在调用任何其他函数之前必须先调用此函数，但只需要调用一次。

DWORD ECR_Init(IN DWORD dwConnectionType);

Parameters
dwConnectionType	This parameter specifies the communication interface between the ECR Register and the terminal, which can be CONNECTION_TYPE_USB or CONNECTION_TYPE_LAN.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

UInt32 ret = ECR_Init(CONNECTION_TYPE_LAN);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("ECR Init successful!");
}

5.3 网络配对和连接

5.3.1 等待配对

该函数用于在ECR和POS终端之间建立网络配对。在该函数中，进行mDNS广播并启动websocket侦听服务以接收来自终端的配对请求。

DWORD ECRLAN_WaitPairing(IN ST_ECR_LAN_PAIRING_CALLBACK *pstPairingCallback);

Parameters
pstPairingCallback	A structure pointer containing multiple callback functions for network pairing. Please refer to the section Network pairing callback.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

ST_ECR_LAN_PAIRING_CALLBACK _lanPairCallback = new ST_ECR_LAN_PAIRING_CALLBACK();
_lanPairCallback.RequestPair = new onRequestPairing(RequestPairing_Event);
_lanPairCallback.RequestUnpair = new onRequestUnpairing(RequestUnpairing_Event);
UInt32 ret = ECRLAN_WaitPairing(ref _lanPairCallback);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("ECRLAN Wait Pairing!");
}
else if (ret == ERR_ECR.ERR_ECR_WAIT_PAIRING)
{
        MessageBox.Show("ECRLAN Wait Pair is already running!");
}

5.3.2 停止等待配对

此功能用于停止已启动的配对过程。

DWORD ECRLAN_StopWaitPairing(void);

Return
0	Success
Other values	Refer to Error Code table

Sample code:

UInt32 ret = ECRLAN_StopWaitPairing();
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("ECRLAN Stop Wait Pairing successful!");
}

5.3.3 接受配对

该函数用于接受终端发送的配对请求，接受终端的配对请求后，该函数将在内部永久保存配对成功的终端的信息，除非应用程序调用ECRLAN_DeletePairList函数删除配对信息，否则配对信息将一直存在。

DWORD ECRLAN_AcceptPairing(IN ST_TERMINAL_INFO *pstTerminalInfo);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that will be accepted for pairing.Regarding the terminal information structure, please refer to the section Terminal information.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

List<ST_TERMINAL_INFO> _lstStTerminalInfo = new List<ST_TERMINAL_INFO>();
_lstStTerminalInfo = GetPairArray();
if (_lstStTerminalInfo.Count <= 0)
{
        MessageBox.Show("Pairlist is empty!");
        return;
}
_curTerminalInfo = _lstStTerminalInfo[0];
UInt32 ret = ECRLAN_AcceptPairing(ref _curTerminalInfo);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("ECRLAN Accept Pairing successful!");
}

5.3.4 拒绝配对

该功能用于拒绝终端发送的配对请求。

DWORD ECRLAN_RejectPairing(IN ST_TERMINAL_INFO *pstTerminalInfo);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that will be rejected for pairing. Regarding the terminal information structure, please refer to the section Terminal information.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

List<ST_TERMINAL_INFO> _lstStTerminalInfo = new List<ST_TERMINAL_INFO>();
_lstStTerminalInfo = GetPairArray();
if (_lstStTerminalInfo.Count <= 0)
{
        MessageBox.Show("Pairlist is empty!");
        return;
}
_curTerminalInfo = _lstStTerminalInfo[0];
UInt32 ret = ECRLAN_RejectPairing(ref _curTerminalInfo);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("ECRLAN Reject Pairing successful!");
}

5.3.5 取消配对

该功能会通知终端，并终止与终端的配对关系。但不会断开当前网络连接。此外，该功能会自动将终端从内部配对列表中删除。

void ECRLAN_Unpair(IN ST_TERMINAL_INFO *pstTerminalInfo);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that will be unpaired. Regarding the terminal information structure, please refer to the section Terminal information.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

List<ST_TERMINAL_INFO> _lstStTerminalInfo = new List<ST_TERMINAL_INFO>();
_lstStTerminalInfo = GetPairArray();
if (_lstStTerminalInfo.Count <= 0)
{
        MessageBox.Show("Pairlist is empty!");
        return;
}

_curTerminalInfo = _lstStTerminalInfo[0];
ECRLAN_Unpair(ref _curTerminalInfo);

5.3.6 获取配对列表

该函数用于获取该SDK内维护的所有成对终端信息的列表。

DWORD ECRLAN_GetPairList(OUT ST_TERMINAL_INFO *pstTerminalInfo, IN OUT DWORD *pdwNum);

Parameters
pstTerminalInfo	A pointer to an array of structures used to hold information about terminals that have ever been successfully paired. When this parameter is NULL, this function will return “ERROR_SUCCESS” and the pdwNum parameter will return the actual number of paired terminals. Regarding the terminal information structure, please refer to the section Terminal information.
pdwNum	As an input parameter, it indicates the maximum expected number of paired terminals to be obtained. If the size of pstTerminalInfo is insufficient, ERR_ECR_BUFFER_NOT_ENOUGH will be returned. As an output parameter, it indicates the number of terminals actually returned that were ever paired successfully.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

ST_TERMINAL_INFO[] curTerminalInfo = new ST_TERMINAL_INFO[20];
int curNum = 20;
IntPtr ptrTerminals = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(ST_TERMINAL_INFO)) * 20);
UInt32 ret = ECRLAN_GetPairList(ptrTerminals, ref curNum);
for (int i = 0; i < curNum; i++)
{
        IntPtr ptr = (IntPtr)((UInt32)ptrTerminals + i * Marshal.SizeOf(typeof(ST_TERMINAL_INFO)));
        curTerminalInfo[i] = (ST_TERMINAL_INFO)Marshal.PtrToStructure(ptr, typeof(ST_TERMINAL_INFO));
}
Marshal.FreeHGlobal(ptrTerminals);

List<ST_TERMINAL_INFO> lstStTerminalInfo = new List<ST_TERMINAL_INFO>();
for (int i = 0; i < curNum; i++)
{
        lstStTerminalInfo.Add(curTerminalInfo[i]);
}

5.3.7 删除配对列表

该功能用于从配对信息列表中移除所有终端或指定终端。该功能无需通知终端。

DWORD ECRLAN_DeletePairList(IN ST_TERMINAL_INFO *pstTerminalInfo, IN DWORD dwFlag);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that will be deleted. To delete all paired terminals, set to NULL. Regarding the terminal information structure, please refer to the section Terminal information.
dwFlag	A flag. If the value is 0, the specified terminal is deleted; if the value is 1, all paired terminals are deleted.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

_lstStTerminalInfo = GetPairArray();
if (_lstStTerminalInfo.Count <= 0)
{
        MessageBox.Show("Pairlist is empty!");
        return;
}
UInt32 ret = ECRLAN_DeletePairList(_lstStTerminalInfo[0], 0);
if (_ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("ECRLAN Delete PairList successful!");
        return;
}

5.3.8 网络连接

该功能用于与终端建立网络连接。

DWORD ECRLAN_Connect(IN ST_TERMINAL_INFO *pstTerminalInfo, IN DWORD dwWaitingSeconds, IN ST_ECR_CONNECTION_CALLBACK *pstConnectionCallback);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that will be connected. Regarding the terminal information structure, please refer to the section Terminal information.
dwWaitingSeconds	Timeout time in seconds
pstConnectionCallback	A structure pointer containing multiple callback functions for connection. Please refer to the section Connection callback.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

_lstStTerminalInfo = GetPairArray();
if (_lstStTerminalInfo.Count <= 0)
{
        MessageBox.Show("Pairlist is empty!");
        return ERR_ECR.ERR_ECR_SUCCESS;
}

_ecrConnectCallback.WsConnected = new onWsConnected(WsConnected_Event);
_ecrConnectCallback.WsDisconnected = new onWsDisconnected(WsDisconnected_Event);
_ecrConnectCallback.WsError = new onWsError(WsError_Event);
_curTerminalInfo = _lstStTerminalInfo[0];
UInt32 ret = ECRLAN_Connect(ref _curTerminalInfo, 60, ref _ecrConnectCallback);
return ret;

5.3.9 网络断开

该功能用于断开与当前终端的网络连接。

DWORD ECRLAN_Disconnect(void);

Return
0	Success
Other values	Refer to Error Code table

Sample code:

UInt32 ret = ERR_ECR.ERR_ECR_SUCCESS;
if (_connectionType == CONNECTION_TYPE_LAN)
        ret = ECRLAN_Disconnect();

if (ret != ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show($"ECRLAN_Disconnect Errorcode:{ret.ToString("X2")}");
}

5.3.10 获取网络连接状态

此功能用于检查与终端的网络连接状态。

BOOL ECRLAN_isConnected(void);

Return
Network connection status	TRUE: the network is connected; FALSE: the network is in a disconnected state.

Sample code:

if (TRUE == ECRLAN_isConnected())
        return ERR_ECR.ERR_ECR_SUCCESS;

5.4 网络配对回调

5.4.1 回调结构的定义

typedef struct
{
    //This callback function is called when Terminal requests a pairing
    void (*onRequestPairing)(IN ST_TERMINAL_INFO *pstTerminalInfo);

    //This callback function is called when Terminal requests to be unpaired
    void (*onRequestUnpairing)(IN ST_TERMINAL_INFO *pstTerminalInfo);
}ST_ECR_LAN_PAIRING_CALLBACK;

5.4.2 onRequestPairing

当终端请求配对时调用此回调函数。

void (*onRequestPairing)(IN ST_TERMINAL_INFO *pstTerminalInfo);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that requests a pairing. Regarding the terminal information structure, please refer to the section Terminal information.

5.4.3 onRequestUnpairing

当终端请求取消配对时调用此回调函数。

void (*onRequestUnpairing)(IN ST_TERMINAL_INFO *pstTerminalInfo);

Parameters
pstTerminalInfo	The terminal information of the specified terminal that requests unpairing. Regarding the terminal information structure, please refer to the section Terminal information.

5.5 连接回调

5.5.1 回调结构的定义

typedef struct
{
    //This callback function is called when a network or USB connection is established
    void (*onConnected)(void);

    //This callback function is called when the network or USB connection is disconnected
    void (*onDisconnected)(void);

    //This callback function is called when an error occurs during connection establishment
    void (*onError)(IN DWORD dwErrCode, IN char *pszErrMsg);
}ST_ECR_CONNECTION_CALLBACK;

5.5.2 onConnected

此回调函数在建立网络时调用。

void (*onConnected)(void);

5.5.3 onDisconnected

当网络连接断开时调用此回调函数。

void (*onDisconnected)(void);

5.5.4 onError

当连接建立过程中发生错误时调用此回调函数。

void (*onError)(IN DWORD dwErrCode, IN char *pszErrMsg);

Parameters
dwErrCode	The error code.
pszErrMsg	The detailed error message.

5.6 交易

5.6.1 开始交易

该函数用于调用终端执行交易流程，包括购买、返现、作废、预授权等。

DWORD ECR_DoTransaction(IN char *pszRequestMessage, IN DWORD dwWaitingSeconds, IN ST_ECR_TRANS_CALLBACK *pstTransCallback);

Parameters
pszRequestMessage	Request message data about the transaction sent by the ECR Register to the terminal. The message is in Json format. Please refer to the section 交易消息-提交交易请求
dwWaitingSeconds	The timeout time for the transaction in seconds. If terminal does not return at the set time, WAIT_TIMEOUT is returned.
pstTransCallback	A structure pointer containing multiple callback functions for transaction. Please refer to the section Transaction callback. In the correct case, onSuccess is called, and the pszResponse parameter returns the terminal's response message (in Json format). In case of error, onError is called.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

ST_ECR_TRANS_CALLBACK _transCallback = new ST_ECR_TRANS_CALLBACK();
_transCallback.TransSuccess = new onTransSuccess(TransSuccess_Event);
_transCallback.TransError = new onTransError(TransError_Event);

PaymentRequestParams reqParams = new PaymentRequestParams();
reqParams.app_id = "wz6012822ca2f1as78";
reqParams.topic = Constants.PAYMENT_TOPIC;
reqParams.biz_data = new PaymentRequestParams.BizData();
reqParams.biz_data.merchant_order_no = tbOrderNumber.Text;// "123" + DateTime.Now.ToString("yyyyMMddHHmmss");
reqParams.biz_data.order_amount = tbAmount.Text;//"11";
reqParams.biz_data.pay_scenario = "SWIPE_CARD";
reqParams.biz_data.trans_type = Constants.TRANS_TYPE_SALE;

string json = JsonConvert.SerializeObject(reqParams, new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });
UInt32 ret = ECR_DoTransaction(json, 60, ref _transCallback);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show($"Sale:{json}");
}
else
{
        MessageBox.Show($"Sale ErrorCode:{ret.ToString("X2")}");
}

5.6.2 取消交易

该函数用于取消终端对交易的执行。请注意，并非所有交易都可以取消，只能取消部分处于等待用户交互状态的交易。

DWORD ECR_CancelTransaction(IN char *pszRequestMessage, IN DWORD dwWaitingSeconds);

Parameters
pszRequestMessage	Request message data about the transaction sent by the ECR Register to the terminal. The message is in Json format. Please refer to the section 交易消息-关闭交易
dwWaitingSeconds	The timeout time for the transaction in seconds. If terminal does not return at the set time, WAIT_TIMEOUT is returned.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

PaymentRequestParams reqParams = new PaymentRequestParams();
reqParams.app_id = "wz6012822ca2f1as78";
reqParams.topic = Constants.CLOSE_TOPIC;
reqParams.biz_data = new PaymentRequestParams.BizData();
reqParams.biz_data.merchant_order_no = tbOrderNumber.Text; //"123" + DateTime.Now.ToString("yyyyMMddHHmmss");

JsonSerializerSettings jsetting = new JsonSerializerSettings();
jsetting.DefaultValueHandling = DefaultValueHandling.Ignore;
jsetting.NullValueHandling = NullValueHandling.Ignore;
string json = JsonConvert.SerializeObject(reqParams, jsetting);
UInt32 ret = ECR_CancelTransaction(json, 60);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show("Cancel:{json}");
}
else
{
        MessageBox.Show($"Cancel ErrorCode:{ret.ToString("X2")}");
}

5.6.3 查詢交易

该功能用于查询终端的交易记录。

DWORD ECR_QueryTransaction(IN char *pszRequestMessage, IN DWORD dwWaitingSeconds, IN ST_ECR_TRANS_CALLBACK *pstTransCallback);

Parameters
pszRequestMessage	Request message data about the transaction sent by the ECR Register to the terminal. The message is in Json format. Please refer to the section 交易消息-查询交易
dwWaitingSeconds	The timeout time for the transaction in seconds. If terminal does not return at the set time, WAIT_TIMEOUT is returned.
pstTransCallback	A structure pointer containing multiple callback functions for transaction. Please refer to the section Transaction callback. In the correct case, onSuccess is called, and the pszResponse parameter returns the terminal's response message (in Json format). In case of error, onError is called.

Return
0	Success
Other values	Refer to Error Code table

Sample code:

ST_ECR_TRANS_CALLBACK _transCallback = new ST_ECR_TRANS_CALLBACK();
_transCallback.TransSuccess = new onTransSuccess(TransSuccess_Event);
_transCallback.TransError = new onTransError(TransError_Event);

PaymentRequestParams reqParams = new PaymentRequestParams();
reqParams.app_id = "wz6012822ca2f1as78";
reqParams.topic = Constants.QUERY_TOPIC;
reqParams.biz_data = new PaymentRequestParams.BizData();
reqParams.biz_data.merchant_order_no = tbOrderNumber.Text;

JsonSerializerSettings jsetting = new JsonSerializerSettings();
jsetting.DefaultValueHandling = DefaultValueHandling.Ignore;
jsetting.NullValueHandling = NullValueHandling.Ignore;
string json = JsonConvert.SerializeObject(reqParams, jsetting);
UInt32 ret = ECR_QueryTransaction(json, 60, ref _transCallback);
if (ret == ERR_ECR.ERR_ECR_SUCCESS)
{
        MessageBox.Show($"Query:{json}");
}
else
{
        MessageBox.Show($"Query ErrorCode:{ret.ToString("X2")}");
}

5.7 交易回调

5.7.1 回调结构的定义

typedef struct
{
    //This function is called when a transaction is executed correctly.
    void (__stdcall *onSuccess)(IN char *pszResponse);

    //This function is called when there is an error in the execution of a transaction.
    void (__stdcall *onError)(IN DWORD dwErrCode, IN char *pszErrMsg);
}ST_ECR_TRANS_CALLBACK;

5.7.2 onSuccess

当交易成功时调用此函数。

void (*onSuccess)(IN char *pszResponse);

Parameters
pszResponse	Request message data about the transaction sent by the ECR Register to the terminal. The message is in Json format. Please refer to the section Transaction message.

5.7.3 onError

当交易失败时调用此函数。

void (*onError)(IN DWORD dwErrCode, IN char *pszErrMsg);

Parameters
dwErrCode	The error code.
pszErrMsg	The detailed error message.

6.附录

6.1 Error Code Table

Key	Value	说明
ERR_SUCCESS	0	The operation succeeded
ERR_ECR_INVALID_PARAMETER	0xE0030001	Invalid parameter
ERR_ECR_LENGTH_OUT_RANGE	0xE0030002	The length is out of range
ERR_ECR_DATA_CHECK	0xE0030005	Bad data checksum
ERR_ECR_BAD_DATA	0xE0030006	Error in the data
ERR_ECR_BUFFER_NOT_ENOUGH	0xE0030007	Insufficient buffer size
ERR_ECR_TIMEOUT	0xE0030008	Communication timeout
ERR_ECR_READ_DATA	0xE003000A	Failed to read data
ERR_ECR_WRITE_DATA	0xE003000B	Failed to write data
ERR_ECR_USB_CABLE_NOT_CONNECTED	0xE003000F	No terminal connected to ECR via USB cable
ERR_ECR_USB_NOT_CONNECTED	0xE0030010	No USB connection has been established
ERR_ECR_WIFI_NOT_CONNECTED	0xE0030011	No Wi-Fi connection has been established
ERR_ECR_WIFI_SEND_FAILED	0xE0030012	Failed to send data via Wi-Fi
ERR_ECR_DEV_UNPAIRED	0xE0030013	Device unpaired
ERR_ECR_JSON_ERROR	0xE0030014	Json data incorrect
ERR_ECR_WAIT_PAIRING	0xE0030015	It is already in the state of waiting for the pairing request from the terminal