1 前言

1.1 目标

本文档定义了收银系统客户端应用业务处理与插件接入方式和参数。

2 准备工作

2.1 获取对接资料

联系收钱吧商务获取对接资料（插件和文档），以及测试参数。

2.2 字典解释

术语	说明
商户号	商户在收钱吧开户时收钱吧分配给商户的商户号，一般来说同一个结算主体下的所有门店共用一个商户号
商户门店号	商户系统里的门店编号，一般为商户对外提供的门店编号，商户开户时提供给收钱吧

3 插件结构

名称	修改日期	类型	大小
cashpos.dll	2018/10/6 9:31	应用程序扩展	7,192 KB
cashpos_config.ini	2018/10/11 9:56	配置设置	1KB
CashPosAssistant.exe	2018/9/25 9:22	应用程序	6,580 KB
CashposConsole.exe	2018/9/25 9:22	应用程序	36 KB
CashposUpdate.exe	2018/9/25 9:28	应用程序	96 KB
CashposWrapper.dll	2018/10/12 8:51	应用程序扩展	36 KB

关键文件说明：
– CashposConsole.exe：插件exe程序
– cashpos.dll：主应用程序
– cashpos.lib: 应用程序库文件
– libeay32.dll: 系统文件
– cashpos_config.ini：商户配置文件
– serviceconfig.ini：插件配置文件
– EQB290001000001_pri.pem：商户私钥
– 000000000000000_pub.pem：平台公钥

商户只需要调用CashposWrapper.dll

4 接口协议

4.1 通讯方式

采用动态链接库dll函数调用方式传参和回参

4.2 通用数据

4.2.1 字符集

所有通讯数据统一采用UTF-8字符集。

4.3 接口设计

4.3.1 函数定义

// [IN] path: CashposConsole.exe绝对完整路径
// [IN] request: 调用参数
// [OUT] respond: 返回参数
//
// 返回值：
// -1: CashposConsole.exe路径错误
// 0: CashposConsole.exe启动失败或没有响应字符串
// 1: CashposConsole.exe调用成功，可以获取返回参数
int invokeCashpos(char* path, char* request, char* respond)

4.3.2 传入参数

将所有参数组装成JSON，具体字段参见各功能接口传入参数说明

4.3.3 返回参数

返回参数为JSON字符串，具体字段参见各功能接口返回参数说明。

如果请求错误只返回resultCode和resultDesc

4.3.4 Java调用示例

//继承接口
public interface Cashpos extends Library {
//函数声明
int invokeCashpos(String path, String request, byte[] respond);
}


//调用的类里面声明
private static Cashpos INSTANCE;

static {
    Cashpos INSTANCE = (Cashpos) Native
    .loadLibrary("C:\\..\\CashposWrapper", Cashpos.class);
}

//接收返回值，需要申请空间
byte[] pOutInfo = new byte[1024];
// CashposConsole.exe 完整路径
String path = "C:\\..\\CashposConsole.exe";
//请求参数
String request = "";
//函数调用
int returnCode = Cashpos.INSTANCE.invokeCashpos(path, request, pOutInfo);
//会自动去掉多余空格
String str = Native.toString (pOutInfo);

4.3.5 C#调用示例

[DllImport(".\\cashpos\\CashposWrapper.dll", EntryPoint = "invokeCashpos")]
public static extern int InvokeCashpos(String path, String inputdata, StringBuilder outputdata);

string CashPosRequst =
string CashPosPath =;
StringBuilder respond = new StringBuilder(1024);
int returnCode = InvokeCashpos(CashPosPath, CashPosRequst, respond);

4.3.6 Delphi 调用示例

待续

4.3.7 PowerBuilder 调用示例

// 声明
Public Function Long invokeCashpos(ref String path, ref String request, ref String respond) library 'CashposWrapper.dll'

//CashposConsole.exe 完整路径
string path

//调用参数
string request

//返回参数
string respond= space(1024);

//调用函数
long result = invokeCashpos(path, request, respond)

5 API列表

5.1 收款

用于收银机收款，实现常用条码支付和保险支付。注意金额单位为分，必须为整数。

5.1.1 重要提醒

如果商户调用收钱吧插件返回未支付成功时，商户可以给店员提供选择是否确认收款状态提示，如果店员选择是则调用查询接口，查询订单状态。查询成功进入下一步的业务处理。

5.1.2 传入参数

参数	参数名称	类型	必填	说明
operationCode	功能代码	String(2)	是	00 收款
merId	商户号	String(15)	是	商户号，开户后由收钱吧提供
merDepId	商户门店号	String(32)	是	商户门店号，由商户提供
merTermId	商户终端号	String(32)	是	固定值：0001
merOrdId	商户订单号	String(32)	是	商户订单号，商户保证其唯一性
merOrdDate	商户订单日期	String(8)	是	yyyyMMdd，例如：20150422
ordAmt	订单金额	String(10)	是	单位为分，整数串，例如：100
ordDetail	订单明细	String(600) (0)	是	JsonArray格式订单包含的商品详细列表信息，列表明细参见ordDetail参数说明
addlinfo	商户定制信息	String(128)	否	JSON格式业务定制参数，特殊应用场景和用法参见附录
deviceId	设备号	String()	是	收银机的唯一标识码默认值：商户门店号
limitPay	指定支付方式	String	否	可指定本单允许商户已开通的哪些支付方式付款，支付方式标记参见附录7.1章节，多个支付方式以竖线分割，例如微信和支付宝 WX\|AL

ordDetail参数说明：

注意金额单位为分，必须为整数

参数	参数名称	类型	必填	备注
itemId	商品编号	String(32)	是	合作商户药品库的药品编号，默认值：“-”中划线
itemName	商品名称	String(256)	是	药品名称，例如：维力青，默认值：“-”中划线
itemType	商品类型	String(64)	是	药品剂型，例如：片剂，默认值：“-”中划线
desc	批准文号	String(64)	是	例如：国药准字H201000141，默认值：“-”中划线
std	规格	String(64)	是	例如：0.5mg*7s，默认值：“-”中划线
unit	单位	String(64)	是	例如：盒，默认值：“-”中划线
price	单价	String(10)	是	单位为分，正整数串，例如：100，默认值：0
quantity	数量	String(12)	是	最多4位小数，例如：1，默认值：1
drugCode	药品本位码	String(32)	否	医保支付时必填
ybItemId	医保目录编码	String(32)	否	医保支付时必填
ybItemName	医保目录名称	String(256)	否	医保支付时必填

收款调用 JSON 示例：

{
    "merOrdDate": "20191030",
    "addiInfo": "",
    "operationCode": "00",
    "ordAmt": "110",
    "merId": "EQB290002000024",
    "merDepId": "0001",
    "merTermId": "0001",
    "deviceId": "01",
    "merOrdId": "ZF20191030183634",
    "ordDetail": [
        {
            "unit": "-",
            "itemName": "阿咖酚散",
            "price": "200",
            "desc": "-",
            "std": "-",
            "itemType": "-",
            "quantity": "1",
            "itemId": "A6464",
            "ybItemName": "阿咖酚散",
            "ybItemId": "86900373000013",
            "drugCode": "86900373000013"
        },
        {
            "unit": "-",
            "itemName": "中华跌打丸",
            "price": "1",
            "desc": "-",
            "std": "-",
            "itemType": "-",
            "quantity": "1",
            "itemId": "A6896",
            "ybItemName": "中华跌打丸",
            "ybItemId": "86905156000822",
            "drugCode": "86905156000822"
        }
    ]
}

5.1.3 返回参数

参数	参数名称	类型	必填	说明
resultCode	操作结果	String(4)	是	0000为接口调用成功，不代表业务处理成功，其它为调用失败
resultDesc	结果描述	String(256)	是	结果描述
merId	商户号	String(15)	是
merDepId	商户门店号	String(32)	是
merTermId	商户终端号	String(32)	是
merOrdDate	商户订单日期	String(8)	是	yyyyMMdd，例如：20150422
merOrdId	商户订单号	String(32)	是	商户收款订单号(查询确认收款订单状态)或商户退款订单号(查询确认退款订单状态)
ordStat	订单状态	String(2)	是	若查询收款订单： 00 – 支付成功 01 – 待支付 02 – 支付处理中 04 – 已过期 99 – 支付失败仅返回00时表示收款成功；
ordAmt	订单金额	String(10)	是	单位为分，正整数串，例如：100
ordDate	平台订单日期	String(8)	是	yyyyMMdd，例如：20150422
ordSeq	平台订单流水号	String(32)	是	该交易在收钱吧系统中的交易流水号。 ordSeq当天唯一，即ordSeq和ordDate联合唯一例如：WX000001 取前两位区分支付方式（大写）参见支付方式
chnIdate	渠道日期	String(8)	否	yyyyMMdd，例如：20150422
chnIseq	渠道流水号	String(64)	否
addlinfo	商户定制信息	String	是	JSON格式系统默认返回以下字段，如果商户请求时传了该字段也会一起返回，具体业务使用参见附录场景

5.1.3.1 addiInfo 简要说明

addiInfo 返回以下字段（请求时商户不能使用以下参数key）：

商家优惠金额 = 订单金额 – 实收金额
如果商家优惠金额大于0，商家系统需要将优惠金额处理（一般是均摊到每个商品）并且改写实收金额

参数	参数名称	类型	必填	备注
settlementAmt	实收金额	String(10)	是	商家实收金额
paymentDiscount	优惠信息	String	否	包含商家优惠和平台优惠（JSON格式）

paymentDiscount 说明

参数	参数名称	类型	备注
hongbaoWosai	喔噻红包	String(10)	平台优惠
hongbaoWosaiMch	喔噻商户红包免充值	String(10)	商家优惠
discountWosai	喔噻立减	String(10)	平台优惠
discountWosaiMch	喔噻商户立减免充值	String(10)	商家优惠
discountChannel	支付通道折扣(立减优惠)	String(10)	平台优惠
discountChannelMch	折扣(立减优惠)支付通道商户免充值	String(10)	商家优惠
discountChannelMchTopUp	折扣(立减优惠)支付通道商户充值	String(10)	平台优惠
hongbaoChannel	支付通道红包	String(10)	平台优惠
hongbaoChannelMch	支付通道商户红包免充值	String(10)	商家优惠
hongbaoChannelMchTopUp	支付通道商户红包充值	String(10)	平台优惠

收款返回JSON示例

{
    "chnlDate": "20191030",
    "chnlSeq": "7895238025376758",
    "merDepId": "0001",
    "merId": "EQB290002000024",
    "merOrdDate": "20191030",
    "merOrdId": "ZF20191030183634",
    "merTermId": "0001",
    "ordAmt": "110",
    "ordDate": "20191030",
    "ordSeq": "WX016900",
    "ordStat": "00",
    "resultCode": "0000",
    "resultDesc": "处理成功",
    "addiInfo": {
        "paymentDiscount": {
            "discountChannelMch": "100"
        },
        "settlementAmt": "10"
    }
}

5.2 退款

通过收钱吧完成的交易，商户可以通过退款接口将支付款全额退还顾客原付款账户。如果是银行卡付款具体到账时间请以付款银行为准。

5.2.1 重要提醒

收钱吧退款支持单笔收款交易分多次部分退款，多次退款需要使用不同的退款单号。申请退款总金额不能超过原收款订单金额。

商户一般采用全额退款。
一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号，相同退款单号的再次提交，收钱吧判定为同一笔退款需求，不会退出多笔款项；

5.2.2 传入参数

参数	参数名称	类型	必填	说明
operationCode	功能代码	String(2)	是	02 退款
merId	商户号	String(15)	是	商户号，开户后由收钱吧提供
merDepId	商户门店号	String(32)	是	商户门店号，由商户提供
merTermId	商户终端号	String(32)	是	固定值：0001
merOrdId	原商户收款订单号	String(32)	是	需要退的原收款订单单号
merOrdDate	原商户收款订单日期	String(8)	是	yyyyMMdd，例如：20150422
ordAmt	原收款订单金额	String(10)	是	单位为分，整数串，例如：100
ordDate	原平台订单日期	String(8)	是	yyyyMMdd，例如：20150422
ordSeq	原平台订单流水号	String(32)	是	原平台订单流水号
refundMerOrdDate	商户退款订单日期	String(8)	是	yyyyMMdd，例如：20150422
refundMerOrdId	商户退款订单号	String(32)	是	商户退款订单号(本次退款交易的唯一单号)
refundOrdDetail	退款商品明细	String(600)(0)	否	JsonArray格式需要退款的商品详细列表信息，列表明细参见ordDetail参数说明
refundAmt	退款金额	String(10)	是	单位为分，整数串，例如：100
deviceId	设备号	String(32)	是	收银机的唯一标识码默认值：商户门店号

refundOrdDetail 参数说明：

参数	参数名称	类型	必填	备注
itemId	商品编号	String(32)	是	合作商户药品库的药品编号，默认值：“-”中划线
itemName	商品名称	String(256)	是	药品名称，例如：维力青，默认值：“-”中划线
itemType	商品类型	String(64)	是	药品剂型，例如：片剂，默认值：“-”中划线
desc	批准文号	String(64)	是	例如：国药准字H201000141，默认值：“-”中划线
std	规格	String(64)	是	例如：0.5mg*7s，默认值：“-”中划线
unit	单位	String(64)	是	例如：盒，默认值：“-”中划线
price	单价	String(10)	是	单位为分，正整数串，例如：100，默认值：0
quantity	数量	String(12)	是	正整数串，例如：1，默认值：0

退款调用 JSON 示例：

{
  "operationCode": "02",
  "merId": "EQB551001000022",
  "merDepId": "0001",
  "merTermId": "0001",
  "merOrdId": "ZF20190222151144",
  "merOrdDate": "20190222",
  "ordAmt": "1",
  "ordDate": "20190222",
  "ordSeq": "WX010896",
  "refundMerOrdDate": "20190222",
  "refundMerOrdId": "TK201902221503452",
  "refundOrdDetail": [
    {
      "unit": "盒",
      "itemName": "健胃消食片",
      "price": "650",
      "desc": "国药准字H20100141",
      "std": "0.8g*8片*4板",
      "itemType": "片剂",
      "quantity": "1",
      "itemId": "syyy0001"
    },
    {
      "unit": "盒",
      "itemName": "三精双黄连口服液",
      "price": "1100",
      "desc": "国药准字H20100142",
      "std": "10ml*10支",
      "itemType": "口服液",
      "quantity": "2",
      "itemId": "syyy0002"
    }
  ],
  "refundAmt": "1",
  "deviceId": "01"
}

5.2.3 返回参数

参数	参数名称	类型	必填	说明
resultCode	操作结果	String(2)	是	0000为接口调用成功，不代表业务处理成功，其它为调用失败
resultDesc	结果描述	String(256)	是	结果描述
merId	商户号	String(15)	是	商户号
merDepId	商户门店号	String(32)	是	商户门店号
merTermId	商户终端号	String(32)	是	商户终端号
refundMerOrdId	商户退款订单号	String(32)	是	商户退款订单号
refundMerOrdDate	商户退款订单日期	String(8)	是	yyyyMMdd，例如：20150422
refundOrdSeq	平台退款订单流水号	String(32)	是	平台退款订单流水号，该交易在收钱吧系统中的交易流水号，ordSeq当天唯一，即ordSeq和ordDate联合唯一。
refundOrdDate	平台退款订单日期	String(8)	是	yyyyMMdd，例如：20150422
refundOrdStat	退款状态	String(2)	是	00 – 退款成功，01 – 退款申请成功(审核中)，02 – 退款处理中，04 – 已过期，99 – 退款失败，仅返回00时退款成功，其他状态，后续可调用查询接口确认退款状态
refundAmt	退款金额	String(10)	是	单位为分，正整数串，例如：100

退款返回 JSON 示例：

{
    "resultCode": "0000",
    "resultDesc": "处理成功",
    "merId": "EQB551001000022",
    "merDepId": "0001",
    "merTermId": "0001",
    "refundMerOrdId": "TK201902221503452",
    "refundMerOrdDate": "20190222",
    "refundOrdSeq": "WX010897",
    "refundOrdDate": "20190222",
    "refundOrdStat": "00",
    "refundAmt": "1"
}

5.3 查询

商户可以通过查询订单接口主动查询收款和退款订单状态，完成下一步的业务逻辑。
商户调用查询接口进行成功业务处理，一定要判断商户订单号和收钱吧订单号的唯一性，防止一个单号重复虚假支付。

5.3.1 重要提醒

需要调用查询接口的情况：
1. 商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；
2. 调用支付接口后，返回系统错误或未知交易状态情况；

5.3.2 传入参数

参数	参数名称	类型	必填	说明
operationCode	功能代码	String(2)	是	04 查询
merId	商户号	String(15)	是	商户号，开户后由收钱吧提供
merDepId	商户门店号	String(32)	是	商户门店号，由商户提供
merTermId	商户终端号	String(32)	是	固定值：0001
merOrdId	商户订单号	String(32)	是	商户收款订单号或者商户退款订单号，商户保证其唯一性
merOrdDate	商户订单日期	String(8)	是	yyyyMMdd，例如：20150422
deviceId	设备号	String(32)	是	收银机的唯一标识码，默认值：商户门店号

查询调用 JSON 示例：

{
    "operationCode": "04",
    "merId": "EQB551001000022",
    "merDepId": "0001",
    "merTermId": "0001",
    "merOrdId": "TK20190222150347",
    "merOrdDate": "20190222",
    "deviceId": "01"
}

5.3.3 返回参数

参数	参数名称	类型	必填	说明
resultCode	操作结果	String(4)	是	0000为接口调用成功，不代表业务处理成功，其它为调用失败
resultDesc	结果描述	String(256)	是	结果描述
merId	商户号	String(15)	是
merDepId	商户门店号	String(32)	是
merTermId	商户终端号	String(32)	是
merOrdDate	商户订单日期	String(8)	是	yyyyMMdd，例如：20150422
merOrdId	商户订单号	String(32)	是	商户收款订单号(查询确认收款订单状态)或商户退款订单号(查询确认退款订单状态)
ordStat	订单状态	String(2)	是	若查询收款订单： 00 – 支付成功 01 – 待支付 02 – 支付处理中 04 – 已过期 99 – 支付失败仅返回00时表示收款成功；若查询退款订单： 00 – 退款成功 01 – 待退款 02 – 退款处理中 04 – 已过期 99 – 退款失败仅返回00时表示退款成功。
ordAmt	订单金额	String(10)	是	单位为分，正整数串，例如：100
ordDate	平台订单日期	String(8)	是	yyyyMMdd，例如：20150422
ordSeq	平台订单流水号	String(32)	是	该交易在收钱吧系统中的交易流水号。 ordSeq当天唯一，即ordSeq和ordDate联合唯一例如：WX000001 取前两位区分支付方式（大写）参见支付方式
chnIdate	渠道日期	String(8)	否	yyyyMMdd，例如：20150422
chnIseq	渠道流水号	String(64)	否
addlinfo	商户定制信息	String	是	JSON格式系统默认返回以下字段，如果商户请求时传了该字段也会一起返回，具体业务使用参见附录场景

addiInfo 返回以下字段，请求时商户不能使用以下参数 key
商家优惠金额=订单金额-实收金额

参数	参数名称	类型	必填	备注
settlementAmt	实收金额	String(10)	是	商家实收金额
paymentDiscount	优惠信息	String	否	包含商家优惠和平台优惠 JSON格式具体字段参见paymentDiscount说明

paymentDiscount 说明：

参数	参数名称	类型	必填	备注
hongbaoWosa	喔噻红包	String(10)	否	平台优惠
hongbaoWosaMch	喔噻商户红包免充值值	String(10)	否	商家优惠
discountWosa	喔噻立减	String(10)	否	平台优惠
discountWosaMch	喔噻商户立减免充值值	String(10)	否	商家优惠
discountChannel	支付通道折扣(立减优惠)	String(10)	否	平台优惠
discountChannelMch	折扣(立减优惠) 支付通道商户免充值值	String(10)	否	商家优惠
discountChannelMchTop	折扣(立减优惠) 支付通道商户充值值	String(10)	否	平台优惠
hongbaoChannel	支付通道红包	String(10)	否	平台优惠
hongbaoChannelMch	支付通道商户红包免充值值	String(10)	否	商家优惠
hongbaoChannelMchTop	支付通道商户红包充值值	String(10)	否	平台优惠

查询返回 JSON 示例：

{
    "chnlDate": "20191030",
    "chnlSeq": "7895238025376758",
    "merDepId": "0001",
    "merId": "EQB290002000024",
    "merOrdDate": "20191030",
    "merOrdId": "ZF20191030183634",
    "merTermId": "0001",
    "ordAmt": "110",
    "ordDate": "20191030",
    "ordSeq": "WX016900",
    "ordStat": "00",
    "resultCode": "0000",
    "resultDesc": "调用成功",
    "addiInfo": {
        "paymentDiscount": {
            "discountChannelMch": "100"
        },
        "settlementAmt": "10"
    }
}

6 调试说明

6.1 请求出错说明

resultCode 为 0000 时代表调用成功，不代表业务处理成功。
resultCode 不为 0000 时代表请求出错，resultDesc 为错误描述。
请求出错时只返回 resultCode 和 resultDesc。

6.1.1 请求出错的常见原因

(1) 可能是参数传错，或者是必须的参数未传
(2) 解密失败
(3) 验签失败
(4) 注意所有金额单位为分，整数

7 附录

7.1 支付方式

代码	名称	备注
00	收钱吧保险支付
AL	支付宝
WX	微信
UQ	银联云闪付
DC	数字人民币	覆盖人民银行确定所有试点区域，工/建/农/中/交/邮/招7家企业数字人民币钱包
BP	翼支付
CM	移动和包
LK	刷卡拉卡拉
UM	刷卡银联商务
EK	智慧E保	原医卡通/亿保/健保通
PK	普康卡
RH	企健网
YS	钥匙卡
JY	健医在线
WD	直付保	万达医疗合作业务
PA	平安付壹卡会
SB	健保通付
OK	联华OK卡
MB	电子会员卡
YJ	宜捷通
YB	微信医保
UB	银联医保
LP	礼品卡
YP	优势付
RX	瑞祥卡
PJ	平安药诊卡	平安好医生/平安健康
CC	中智企服卡
BM	国药博明健康卡
PW	瓴文医疗	九州通瓴文医疗合作业务
JZ	健世保	健阵医药合作业务
KY	康云通
ZL	智龢健康
HY	惠医保
HT	瀚银通
YI	优寿卡
TC	同昌保险卡
GH	国惠通
JH	建行生活APP
ZH	招行掌上生活APP

8 常见问题处理

8.1掉单

由于网络，收银机系统等原因导致收钱吧侧支付成功，商户未成功，以下称为掉单。
如果商户调用收钱吧时保存了收款时使用的数据，则用调用时的收款单号调用查询接口获取订单信息。

如果商户调用收钱吧未保存收款时使用的数据，则需要店员输入收款时使用的订单号调用查询接口查询订单信息，输入的订单号先判断订单号在商户系统是否存在。

查询成功后，一定要判断商户订单号和收钱吧订单号的在商户系统的唯一性，防止一个单号重复虚假支付。
查询成功后，商户需要将查询的订单信息保存下来，退款时会使用收款订单相关参数。

8.2 退款失败

商户调用收钱吧退款失败，不要更换单号，用同一单号继续调用收钱吧退款。
如果退款失败可以联系收钱吧客服咨询失败原因。