概要描述:
· SDK适用的智能终端（android系统）：商米P2，新大陆N910，联迪A8，联迪A8S
· SDK中只提供银行卡交易功能，码交易功能暂未实现
· SDK使用说明：(附件有Demo和对接所需资源文件，详见7)
接入须知:
1.导入sdk所需aar及so文件，建议放在 主module libs目录下：
2.主module下build.gradle下配置：
3.sdk 初始化：
为避免初始化失败，请在初始化前确保使用的设备已经在我司生产环境入库并已经成功绑定商户
如设备为自备机，请确保设备已经成功报备至海科机构下，海科机构代码：48330000
BaseSdkFactory 为工厂类，实例化不同设备类型对象
BaseController 调用控制类
HkSdkCallback SDK回调接口（详见5）
// 联迪A8 A8S// BaseSdkFactory factory = new LandiSdkFactory();
// 新大陆N910
// BaseSdkFactory factory = new NewlandSdkFactory();
// 商米P2
BaseSdkFactory factory = new SunmiSdkFactory();
BaseController sdkController = factory.getSdkController(Context,HkSdkCallback);
sdkController.init(context);
4.sdk功能接口调用：（需要开启 存储、位置权限）以下为传参及调用示例
动态获取用户权限需使用方自行实现
private void toTrade(int requestCode) {
if (requestCode == PERMISSION_REQUESTCODE_CONSUME) {
// 银行卡消费接口调用示例：
Map<String,Object> consumeParam = new HashMap<>();
String tradeId = "OUT_TEST" + System.currentTimeMillis() + "";
// (服务商交易订单号，保证唯一)outTradeNo
consumeParam.put("outTradeNo",tradeId);
// (交易金额，单位：元)totalAmount
consumeParam.put("totalAmount","0.01");
// (交易备注)remark
consumeParam.put("remark","sdk交易测试");
// (交易结果异步通知地址,示例：http://652679.api.com/notify)
consumeParam.put("notifyUrl","交易结果异步通知地址");
// (分账类型)ledger_flag
// ledger_flag传参值：
// REALTIME_SETTLE：实时分账
// DELAY_SETTLE：延时分账
// BALANCE_SPLIT：余额分账
consumeParam.put("ledger_flag","");
//（分账关系组）ledger_relation：
// 最多支持10组，
// 实时分账时该参数必传，且关系组大于1，小于等于10（list != null && 10 <= list.size > 1）
// 延时分账,余额分账 类型时此字段有值也无效，也可不传
// 实时分账类型时ledger_relation传参示例：
// List<Map> list = new ArrayList<>();
// Map map = new HashMap();//分账关系组1
// map.put("receive_no", "833103159990017");// 收账方(海科商户号)
// map.put("amt", "0.01");// 分账金额（单位：元）
// Map map1 = new HashMap();// 分账关系组2
// map1.put("receive_no", "833102654993185");
// map1.put("amt", "0.01");
// list.add(map);
// list.add(map1);
// consumeParam.put("ledger_relation",list);
consumeParam.put("ledger_relation",new ArrayList<Map>());
// （交易打印小票标识，只支持传1或2，其他值或不传则不打印小票）printFlag
// 1:打印一联小票
// 2:打印两联小票
consumeParam.put("printFlag","2");
// 结算商户编号，可空，默认为设备所属商编
consumeParam.put("merch_no","");
// this 为上下文，consumeParam为消费传参map
sdkController.toConsume(this,consumeParam);
}else if (requestCode == PERMISSION_REQUESTCODE_REVOKE) {
// 银行卡消费撤销传参示例：
Map<String, Object> revokeParam = new HashMap<>();
// (服务商交易订单号，保证唯一)outTradeNo
revokeParam.put("outTradeNo", "OUT_TESTRevoke" + System.currentTimeMillis() + "");
// （原消费交易订单号，此订单号为海科测订单号，在onConsumeSuccess（）回调方法中有返回）
revokeParam.put("tradeId", tranDetail.getTradeId());
revokeParam.put("notifyUrl", "交易（撤销）结果异步通知地址");
// （交易打印小票标识，只支持传1或2，其他值或不传则不打印小票）printFlag
// 1:打印一联小票
// 2:打印两联小票
revokeParam.put("printFlag", "2");
// 结算商户编号，可空，默认为设备所属商编
revokeParam.put("merch_no","");
// this 为上下文，revokeParam为撤销传参map
sdkController.toRevoke(this, revokeParam);
}else if (requestCode == PERMISSION_REQUESTCODE_REFUND) {
// 银行卡消费退货接口传参示例：
Map<String,Object> refundParam = new HashMap<>();
// (服务商交易订单号，保证唯一)outTradeNo
refundParam.put("outTradeNo","OUT_TESTRefund" + System.currentTimeMillis() + "");
// (退款金额，单位：元)refundAmount
refundParam.put("refundAmount","0.01");
// （原消费交易订单号，此订单号为海科测订单号，在onConsumeSuccess（）回调方法中有返回）
refundParam.put("tradeId",tranDetail.getTradeId());
// (交易备注)remark
refundParam.put("remark","sdk交易测试");
refundParam.put("notifyUrl","交易（退款）结果异步通知地址");
// （交易打印小票标识，只支持传1或2，其他值或不传则不打印小票）printFlag
// 1:打印一联小票
// 2:打印两联小票
refundParam.put("printFlag","2");
// 结算商户编号，可空，默认为设备所属商编
refundParam.put("merch_no","");
// this 为上下文，refundParam为退货传参map
sdkController.toRefund(this,refundParam);
}else if (requestCode == PERMISSION_REQUESTCODE_PREAUTH) {
// 银行卡预授权
Map<String,Object> preauthParam = new HashMap<>();
outTradeNo = "OUT_TESTauth" + System.currentTimeMillis() + "";
preauthParam.put("outTradeNo",outTradeNo);
preauthParam.put("totalAmount",et_amount.getText().toString().trim());
preauthParam.put("remark","sdk预授权交易测试");
preauthParam.put("notifyUrl","异步通知地址");
preauthParam.put("printFlag","1");
sdkController.toPreAuth(this,preauthParam);
}else if (requestCode == PERMISSION_REQUESTCODE_PREAUTHREVOKE) {
// 银行卡预授权撤销
if (tranDetail == null || TextUtils.isEmpty(tranDetail.getTradeId())) {
Toast.makeText(this, "请先进行预授权", Toast.LENGTH_SHORT).show();
return;
}
Map<String, Object> preAuthRevokeParam = new HashMap<>();
preAuthRevokeParam.put("outTradeNo", "OUT_TESTpreauthRevoke" + System.currentTimeMillis() + "");
preAuthRevokeParam.put("tradeId", tranDetail.getTradeId());
preAuthRevokeParam.put("notifyUrl", "交易结果异步通知地址");
preAuthRevokeParam.put("printFlag", "2");
sdkController.toPreAuthRevoke(this, preAuthRevokeParam);
}else if (requestCode == PERMISSION_REQUESTCODE_PREAUTHFINISH) {
// 银行卡预授权完成
if (tranDetail == null || TextUtils.isEmpty(tranDetail.getTradeId())) {
Toast.makeText(this, "请先进行预授权", Toast.LENGTH_SHORT).show();
return;
}
Map<String,Object> preAuthFinishParam = new HashMap<>();
preAuthFinishParam.put("outTradeNo","OUT_TESTpreauthfinish" + System.currentTimeMillis() + "");
preAuthFinishParam.put("finishAmount","0.01");
preAuthFinishParam.put("tradeId",tranDetail.getTradeId());
preAuthFinishParam.put("remark","sdk交易测试");
preAuthFinishParam.put("notifyUrl","交易结果异步通知地址");
preAuthFinishParam.put("printFlag","2");
preAuthFinishParam.put("ticketContent","这里是交易备注，银行卡预授权完成");
sdkController.toPreAuthFinish(this,preAuthFinishParam);
}else if (requestCode == PERMISSION_REQUESTCODE_PREAUTHFINISHREVOKE) {
// 银行卡预授权完成撤销
if (tranDetail == null || TextUtils.isEmpty(tranDetail.getTradeId())) {
Toast.makeText(this, "请先进行预授权完成", Toast.LENGTH_SHORT).show();
return;
}
Map<String, Object> preAuthFinishRevokeParam = new HashMap<>();
preAuthFinishRevokeParam.put("outTradeNo", "OUT_TESTpreauthfinishRevoke" + System.currentTimeMillis() + "");
preAuthFinishRevokeParam.put("tradeId", tranDetail.getTradeId());
preAuthFinishRevokeParam.put("notifyUrl", "交易结果异步通知地址");
preAuthFinishRevokeParam.put("printFlag", "2");
sdkController.toPreAuthFinishRevoke(this, preAuthFinishRevokeParam);
}}
// 获取终端序列号密文
// random：随机加密因子，被扫交易传客户付款码后6位
String random = "123456";
sdkController.getSecretText(random);
// 查询当前设备绑定的商户信息
sdkController.getMerchantInfo();
// 单笔交易查询 返回内容见onGetCardPayDetail（） 回调方法
// (服务商订单号)outTradeNo
sdkController.queryCardPayDetail(outTradeNo);
// 设备签到，注意：需要在onInitSuccess()回调方法中主动调用，传参为上下文对象
sdkController.toDeviceSignIn(this);5.SDK接口回调说明：
private class SDKCallback implements HkSdkCallback {
@Override
public void onError(String s, String s1) {
// 发生错误（具体详见6）
}
@Override
public void onInitSuccess() {
// SDK初始化成功
// 使用时，请在此方法中调用设备签到接口，示例：sdkController.toDeviceSignIn(this);
}
@Override
public void onSignInSuccess() {
// 设备下载交易参数成功，此时具备交易的条件。
}
@Override
public void onGetMerchantInfo(Map<String, Object> map) {
// 获取商户信息成功
// map中包含字段及说明：
// pn:设备在海科系统终端号
// sn:设备序列号
// merch_no:设备所属海科商户编号
// merch_name:设备所属海科商户名称
// merch_short_name:设备所属海科商户简称
// shop_name:设备所属店铺名称
}
@Override
public void onConsumeSuccess(String s) {
// 消费成功，返参为消费成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onRevokeSuccess(String s) {
// 撤销成功，返参为消费撤销成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onPreLicensingSuccess(String result) {
// 预授权成功，返参为消费撤销成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onPreLicensingRevokeSuccess(String result) {
// 预授权撤销成功，返参为消费撤销成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onPreLicensingDoneSuccess(String result) {
// 预授权完成成功，返参为消费撤销成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onPreLicensingDoneRevokeSuccess(String result) {
// 预授权完成撤销成功，返参为消费撤销成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onRefundSuccess(String s) {
// 退货成功。，返参为消费退货成功的交易报文，json格式
// 解析实体参考附件中TranDetail文件
}
@Override
public void onTicketUploadSuccess() {
// 交易电子签名上传成功
}
@Override
public void onTicketPrintSuccess() {
// 签购单打印成功
}
@Override
public void onGetCardPayDetail(String result) {
// 单笔交易详情返回结果，返参为交易明细信息
// 解析实体参考附件中TranDetail文件
}
@Override
public void onGetSecretText(String result) {
// result：获取终端序列号密文返回结果，长度为8
}}
6.错误码说明
FIRM_SDK_INIT_ERROR(“01”, “厂商SDK初始化失败”),
DEVICE_KEY_INIT_ERROR(“02”, “设备秘钥初始化失败”),
QUERY_DEVICE_DATA_ERROR(“03”, “查询设备系统参数失败”),
ACCESSID_IS_NULL_ERROR(“04”, “accessId为空”),
CONSUME_PARAM_IS_NULL(“05”, “消费传参为空”),
CONSUME_OUTTRADENO_IS_NULL(“06”, “消费传参(outTradeNo)为空”),
CONSUME_AMOUNT_IS_NULL(“07”, “消费传参(totalAmount)为空或不合法”),
DEVICE_CHECK_CARD_TIMEOUT(“08”, “设备检卡超时”),
DEVICE_CHECK_CARD_ERROR(“09”, “设备检卡错误”),
CONSUME_CANCEL(“10”, “用户取消”),
CONSUME_INPUT_EXPT(“11”, “输密过程异常”),
CONSUME_UPLOAD_EXPT(“12”, “上送交易出现异常”),
CONSUME_SYSTEM_EXPT(“13”, “上送交易系统异常”),
TICKET_UPLOAD_ERROR(“14”, “交易小票上传失败”),
TICKET_PRINT_ERROR(“15”, “交易小票打印失败”),
REVOKE_PARAM_IS_NULL(“16”, “消费撤销传参为空”),
REVOKE_OUTTRADENO_IS_NULL(“17”, “消费撤销传参(outTradeNo)为空”),
REVOKE_TRADEID_IS_NULL(“18”, “消费撤销传参(tradeId)为空”),
OLD_TRADE_NOT_FOUND(“19”, “原交易不存在”),
REFUND_PARAM_IS_NULL(“20”, “消费退货传参为空”),
REFUND_AMOUNT_IS_NULL(“21”, “消费退货传参(refundAmount)为空或不合法”),
REFUND_TRADEID_IS_NULL(“22”, “消费退货传参(tradeId)为空”),
SECRETTEXT_IS_NULL(“23”, “终端序列号密文获取失败”),
DCC_NOT_AUTH(“24”, “DCC未授权”),
PREAUTH_PARAM_IS_NULL(“25”, “预授权传参为空”),
PREAUTH_OUTTRADENO_IS_NULL(“26”, “预授权传参(outTradeNo)为空”),
PREAUTH_AMOUNT_IS_NULL(“27”, “预授权传参(totalAmount)为空或不合法”),
PREAUTHREVOKE_PARAM_IS_NULL(“28”, “预授权撤销传参为空”),
PREAUTHREVOKE_OUTTRADENO_IS_NULL(“29”, “预授权撤销传参(outTradeNo)为空”),
PREAUTHREVOKE_TRADEID_IS_NULL(“30”, “预授权撤销传参(tradeId)为空”),
PREAUTHFINISHREVOKE_PARAM_IS_NULL(“31”, “预授权完成撤销传参为空”),
PREAUTHFINISHREVOKE_OUTTRADENO_IS_NULL(“32”, “预授权完成撤销传参(outTradeNo)为空”),
PREAUTHFINISHREVOKE_TRADEID_IS_NULL(“33”, “预授权完成撤销传参(tradeId)为空”),
PREAUTHFINISH_PARAM_IS_NULL(“34”, “预授权完成传参为空”),
PREAUTHFINISH_AMOUNT_IS_NULL(“35”, “预授权完成传参(finishAmount)为空或不合法”),
PREAUTHFINISH_TRADEID_IS_NULL(“36”, “预授权完成传参(tradeId)为空”),
PREAUTHFINISH_OUTTRADENO_IS_NULL(“36”, “预授权完成传参(outTradeNo)为空”),
SDK_SYSTEM_ERROR(“99”, “系统异常”);
7.以下附件为最新对接资料：更新时间：2024.11.14
2025.3.4 更新sdk,增加刷卡预授权相关功能，见附件中 资料包 libs/SDK-release-v1.1.aar
