N950 EDC integration guide

Note: Translation in progress.

Antom 支持 Omnichannel（全渠道）支付，其中包含线下（In-Person）支付渠道，其允许使用线下 POS/Kiosk 上位机的商户通过集成接入 Antom 收款终端机，实现统一收单、多渠道资金归集与集中管理，提升运营效率与对账体验。本文为您介绍如何通过 Antom Omnichannel 集成 N950 EDC 机具，以接受线下支付。

支付流程

以下图片展示了如何通过 Antom Omnichannel 集成 N950 EDC 机具进行线下支付：

1. 买家选择商品并下单。
2. 检查支付终端状态。
   调用 diagnosis 接口检查支付终端状态，包括网络状态、打印机状态和全局状态。只有返回终端设备状态正常才可以进行后续操作。
3. 发起支付请求。
   调用 pay 接口发起支付请求。
4. 获取支付结果。
   如果超时未收到支付响应，您可以调用 inquiryPayment 接口来查询支付状态。
5. （可选）退款。
   当交易需要退款时，您可以调用 refund 接口发起退款请求。仅 Wi-Fi 局域网通信模式
6. （可选）获取退款结果。仅 Wi-Fi 局域网通信模式
   如果超时未收到退款响应，您可以调用 inquiryRefund 接口来查询退款结果。

集成准备

为顺利完成支付终端的集成，请按以下步骤准备：

1. 联系 Antom 商务专员完成签约及设备采购、获取 SDK 资源包。
2. 在两种通信模式中选择一种适合您的模式，集成后不可更改。
3. 配置通信接口端点：仅 Wi-Fi 局域网通信模式
   接口端点格式：http://{terminal_static_ipAddress}:8344/{version}/{restfulPath}（其中 terminal_static_ipAddress 为您的终端设备连接的网络局域网静态 IP）
4. 完成线下终端机具的密钥交换：

• 私钥：您可使用支付宝密钥工具生成生产环境的公私钥。生成私钥后，请务必保存您的私钥信息。 按照以下操作使用 OpenSSL 生成密钥对并本地保存私钥（POS 私钥）：

$ openssl
OpenSSL> genrsa -out rsa_private_key.pem 2048
OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt
OpenSSL> rsa -in rsa_private_key.pem -pubout -out  rsa_public_key.pem
OpenSSL> exit

• 公钥：通过邮件与 Antom 商务专员交换您生成的生产环境公钥。Antom 商务专员获得您的生产环境公钥后，会配置为您 ClientID，并将 Antom 公钥和 ClientID（支付终端的序列号 SN）共享给您。

机具通信模式选择

您需先了解集成的 POS / Kiosk 上位机适合哪种通信选型，随后集成一种通信模式：

注意：您只能选择其中一种通信模式进行集成。

支付终端设备首次配置

按照以下步骤完成支付终端设备的首次配置：

1. 硬件检查：收到设备后，请确认设备、电源、手册齐全。联调和集成中设备建议分发给您的专业开发、测试人员。

注意： Newland 终端设备不含 USB 数据线和小票收据，您需要自备合适的配件。

2. 开机联网：

• 连接 Type C 电源并启动设备。
• 设置 Wi-Fi 或网线（需与 POS 同网络），配置静态 IP 地址。仅 Wi-Fi 局域网通信模式
• 如选择 USB 通信模式，请确保准备一条 Type C 传输线从终端设备连接到您的上位机 POS/Kiosk。仅 USB 连线通信模式
• 终端机设备不带小票收据，建议您自行准备 5.5cm-5.7cm 宽度的小票收据。

3. 入驻 D-store 并安装 App：

• 您需要入驻 D-store Console 用于线下机具的管理。
• 联系 Antom 商务专员下载 D-store Payment Terminal App（最新版本为 1.6.0）。
• 完成 D-store Console 入驻后，按照 创建门店 > POS > 设备 路径配置支付终端新设备，获取下载二维码及登录密码。

• 在 D-store 侧完成创建门店后把 D-store 门店 ID 发送给 Antom 商务专员以完成线下渠道报备。

4. 记录序列号 SN：在终端背面或设置中查找 SN，用于接口请求的 Client-Id 字段。

设置静态 IP 地址 仅 Wi-Fi 局域网通信模式

在设置静态 IP 地址之前，请联系 Antom 技术支持为终端分配一个固定的 IP 地址。设置步骤如下：

1. 选择网络：选择门店正在使用的 Wi-Fi 网络。
2. 进入设置：

• 点击该网络以输入密码，或点击右上角的铅笔按钮以编辑 Wi-Fi 设置。
• 如果未看到这些配置选项，请点击 advanced options 以展开设置菜单。

3. 配置 IP 设置：在 IP settings 选项下，选择 static。
4. 输入网络信息：

• 在 IP address 输入框内输入 Antom 分配给您的固定 IP 地址。
• 在 Gateway 输入框内输入从 POS 获取的 gateway 地址。

完成以上步骤后，即可开始 API 开发与测试。

集成步骤

按照以下步骤实现您的 POS 应用程序通过本地网络以 HTTP 协议与终端设备进行通信：

1. 商户 POS 应用向终端设备发起支付请求：

• Wi-Fi 局域网通信：通过局域网和 HTTPS 接口调用触发设备上的支付流程。
• USB 连线通信：通过集成客户端 SDK 和机具连线的方式调用触发设备上的支付流程。

2. 终端设备将该请求转发至 PDS 支付平台执行交易处理。

3. 交易结果将通过同步响应实时返回至您的系统。

步骤 1：集成支付终端接口

按照以下步骤集成支付终端接口：

• 配置终端网络 仅 Wi-Fi 局域网通信模式：使用 DHCP 保留或手动配置静态 IP 地址，完成终端的网络设置。
• 确保本地通信安全：对请求信息进行加密处理并生成数字签名，保障数据传输安全。
• 构建支付流程：使用终端的 IP 地址（例如：http://192.168.71.58:8344/{path}）发送支付请求，完成交易处理。参阅接口概述了解报文结构和端到端的报文传输工作流程。

在支付过程中，POS 系统可能因网络超时或重复提交等原因，多次发送同一 paymentRequestId 的支付请求。Antom 通过幂等性键（idempotency key）确保同一支付请求仅被处理一次，有效防止重复扣款，保障用户资金安全。更多信息请参阅幂等性。

相关接口

以下表格展示了相关的接口信息以及调用方向，您可以根据需求调用接口：

1. 初始化 SDK 仅 USB 连线通信模式

在 USB 连线通信模式下，您需调用 initConnection 接口来初始化连接并检查 POS 与支付终端之间的通信。确保在创建支付请求之前先调用 initConnection 接口。

初始化之前，如您的 POS 系统包含扫描/配对机具，请确保您的系统允许一台 POS 设备配对多台终端机具。扫描机具成功连接后，您会收到如下设备信息：

("mClass":0, "mInterfaces": null, "mManufacturerName": "newland", 
"mName":" /dev/bus/usb/001/042", "mProductId": 11520, 
"mProductName": "QCM2290-IDP _SN: 35xxxxx", "mProtocol": 0, 
"mSubclass": 0, "mVendorId": 6353, "mVersion": "4.19")

为了在您的应用和 USB 支付终端之间建立稳定可靠的通信，您需要遵循以下步骤来检查设备权限、判断连接模式：

1. 强制执行以下方法检查并请求 USB 设备的访问权限：

if (UsbDeviceHelper.checkAndRequestUsbPermission(this, usbDevice)) {
    permissionGranted(usbDevice)
}else{
    Logger.d("选中一个USB 但是没有权限$usbDevice", tag = "UsbHotActivity")
}

2. 强制执行以下方法方法检查 USB 设备是否处于配件模式。

• 如果此方法返回 true，则设备已处于配件模式，您可以直接开始数据通信。
• 如果返回 false，则需要执行后续步骤切换到配件模式。

private fun isInAccessoryMode(device: UsbDevice): Boolean {
    return (device.getVendorId() == 0x18d1) &&
    (device.getProductId() >= 0x2D00 &&
            device.getProductId() <= 0x2D05)
}

3. 如果设备未处于配件模式，需要检查设备是否支持配件协议，并将其切换到配件模式。

1. 强制执行以下方法打开设备连接并检查协议支持：

Log.d(TAG, "当前非配件模式，判断是否支持配件协议")
val connection: UsbDeviceConnection = usbManager!!.openDevice(device)
val protocolSupported: Boolean = checkAccessoryProtocol(connection)
Log.d(TAG, "设备 $device " + device.deviceName + " 是否支持配件协议: " + protocolSupported)
connection.close()
if (protocolSupported) {
    Log.d(TAG, "支持配件模式，这里发送指令，改成配件模式，并重新连接")
    UsbDeviceHelper.initAccessory(this, device, 1000)
} else {
    Log.d(TAG, "不支持配件模式")
    runOnUiThread {
        Toast.makeText(this@UsbHotActivity, "不支持配件模式", Toast.LENGTH_SHORT).show()
    }
}

b. 强制执行以下方法通过控制传输查询设备是否支持 Android 配件协议：

fun checkAccessoryProtocol(connection: UsbDeviceConnection): Boolean {
    // 发送 Android 配件协议查询请求
    val buffer = ByteArray(2)
    val requestType = 0xC0 // 方向：设备到主机，类型：厂商，接收者：设备
    val request = 51 // ACCESSORY_GET_PROTOCOL
    val value = 0
    val index = 0
    val timeout = 200

    val ret = connection.controlTransfer(
        requestType, request, value, index, buffer, buffer.size, timeout
    )

    if (ret == 2) {
        val protocolVersion = (buffer[1].toInt() shl 8) or buffer[0].toInt()
        Log.d(TAG, "Accessory Protocol Version: $protocolVersion")
        return protocolVersion >= 1
    }
    return false
}

c. 如果设备支持配件协议，强制执行以下方法将设备切换到配件模式：

 fun initAccessory(context: Context, device: UsbDevice, timeOut: Int): Boolean {
        // 打开设备连接
        val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
        val connection = usbManager?.openDevice(device) ?: return false

        try {
            // 使用同一个connection进行所有控制传输
            with(connection) {
                // 初始化字符串控制传输
                controlTransfer(
                    0x40, 52, 0, 0, "alipay".toByteArray(),
                    "alipay".length, timeOut
                )
                controlTransfer(
                    0x40, 52, 0, 1, "terminal".toByteArray(),
                    "terminal".length, timeOut
                )
                controlTransfer(
                    0x40, 52, 0, 2, "Payment Terminal".toByteArray(),
                    "Payment Terminal".length, timeOut
                )
                controlTransfer(0x40, 52, 0, 5, "42".toByteArray(),
                    "42".length, timeOut
                )
                // 启动配件模式
                controlTransfer(0x40, 53, 0, 0, ByteArray(0), 0, timeOut)
            }
            return true
        } catch (e: Exception) {
            Logger.e("initAccessory error: ${e.message}")
            return false
        } finally {
            // 最后关闭连接
            connection.close()
        }
    }

2. 检查支付终端状态

在 Wi-Fi 局域网通信模式下，您需调用 diagnosis USB 连线通信模式 或 diagnosis Wi-Fi 局域网通信模式 接口检查支付终端状态，包括网络状态、打印机状态和全局状态。只有返回终端设备状态正常才可以进行后续操作。

3. 发起支付请求

买家选择商品并下单后，调用 pay USB 连线通信模式 或 pay Wi-Fi 局域网通信模式 接口发起支付请求。您可以通过 paymentMethod 参数指定支付方式，支付方式枚举值请参阅支持的支付方式。

4. 获取支付结果

如果超时未收到支付响应，您可以调用 inquiryPayment USB 连线通信模式 或 inquiryPayment Wi-Fi 局域网通信模式 接口来查询支付状态。

（可选）5. 退款 仅 Wi-Fi 局域网通信模式

当交易需要退款时，您可以调用 refund 接口发起退款请求。如果超时未收到退款响应，您可以调用 inquiryRefund 接口来查询退款结果。在调用 refund 接口之前，请先确认您的终端设备所属的运行模式。按照以下步骤检查您的设备配置：

1. 登录 D-store Console 门户。
2. 选择 POS > 设备。
3. 找到已创建的支付终端，点击 编辑设备。
4. 查看 顾客模式 的状态：点击以启用或停用。

退款支持说明

POS - 终端机启用或停用 顾客模式 对于退款的支持情况如下：

• 停用 顾客模式：此时仅支持调用 refund 接口发起全额退款，不支持部分退款。 如未集成 refund 接口，店长及以上权限的账户可以在终端机上的 D-store POS 应用中选择订单进行全额退款或部分退款。
• 启用 顾客模式：启用后，终端机将始终停留在首页，用户无法操作或查看终端机上的支付记录。此时支持调用 refund 接口发起全额退款，但只能进行一次部分退款。

步骤 2：进行生产验收测试

联系 Antom 商务专员获取终端设备集成测试用例，完成所有测试后即可正式上线。

步骤 3：对账

交易完成后，使用 Antom 提供的财务报告进行对账。有关如何对账和 Antom 结算规则的更多信息，请参阅对账。

支持的支付方式

查看 N950 EDC 机具集成支持的支付方式及枚举值：

• 新加坡
• 马来西亚

商户常见使用场景

Wi-Fi 通信正向场景

1. 店员发起支付：在已经集成终端机的 POS 页面侧， 选择线下支付方式（如刷卡、二维码等）。
2. POS 端处理：POS 系统将交易信息（如金额、订单号等）进行加密，并添加数字签名以确保数据完整性和防篡改。
3. 发送交易请求：POS 将加密后的交易请求报文通过 API 发送至支付终端。
4. 支付终端验证：支付终端接收请求后，解密数据并验证签名（确保数据来自合法 POS 且未被修改）。
5. 向 D-store Payment Terminal App 发起支付指令：终端将交易报文封装后发送至 D-store Payment Terminal App 服务器进行支付处理，并轮询查询支付结果，直到获取到最终支付状态（如成功、失败等）。

注意：买家支付后，如果由于网络问题导致未及时收到收单机构的支付结果，出现订单超时但买家侧已扣款的情况，则订单状态以终端设备显示的支付结果为准。

6. 返回响应前处理：支付终端在准备好响应时，对返回结果（如支付状态、金额等）进行加密和签名。
7. 返回 POS 系统：终端将加密的响应报文发送回 POS 系统。
8. POS 端验证结果：POS 系统解密响应报文，验证签名正确性，确保数据未被篡改，并提取完整支付结果。
9. 打印交易凭证：根据支付结果（如交易成功或失败），POS 系统打印交易凭条供顾客留存。终端机也可设置打印支付小票凭条（买家、商户小票）。

Wi-Fi 退款场景

Wi-Fi 退款场景分为集成场景和无集成场景两种情况：