弹窗模式

2025-03-12 06:47

EDC（电子数据捕获）设备广泛应用于各种零售和服务行业，尤其在餐饮、超市和便利店等场所。本文为您介绍如何通过集成 Antom SDK 实现 EDC 终端支持弹窗模式，从而快速、安全地处理顾客的支付需求，提升交易效率和顾客体验。

集成步骤

获取硬件设备
安装 EasyCard App
安装 SDK 资源包
初始化 SDK
发送设备指令
数据透传

步骤 1：获取硬件设备

如何获取机具设备请联系 Antom 商务专员了解详细信息。

步骤 2：安装 EasyCard App

请联系 Antom 商务专员获取 EasyCard App 的安装说明。获取设备并完成配置后，您可以按以下步骤完成 SDK 集成。

步骤 3：安装 SDK 资源包

版本要求：

Android 4.4（API level 19）或更高版本。
Java 1.8 及以上。

请按照以下步骤通过 Maven 集成 SDK 资源包。

添加 Maven 库：

在项目根目录的 build.gradle 文件中增加如下代码配置：

copy
// 添加 Maven 库
maven {
    credentials {
        username "antomsdk@aliyun.com"
        password "Admin1234"
    }
    url "https://globaltech.alipay.com/api/v1/file/repository/antom/"
}

添加 Maven 依赖：

使用下面的代码在 build.gradle 文件中添加依赖项。

copy
// 在应用的 build.gradle 中  
// 如果与现有 SDK 存在冲突，请将其排除
dependencies {
    implementation 'com.alipay.antom.sdk:instore-core:${antom_version}'
    implementation 'com.alipay.antom.sdk:instore-edc-cmd:1.0.0'
    implementation 'com.alipay.antom.sdk:foundation-jsengine:1.0.0'
}

将下面代码中 ANTOM_VERSION 的值替换为最新版本号 1.20.1，以便在 build.gradle 文件中外部化版本号，进行代码升级管理。

copy
ext {
    antom_version = 'ANTOM_VERSION'
}

步骤 4：初始化 SDK

建议在应用启动时调用 init 接口进行全局初始化，以确保设备能够快速响应。

通过使用 AMSEDCGlobalConfiguration 并指定基础配置来创建 SDK 实例。配置对象包括以下参数：

参数名称

类型

是否必需

描述

options

Map

是

预留扩展参数信息。它包含以下参数：

provider：连接设备的类型，必传，String 类型。
merchantId：商户的 ID 号，必传，String 类型。

initCallback

InitCallback

是

初始化回调函数。它包含以下参数：

eventCode：相关结果码，String 类型。
result：结果的具体信息，String 类型。

通过调用 InitCallback 可以得到 onInitResult 回调事件。以下示例代码展示了如何处理回调事件onInitResult：

copy
void onInitResult(String code, String result)

以下示例代码展示了如何实例化 SDK：

copy
AMSEDCGlobalConfiguration globalConfiguration = new AMSEDCGlobalConfiguration()
globalConfiguration.setOption("provider","KICC");
globalConfiguration.setOption("merchantId","xxxxxxx");
globalConfiguration.setInitCallback(new AMSEDCInitCallback() {
    @Override
    public void onInitResult(String code, String message) {
        if("INIT_SUCCESS".equals(code)){

        }
    }
});
AMSEDCPayment.init(this.getApplicationContext(), globalConfiguration);

步骤 5：发送设备指令

您可以调用 sendCommand 接口，给指定的 EDC 设备发送指令和数据，如 commandName=xxxx，具体实现的指令请参考机具指令。

向设备发送 DeviceCommandRequest 请求后，您将收到 DeviceCommandCallback 响应。发送DeviceCommandRequest 请求涉及以下参数：

参数名称	类型	是否必需	描述
provider	String	是	设备商，指定为 KICC。
commandName	String	是	指令名称。有效指令包括：发起支付（Purchase）取消支付（PurchaseCancel）现金报税（CashReceipt）取消现金报税（CashReceiptCancel）查询最近一笔交易（GetLastTransaction）
requestId	String	是	请求 ID。
commandRequestParams	JSONObject	否	指令请求参数。
options	Map<String, String>	否	预留扩展参数。

以下代码展示了一个 DeviceCommandCallback 响应的示例，其中包含以下参数：

CommandResult ：指令结果，包含以下参数：

responseData：返回结果，JSONObject 类型。

onCommandFailed：设备响应失败。
onBusinessFailed：业务响应失败。

copy
void onSuccess(CommandResult result);

/**
 * 指令响应失败
 */
void onCommandFailed(CommandFailInfo commandFailInfo);

/**
 * 指令响应成功，但是业务响应错误
 */
void onBusinessFailed(CommandResult result);

以下代码展示了一个 responseData 的示例：

copy
{
  "requestId": "123456XXXX",
  "paymentAmount": {
    "value": "$TOTAL_AMOUNT",
    "currency": "KRW"
  },
  "taxAmount": {
    "value": "$TAX",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "$TIP",
    "currency": "KRW"
  },
  "creditPayPlan": {
    "installmentNum": "0"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "XXX"
  },
  "acquirerInfo": {
    "acquirerResultCode": "$RESULT_CODE",
    "acquirerResultMessage": "$RESULT_MSG",
    "acquirerTransactionId": "$TRAN_SERIALNO",
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerMerchantId": "$SHOP_TIDMERCHANT_NUM",
    "acquirerApprovalNum": "$APPROVAL_NUM",
    "acquirerName": "KICC",
    "notice": "               매입사제출테스트 거래임",
    "acquirerMetaData":"ImNyZWRpdFBheVBsYW4iOiB7CiAgICAiaW5zdGFsbG1lbnROdW0iOiAiMCIKICB9LAogICJyZXN1bHQiOiB7CiAgICAicmVzdWx0Q29kZSI6ICJTVUNDRVNTIiwKICAgICJyZXN1bHRNZXNzYWdlIjogIiIKICB9Cg=="
  },
  "paymentResultInfo": {
    "cardBin": "52364979",
    "paymentMethodId": "",
    "issuerCode": "$CARD_NAME",
    "funding": "DEBIT/CREDIT/PREPAID",
    "paymentMethodRegion": "KR",
    "paymentMethodType": "CARD/CONNECT_WALLET/SAMSUNGPAY"
  }
}

以下代码展示了一个 onBusinessFailed 的示例：

copy
{
  "requestId": "c9d707ee-639d-4bf2-9a43-cc36c0a3beac",
  "result": {
    "resultCode": "PROCESS_FAIL",
    "resultMessage": "Please check network"
  },
  "acquirerInfo": {}
}

超时

以下是各指令的默认超时时间。

指令场景	默认值/秒
支付 Purchase	95（当金额超过 50000 KRW 时需要签名，此时默认值为 115）注意：如果需要为 Purchase 指令自定义超时时间，请确保设置的超时时间不低于其默认值。
支付取消 PurchaseCancel	85
报税 CashReceipt	65
取消现金报税 CashReceiptCancel	65
查询上一笔交易时间 GetLastTransaction	5

调用 sendCommand 接口的示例代码

copy
DeviceCommandRequest deviceCommandRequest = new KICCCommandRequest();
deviceCommandRequest.setCommandName("Purchase");
deviceCommandRequest.setCommandRequestParams(new JSONObject("{\n" +
                "  \"requestId\": \"123456XXXX\",\n" +
                "  \"paymentAmount\": {\n" +
                "    \"value\": \"104\",\n" +
                "    \"currency\": \"KRW\"\n" +
                "  },\n" +
                "  \"taxAmount\": {\n" +
                "    \"value\": \"9\",\n" +
                "    \"currency\": \"KRW\"\n" +
                "  },\n" +
                "  \"tipAmount\": {\n" +
                "    \"value\": \"0\",\n" +
                "    \"currency\": \"KRW\"\n" +
                "  },\n" +
                "  \"creditPayPlan\": {\n" +
                "    \"installmentNum\": \"0\"\n" +
                "  },\n" +
                "  \"paymentExpiryTime\": \"30\",\n" +
                "  \"acquirerInfo\": {\n" +
                "    \"acquirerTerminalId\": \"0788888\",\n" +
                "    \"acquirerRegistrationNo\": \"0216001234\"\n" +
                "  }\n" +
                "}"));
DeviceCommandCallback callback = new DeviceCommandCallback() {
    @Override
    public void onSuccess(CommandResult result) {
        JSONObject responseData = result.getResponseData();
        Log.d(TAG, "onSuccess responseData: " + responseData);
    }

    @Override
    public void onCommandFailed(CommandFailInfo commandFailInfo) {
        Log.e(TAG, "error:" + commandFailInfo.errorCode + "：" + commandFailInfo.errorMessage);
    }

    @Override
    public void onBusinessFailed(BusinessFailInfo businessFailInfo) {
        Log.e(TAG, "error" + businessFailInfo.getErrorCode() + "：" + businessFailInfo.getErrorMessage());
    }
};
mAMSEDCPayment.sendCommand(activity, deviceCommandRequest, callback);

步骤 6：数据透传

调用 handleIntent 接口，接收机具通过商户 Activity 回传的参数。

注意：对于 KICC 设备，如果未调用此接口，将导致 sendCommand 接口在无响应端超时报错。

在商户的 Activity 类的实现中，以下是一个处理返回结果的示例代码：

copy
// 在商户的 Activity 类中
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(AMSEDCPayment.handleIntent(requestCode,resultCode,data)){
        return;
    }
}

机具指令

以下为 KICC 设备支持的指令模式，统一用 sendCommand 接口来调用，具体信息请参考发送设备指令。

发起支付

使用 Purchase 指令来发起支付，以下为其包含的参数及示例代码。

请求参数

参数名称	是否必需	说明	示例
requestId	是	商户侧交易号。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
creditPayPlan.installmentNum	是	分期付款的期数。	无
paymentExpiryTime	否	支付等待超时时间，默认为 30s。	无
acquirerInfo.acquirerTerminalId	是	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	是	加盟店营业执照号码。	无

以下代码是请求报文的示例：

copy
{
  "requestId": "123456XXXX",
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "creditPayPlan": {
    "installmentNum": "0"
  },
  "paymentExpiryTime": "30",
  "acquirerInfo": {
    "acquirerTerminalId": "0788888",
    "acquirerRegistrationNo": "0216001234"
  }
}

返回参数

参数名称	是否必需	说明	示例
requestId	是	商户侧交易号。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
taxAmount.value	是	增值税金额。	无
taxAmount.currency	是	增值税的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
creditPayPlan.installmentNum	是	分期付款的期数。	无
result.resultCode	是	支付结果码。	无
result.resultMessage	是	支付结果信息。	无
acquirerInfo.acquirerResultCode	否	收单机构返回的结果码。	无
acquirerInfo.acquirerResultMessage	否	收单机构返回的消息描述。	无
acquirerInfo.acquirerTerminalId	是	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	是	加盟店营业执照号码。	无
acquirerInfo.signData	否	签名数据（仅在已签名的交易中传送）。	无
acquirerInfo.notice	否	交易描述。	`" 매입사제출테스트 거래임"` `"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"` `"전표:효력없음 userLoginId 000000000602"`
acquirerInfo.acquirerTransactionId	是	收单机构的交易序列号。	无
acquirerInfo.acquirerMerchantId	是	门店在收单机构的商户号。	无
acquirerInfo.acquirerName	是	收单机构名称。	`KICC`
acquirerInfo.acquirerMetaData	是	收单机构返回的原始数据，在进行退款时必须传入。	无
acquirerInfo.acquirerApprovalNum	是	KICC 的交易批准号码。	无
paymentResultInfo.cardBin	否	支付卡 BIN（银行卡前八位）。在卡片支付时需要获取卡 BIN 信息。	无
paymentResultInfo.paymentMethodId	否	识别号码。钱包支付场景下需要获取付款码。	无
paymentResultInfo.issuerCode	是	发卡行代码。详细列表请查看附件。📎전체 카드사 신용카드_발급사 매입사 정보(2023.07.25 기준) .xlsx	无
paymentResultInfo.funding	是	卡的资金类型包括：借记卡、信用卡和预付卡。注意：当使用国际卡、钱包和 Samsung PAY 支付时，此参数的值为空。	无
paymentResultInfo.paymentMethodRegion	是	代表支付方式所在国家或地区的区域代码。此参数的值为两位字母的 ISO 国家代码或 `GLOBAL`。	无
paymentResultInfo.paymentMethodType	是	支付方式。	无
extendInfo.AD1	否	收单机构的额外注释 1。	无
extendInfo.AD2	否	收单机构的额外注释 2。	无

以下代码是响应报文的示例：

copy
{
  "requestId": "123456XXXX",
  "paymentAmount": {
    "value": "$TOTAL_AMOUNT",
    "currency": "KRW"
  },
  "taxAmount": {
    "value": "$TAX",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "$TIP",
    "currency": "KRW"
  },
  "creditPayPlan": {
    "installmentNum": "0"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "XXX"
  },
  "acquirerInfo": {
    "acquirerResultCode": "$RESULT_CODE",
    "acquirerResultMessage": "$RESULT_MSG",
    "acquirerTransactionId": "$TRAN_SERIALNO",
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerMerchantId": "$SHOP_TIDMERCHANT_NUM",
    "acquirerApprovalNum": "$APPROVAL_NUM",
    "acquirerName": "KICC",
    "notice": "               매입사제출테스트 거래임",
    "acquirerMetaData":"ImNyZWRpdFBheVBsYW4iOiB7CiAgICAiaW5zdGFsbG1lbnROdW0iOiAiMCIKICB9LAogICJyZXN1bHQiOiB7CiAgICAicmVzdWx0Q29kZSI6ICJTVUNDRVNTIiwKICAgICJyZXN1bHRNZXNzYWdlIjogIiIKICB9Cg=="
  },
  "paymentResultInfo": {
    "cardBin": "52364979",
    "paymentMethodId": "",
    "issuerCode": "$CARD_NAME",
    "funding": "DEBIT/CREDIT/PREPAID",
    "paymentMethodRegion": "KR",
    "paymentMethodType": "CARD/CONNECT_WALLET/SAMSUNGPAY"
  }
}

取消支付

使用 PurchaseCancel 指令来取消支付，以下为其包含的参数及示例代码。

请求参数

参数名称	是否必需	说明	示例
requestId	是	商户侧的取消 ID。针对每个请求，requestId 具有唯一性。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
creditPayPlan.installmentNum	否	分期付款的期数。	无
acquirerInfo.acquirerMetaData	是	收单机构返回的原始数据。将 Purchase 指令中返回的 acquirerInfo.acquirerMetaData 的值传入此参数。	无
acquirerInfo.acquirerTerminalId	否	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	否	加盟店营业执照号码。	无

以下是请求报文的示例：

copy
{
  "requestId":"123456XXXX",
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "creditPayPlan": {
    "installmentNum":"0"
  },
  "acquirerInfo": {
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerMetaData":"ImNyZWRpdFBheVBsYW4iOiB7CiAgICAiaW5zdGFsbG1lbnROdW0iOiAiMCIKICB9LAogICJyZXN1bHQiOiB7CiAgICAicmVzdWx0Q29kZSI6ICJTVUNDRVNTIiwKICAgICJyZXN1bHRNZXNzYWdlIjogIiIKICB9Cg=="
  }
}

返回参数

参数名称	是否必需	说明	示例
requestId	是	商户侧的取消 ID。针对每个请求，requestId 具有唯一性。	无
result.resultCode	是	撤销结果。	无
result.resultMessage	是	撤销结果信息。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
taxAmount.value	是	增值税金额。	无
taxAmount.currency	是	增值税的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
acquirerInfo.notice	否	交易描述。	`" 매입사제출테스트 거래임"` `"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"` `"전표:효력없음 userLoginId 000000000602"`
acquirerInfo.acquirerResultCode	是	收单机构返回的结果码。	无
acquirerInfo.acquirerResultMessage	否	收单机构返回的消息描述。	无
acquirerInfo.acquirerTerminalId	否	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	否	加盟店营业执照号码。	无
acquirerInfo.acquirerApprovalNum	是	KICC 的交易批准号码。	无
acquirerInfo.acquirerMerchantId	是	门店在收单机构的商户号。	无
acquirerInfo.acquirerTransactionId	是	收单机构交易序列号。	无
acquirerInfo.acquirerMetaData	否	收单机构返回的原始数据。	无
acquirerInfo.acquirerName	是	收单机构名称。	`KICC`
extendInfo.AD1	否	收单机构的额外注释 1。	无
extendInfo.AD2	否	收单机构的额外注释 2。	无

以下是响应报文的示例：

copy
{
  "requestId":"123456XXXX",
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "taxAmount": {
    "value": "9",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "creditPayPlan": {
    "installmentNum":"0"
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":""
  },
  "acquirerInfo": {
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerResultCode": "$RESULT_CODE",
    "acquirerResultMessage": "$RESULT_MSG",
    "acquirerTransactionId": "$TRAN_SERIALNO",
    "acquirerApprovalNum": "16263485",
    "acquirerMerchantId": "608525310521",
    "acquirerName": "KICC",
    "notice": "$NOTICE"
  }
}

现金报税

使用 CashReceipt 指令来进行现金报税，以下为其包含的参数及示例代码。

请求参数

参数名称	是否必需	说明	示例
requestId	是	商户侧的报税 ID。针对每个请求，requestId 具有唯一性。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
buyerType	否	现金收据交易归属，有效值为： `Individual`：个人。默认值。 `Business`：企业。	无
reportType	否	报税方式，有效值为： `auto`：现金收据自动批准。默认值。 `manual`：现金收据手动批准（主动发放）。	无
acquirerInfo.acquirerTerminalId	否	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	否	加盟店营业执照号码。	无

以下是请求报文的示例：

copy
{
  "requestId":"123456XXXX",
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "buyerType": "Individual/Business",
  "reportType": "auto/manual",
  "acquirerInfo": {
    "acquirerTerminalId": "0788888",
    "acquirerRegistrationNo": "0216001234"
  }
}

返回参数

参数名称	是否必需	说明	示例
requestId	是	商户侧的报税 ID。针对每个请求，requestId 具有唯一性。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
taxAmount.value	是	增值税金额。	无
taxAmount.currency	是	增值税的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
acquirerInfo.notice	否	交易描述。	`" 매입사제출테스트 거래임"` `"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"` `"전표:효력없음 userLoginId 000000000602"`
result.resultCode	是	处理结果。	无
result.resultMessage	是	处理结果信息。	无
cashIdentificationNo	是	现金收据识别号，通常为电话号码。	`123456*******`
institutionCode	是	国税局代码。	无
acquirerInfo.acquirerResultCode	是	收单机构返回的结果码。	无
acquirerInfo.acquirerResultMessage	否	收单机构返回的消息描述。	无
acquirerInfo.acquirerTransactionId	是	收单机构交易序列号。	无
acquirerInfo.acquirerMetaData	是	收单机构返回的原始数据，在取消现金报税时需要传入。	无
acquirerInfo.acquirerTerminalId	否	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	否	加盟店营业执照号码。	无
acquirerInfo.acquirerApprovalNum	是	KICC 的交易批准号码。	无
acquirerInfo.acquirerName	是	收单机构名称。	`KICC`

以下是响应报文的示例：

copy
{
  "requestId": "123456XXXX",
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "taxAmount": {
    "value": "9",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": ""
  },
  "cashIdentificationNo": "$CARD_NO",
  "institutionCode":"$ISSUER_CODE",
  "acquirerInfo": {
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerResultCode": "$RESULT_CODE",
    "acquirerResultMessage": "$RESULT_MSG",
    "acquirerTransactionId": "$TRAN_SERIALNO",
    "acquirerApprovalNum": "$APPROVAL_NUM",
    "acquirerName": "KICC",
    "notice": "$NOTICE",
    "acquirerMetaData":"ImNyZWRpdFBheVBsYW4iOiB7CiAgICAiaW5zdGFsbG1lbnROdW0iOiAiMCIKICB9LAogICJyZXN1bHQiOiB7CiAgICAicmVzdWx0Q29kZSI6ICJTVUNDRVNTIiwKICAgICJyZXN1bHRNZXNzYWdlIjogIiIKICB9Cg=="
  }
}

取消现金报税

使用 CashReceiptCancel 指令来取消现金报税，以下为其包含的参数及示例代码。

请求参数

参数名称	是否必需	说明	示例
requestId	是	商户侧取消报税的 ID。针对每个请求，requestId 具有唯一性。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
buyerType	否	现金收据交易归属，有效值为： `Individual`：个人。默认值。 `Business`：企业。注意：该参数的值需与现金报税请求中的值保持一致。	无
reportType	否	报税方式，有效值为： `auto`：现金收据自动批准。默认值。 `manual`：现金收据手动批准（主动发放）。注意：该参数的值需与现金报税请求中的值保持一致。	无
acquirerInfo.acquirerMetaData	是	收单机构返回的原始数据。将 CashReceipt 指令中返回的 acquirerInfo.acquirerMetaData 的值传入此参数。	无
acquirerInfo.acquirerTerminalId	否	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	否	加盟店营业执照号码。	无

以下是请求报文的示例：

copy
{
  "requestId":"123456XXXX",
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "reportType": "auto/manual",
  "paymentExpiryTime":"30",
  "acquirerInfo": {
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerMetaData":"ImNyZWRpdFBheVBsYW4iOiB7CiAgICAiaW5zdGFsbG1lbnROdW0iOiAiMCIKICB9LAogICJyZXN1bHQiOiB7CiAgICAicmVzdWx0Q29kZSI6ICJTVUNDRVNTIiwKICAgICJyZXN1bHRNZXNzYWdlIjogIiIKICB9Cg=="
  }
}

返回参数

参数名称	是否必需	说明	示例
requestId	是	商户侧取消报税的 ID。针对每个请求，requestId 具有唯一性。	无
paymentAmount.value	是	总支付金额。	无
paymentAmount.currency	是	支付的币种。	`KRW`
taxAmount.value	是	增值税金额。	无
taxAmount.currency	是	增值税的币种。	`KRW`
tipAmount.value	是	服务费金额。	无
tipAmount.currency	是	服务费的币种。	`KRW`
acquirerInfo.notice	否	交易描述。	`" 매입사제출테스트 거래임"` `"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"` `"전표:효력없음 userLoginId 000000000602"`
result.resultCode	是	处理结果。	无
result.resultMessage	是	处理结果信息。	无
cashIdentificationNo	是	现金收据识别号，通常为电话号码。	`123456*******`
institutionCode	是	国税局代码。	无
acquirerInfo.acquirerMetaData	否	收单机构返回的原始数据。	无
acquirerInfo.acquirerTransactionId	是	收单机构交易序列号。	无
acquirerInfo.acquirerResultCode	是	收单机构返回的结果码。	无
acquirerInfo. acquirerResultMessage	否	收单机构返回的消息描述。	无
acquirerInfo.acquirerTerminalId	否	终端机具的 ID（通常情况下，卡和钱包使用不同的 ID）。	无
acquirerInfo.acquirerRegistrationNo	否	加盟店营业执照号码。	无
acquirerInfo.acquirerApprovalNum	是	KICC 的交易批准号码。	无
acquirerInfo.acquirerName	是	收单机构名称。	`KICC`

以下是响应报文的示例：

copy
{
  "requestId": ,
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "taxAmount": {
    "value": "9",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": ""
  },
  "institutionCode":"$ISSUER_CODE",
  "cashIdentificationNo": "$CARD_NO",
  "acquirerInfo": {
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerResultCode": "$RESULT_CODE",
    "acquirerResultMessage": "$RESULT_MSG",
    "acquirerTransactionId": "$TRAN_SERIALNO",
    "acquirerApprovalNum": "$APPROVAL_NUM",
    "acquirerName": "KICC",
    "notice": "$NOTICE"
  }
}

查询最近一笔交易

GetLastTransaction 指令用于查询最近一笔交易，其返回参数的格式不固定，具体格式取决于 responseCommand 字段的类型，其类型包括：

Purchase：发起支付。
PurchaseCancel：取消支付。
CashReceipt：现金报税。
CashReceiptCancel：取消现金报税。

以下为 Purchase 返回格式的示例：

copy
{
  "responseCommand":"Purchase"
  "paymentAmount": {
    "value": "104",
    "currency": "KRW"
  },
  "taxAmount": {
    "value": "9",
    "currency": "KRW"
  },
  "tipAmount": {
    "value": "0",
    "currency": "KRW"
  },
  "creditPayPlan": {
    "installmentNum": "0"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": ""
  },
  "acquirerInfo": {
    "acquirerTerminalId": "$SHOP_TID",
    "acquirerRegistrationNo": "$SHOP_BIZ_NUM",
    "acquirerResultCode": "$RESULT_CODE",
    "acquirerResultMessage": "$RESULT_MSG",
    "acquirerTransactionId": "$TRAN_SERIALNO",
    "acquirerMetaData":"ImNyZWRpdFBheVBsYW4iOiB7CiAgICAiaW5zdGFsbG1lbnROdW0iOiAiMCIKICB9LAogICJyZXN1bHQiOiB7CiAgICAicmVzdWx0Q29kZSI6ICJTVUNDRVNTIiwKICAgICJyZXN1bHRNZXNzYWdlIjogIiIKICB9Cg=="
  }
}

事件码

事件码分类如下：

初始化关联：在全局初始化阶段由 onInitResult 返回。
指令执行关联：若设备响应失败，由 onCommandFailed 返回。
业务关联：若业务响应失败，由 onBusinessFailed 返回。

类型	事件码	描述	后续操作
初始化关联	INIT_SUCCESS	初始化成功。	无需进一步操作。
	INIT_FAILED	初始化失败。	建议重试。
	INIT_PARAM_ERROR	初始化参数错误。	请阅读步骤 4：初始化 SDK，检查输入的参数。
指令执行关联	CommandInvalidResponse	指令返回结果不正确。	建议重试。
	CommandResponseTimeout	指令执行了，但是无响应。更多信息请参考超时。	建议重试。
	CommandNotSupport	指令不支持。	请阅读步骤 5：发送设备指令，输入有效指令。
	CommandDeviceBusy	设备指令进行中。	等待上一个指令返回后再重试。
	CommandParamError	参数异常。	检查输入指令的参数。
业务关联	REPEAT_REQ_REJECT	有一个具有相同 requestId 的现有订单。	请使用新的 requestId 重试。
	INVALID_CONTRACT	合同无效。	请检查输入的 merchantId 是否有效。
	ACCESS_DENIED	访问被拒绝。	请联系 KICC 获取详细原因及帮助。
	PROCESS_FAIL	发生了常见的业务失败。	请勿重试。通常需要人工干预。建议您联系 Antom 技术支持来解决问题。
	PARAM_ILLEGAL	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
	ORDER_STATUS_INVALID	订单状态无效。	请检查订单状态。
	ORDER_IS_CANCELED	交易已取消。	您不能对交易进行退款，因为此交易已被取消。
	USER_AMOUNT_EXCEED_LIMIT	支付金额超过了用户的支付限额。	使用不超过账户可用余额的金额创建新支付，或联系 Antom 技术支持。
	USER_BALANCE_NOT_ENOUGH	由于对应支付方式的用户余额不足，支付无法完成。	请充值账户或选择其他支付方式。
	INVALID_CARD_NUMBER	用于交易的卡号无效。	检查并验证当前接口所需的请求字段是否正确传递和有效。
	IDENTITY_VERIFY_FAILED	身份验证超时或无法检索结果。	请确认您的身份信息并重试。
	UNKNOWN	未知场景。	请联系 KICC 获取详细原因及帮助。