跳到主要内容
版本：Next

POS 统一SDK接入指南

概述​

本指南适用于 POS 终端渠道接入，支持以下渠道：

  • CoGoLinks：CoGoLinks POS 终端

快速开始​

1. 添加依赖​

Android 项目：

dependencies {
    implementation(files("libs/cogolinks-payment-unify-sdk-1.0.5.jar"))
}

Java 项目：

dependencies {
    implementation files('libs/cogolinks-payment-unify-sdk-1.0.5.jar')
}

SDK下载​

注意：SDK JAR 已包含所有必需依赖，无需额外添加。

2. 初始化 SDK​

import com.cogolinks.payment.sdk.pos.UnifySDK;

// 初始化 CoGoLinks 渠道
UnifySDK.init("CoGoLinks", "192.168.10.60", "8090");

3. 调用接口​

import org.json.JSONObject;

// 构建请求
JSONObject request = new JSONObject();
request.put("api", "/sale");
request.put("orderAmount", "10.00");
request.put("merchantOrderNo", "ORDER-20250101-001");
request.put("merchantSerialNo", "your-serial-no");
request.put("paymentType", "01");
request.put("currency", "HKD");

// 执行请求
String response = UnifySDK.execute(request.toString());

// 解析响应
JSONObject responseJson = new JSONObject(response);
if ("00".equals(responseJson.optString("code"))) {
    JSONObject data = responseJson.optJSONObject("data");
    // 处理成功响应
} else {
    // 处理失败响应
}

支持的接口​

POS 端渠道支持以下统一接口：

接口路径功能说明CoGoLinks
/sale消费交易✅
/revoke撤销交易✅
/refund退款交易✅
/query/transaction查询交易✅
/cancel/transaction取消交易✅

常用场景​

场景1：消费交易​

// 初始化 CoGoLinks
UnifySDK.init("CoGoLinks", "192.168.10.60", "8090");

// 消费交易
JSONObject request = new JSONObject();
request.put("api", "/sale");
request.put("paymentType", "01");  // 01-银行卡
request.put("merchantOrderNo", "ORDER-001");
request.put("merchantSerialNo", "SERIAL-001");
request.put("orderAmount", "100.00");
request.put("currency", "HKD");

String response = UnifySDK.execute(request.toString());

场景2：撤销交易​

JSONObject request = new JSONObject();
request.put("api", "/revoke");
request.put("originalTransactionNo", "原交易流水号");
request.put("merchantSerialNo", "SERIAL-002");
request.put("orderAmount", "100.00");
request.put("currency", "HKD");

String response = UnifySDK.execute(request.toString());

场景3：退款交易​

JSONObject request = new JSONObject();
request.put("api", "/refund");
request.put("refundOrderAmount", "50.00");
request.put("merchantSerialNo", "SERIAL-003");
request.put("currency", "HKD");

String response = UnifySDK.execute(request.toString());

场景4：查询交易​

JSONObject request = new JSONObject();
request.put("api", "/query/transaction");
request.put("merchantSerialNo", "SERIAL-001");

String response = UnifySDK.execute(request.toString());

核心 API​

执行请求​

// 方式1：使用已初始化的渠道和IP
String response = UnifySDK.execute(String requestJson);

// 方式2：指定渠道和IP（无需初始化）
String response = UnifySDK.execute(String requestJson, String channel, String posIp);

// 方式3：指定渠道、IP和端口
String response = UnifySDK.execute(String requestJson, String channel, String posIp, String posPort);

渠道管理​

// 获取支持的渠道列表
List<String> channels = UnifySDK.getSupportedChannels();

// 检查渠道是否支持
boolean supported = UnifySDK.isChannelSupported("CoGoLinks");

配置管理​

// 保存配置到本地（持久化，会替换本地已有配置）
boolean success = UnifySDK.saveChannelConfig("CoGoLinks", configJsonString);

// 注入配置到内存（临时，不持久化）
UnifySDK.injectChannelConfig("CoGoLinks", configJsonString);

// 从本地文件加载配置
UnifySDK.loadChannelConfigFromLocal("CoGoLinks");

// 检查配置是否存在
boolean exists = UnifySDK.hasChannelConfig("CoGoLinks");

// 移除配置
UnifySDK.removeChannelConfig("CoGoLinks");

// 刷新配置（先移除再注入）
UnifySDK.refreshChannelConfig("CoGoLinks", newConfigJsonString);

远程配置​

// 设置配置列表URL（用于自动下载）
UnifySDK.setChannelListUrl("https://example.com/channelList.json");

// 设置配置保存目录
UnifySDK.setConfigDir("/path/to/configs");

// 手动触发配置下载
UnifySDK.downloadConfigs();

响应格式​

所有接口返回统一格式：

{
  "code": "00",
  "msg": "成功",
  "data": {
    "transactionNo": "交易流水号",
    "orderAmount": "100.00",
    "merchantOrderNo": "商户订单号",
    "merchantSerialNo": "商户流水号",
    // 其他业务字段...
  }
}

响应码说明：

  • 00：成功
  • 01：失败
  • 02：结果未知，需要查询确认
  • 22：已关单

配置管理​

配置来源优先级​

  1. 内存配置（通过 injectChannelConfig() 注入）
  2. 本地下载文件（通过 saveChannelConfig() 或远程下载保存）
  3. SDK预置配置（resources目录中的配置文件）

配置保存位置​

  • Android：/data/data/{包名}/cache/.unify_sdk/configs/
  • Java：{user.home}/.unify_sdk/configs/
  • 自定义：通过 setConfigDir() 设置

自动下载配置​

SDK 初始化时会自动从远程下载配置（如果配置了URL）：

  • 默认URL：http://unifysdk.oss-cn-hangzhou.aliyuncs.com/channelList.json?...
  • 自定义URL：通过 setChannelListUrl() 设置
  • 下载的配置自动保存到本地，优先级高于SDK预置配置
  • 下载在后台线程执行，不会阻塞主线程

注意事项​

1. 金额单位​

  • 统一以元为单位传入（如 orderAmount: "100.00"）
  • CoGoLinks 渠道：直接使用元单位
  • 响应中的金额会自动转换回元

2. 线程安全​

  • SDK 支持多线程并发调用
  • 建议在应用启动时初始化一次，后续直接调用 execute()
  • 接口路径与统一接口路径一致
  • 金额直接使用元单位
  • 响应格式为嵌套结构（data 字段包含业务数据）

常见问题​

Q1: 如何切换渠道？​

A: 每次调用时指定渠道，或重新调用 init()：

// 方式1：每次调用时指定
UnifySDK.execute(requestJson, "CoGoLinks", "192.168.10.60", "8090");

// 方式2：重新初始化
UnifySDK.init("CoGoLinks", "192.168.10.60", "8090");
UnifySDK.execute(requestJson);

Q2: 如何判断交易是否成功？​

A: 检查响应中的 code 字段：

JSONObject response = new JSONObject(result);
String code = response.optString("code");
if ("00".equals(code)) {
    // 交易成功
} else {
    // 交易失败
}

Q3: 配置保存后如何验证是否生效？​

A: 配置保存后会自动清除缓存并重新加载，可通过以下方式验证：

// 方式1：检查配置是否存在
boolean exists = UnifySDK.hasChannelConfig("CoGoLinks");

// 方式2：调用接口验证配置是否生效
// 如果配置中有特殊字段或行为，调用接口后检查响应是否符合预期

Q4: 如何查看配置保存位置？​

A: 配置保存位置取决于平台：

  • Android：/data/data/{包名}/cache/.unify_sdk/configs/{ChannelName}.json
  • Java：{user.home}/.unify_sdk/configs/{ChannelName}.json
  • 自定义：通过 setConfigDir() 设置的目录

更多文档​