Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Popup mode

Electronic Data Capture (EDC) devices are widely used in various retail and service industries, especially in restaurants, supermarkets, and convenience stores. This document outlines how to integrate the Antom SDK with EDC devices. This solution enables quick and secure processing of customer card payments, enhancing transaction efficiency and user experience.

Integration steps

  1. Obtain the device
  2. Install the EasyCard App
  3. Integrate SDK package
  4. Instantiate the SDK
  5. Send commands to the device
  6. Handle callback intent data

Step 1: Obtain the device

To obtain the device, please contact Antom business support for detailed information.

Step 2: Install the EasyCard App

Please contact Antom business support for the installation instructions of the EasyCard App. After acquiring the equipment and completing the configuration, you can follow the following steps to complete the SDK integration.

Step 3: Integrate SDK package

Version requirements:

  • Android 4.4 (API level 19) or later.
  • Java 1.8 or later.

Please follow the steps below to integrate the SDK package with Maven.

  1. Add the Maven repository:

Add the Maven repository to your root build.gradle file using the code snippet below.

copy
// Add maven repository
maven {
    credentials {
        username "antomsdk@aliyun.com"
        password "Admin1234"
    }
    url "https://globaltech.alipay.com/api/v1/file/repository/antom/"
}
  1. Add dependencies:

Add the dependencies in the build.gradle file using the code snippet below.

copy
// in app build.gradle
// if there are some conflicts with existing sdk, please exclude them
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'
}

Externalize the dependency version in the build.gradle file to easily manage upgrades with the "Externalize dependency version" code snippet. Replace the value of ANTOM_VERSION with the latest version 1.20.1.

copy
ext {
    antom_version = 'ANTOM_VERSION'
}

Step 4: Instantiate the SDK

It is recommended to call the init API for global initialization at application startup to ensure that the device can respond quickly.

Create an SDK instance using AMSEDCGlobalConfiguration and specify basic configurations. Creating a configuration object includes the following methods:

Parameter name

Type

Required

Description

options

Map

Yes

Reserved for extension parameter information. It includes the following parameters:

  • provider: The type of the connected device. Required. String type.
  • merchantId: The merchant's ID number. Required. String type.

initCallback

InitCallback

Yes

Initialization callback function. It includes the following parameters:

  • eventCode: The relevant result code. String type.
  • result: Specific message about the result. String type.

Call the InitCallback to receive the onInitResult callback event. The following example code shows how to handle the onInitResult callback event:

copy
void onInitResult(String code, String result)

The following example code shows how to instantiate the 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);

Step 5: Send commands to the device

Call the sendCommand API to send commands and data to the specified EDC device, such as commandName=xxxx. For specific command implementations, please refer to the device command instructions.

After sending the DeviceCommandRequest to the device, you will receive a DeviceCommandCallback response. Sending the DeviceCommandRequest involves the following parameters:

Parameter name

Type

Required

Description

provider

String

Yes

Device provider, designated as KICC.

commandName

String

Yes

Specifies the command name. Valid commands include:

  • Purchase
  • PurchaseCancel
  • CashReceipt
  • CashReceiptCancel
  • GetLastTransaction

requestId

String

Yes

Request ID.

commandRequestParams

JSONObject

No

Command request parameters.

options

Map<String, String>

No

Reserved for extension parameters.

The following code shows an example of a DeviceCommandCallback response. It contains the following parameters:

  • CommandResult: The command result. It contains the following parameter:
    • responseData: The returned result. JSONObject type.
  • onCommandFailed: The device command execution failed.
  • onBusinessFailed: The business processing failed.
copy
void onSuccess(CommandResult result);

/**
 * Command execution failed 
 */
void onCommandFailed(CommandFailInfo commandFailInfo);

/**
 * Command executed successfully, but business response error
 */
void onBusinessFailed(CommandResult result);

The following code shows an example of 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"
  }
}

The following code shows an example of onBusinessFailed:

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

Timeout

The default timeout settings for each command are as follows.

Command

Default value (seconds)

Purchase

95 (Require signature if the amount exceeds 50,000 KRW, and its default value is 115)

Note: If you need to customize the timeout setting for the Purchase command, ensure that it is not less than the default value.

PurchaseCancel

85

CashReceipt

65

CashReceiptCancel

65

GetLastTransaction

5

Sample code for calling the sendCommand API

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);

Step 6: Handle callback intent data

Call the handleIntent API to receive the parameters returned from the device through the merchant's Activity.

Note: For KICC devices, if this API is not called, it will result in a timeout error when calling the sendCommand API on a non-responsive end.

The following is an example of processing the returned result in the merchant's Activity class:

copy
//In the merchant's Activity class
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if(AMSEDCPayment.handleIntent(requestCode,resultCode,data)){
        return;
    }
}

Device commands

The following are the commands supported by KICC devices, which are invoked by calling the sendCommand API. For detailed information, please refer to Send commands to the device.

Purchase

Use Purchase to initiate a payment with the following parameters:

Request parameters

Parameter name

Required

Description

Sample

requestId

Yes

Merchant transaction number.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

creditPayPlan.installmentNum

Yes

The number of installments.

None

paymentExpiryTime

No

Payment wait timeout, which defaults to 30s.

None

acquirerInfo.acquirerTerminalId

Yes

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

Yes

Merchant business license number.

None

The following code shows a sample of the request message:

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

Returned parameters

Parameter name

Required

Description

Sample

requestId

Yes

Merchant transaction number.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

taxAmount.value

Yes

Value-added tax amount.

None

taxAmount.currency

Yes

Currency of the value-added tax.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

creditPayPlan.installmentNum

Yes

The number of installments.

None

result.resultCode

Yes

Payment result code.

None

result.resultMessage

Yes

Payment result message.

None

acquirerInfo.acquirerResultCode

No

Result code returned from the acquirer.

None

acquirerInfo.acquirerResultMessage

No

Message description returned from the acquirer.

None

acquirerInfo.acquirerTerminalId

Yes

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

Yes

Merchant business license number.

None

acquirerInfo.signData

No

Signature data (Only transmitted in signed transactions.)

None

acquirerInfo.notice

No

Transaction description.

" 매입사제출테스트 거래임"

"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"

"전표:효력없음 userLoginId 000000000602"

acquirerInfo.acquirerTransactionId

Yes

Transaction serial number of the acquirer.

None

acquirerInfo.acquirerMerchantId

Yes

Merchant's ID in the acquirer.

None

acquirerInfo.acquirerName

Yes

Acquirer name.

KICC

acquirerInfo.acquirerMetaData

Yes

Original data returned by the acquirer, which must be provided during the refund process.

None

acquirerInfo.acquirerApprovalNum

Yes

Transaction approval number of KICC.

None

paymentResultInfo.cardBin

No

Payment card BIN (first eight digits of the card). The card BIN information is required during card payment.

None

paymentResultInfo.paymentMethodId

No

Identification number. Bar code is required in the wallet payment scenario.

None

paymentResultInfo.issuerCode

Yes

Issuer code. See the attachment 📎전체 카드사 신용카드_발급사 매입사 정보(2023.07.25 기준) .xlsx for a full list.

None

paymentResultInfo.funding

Yes

The card funding types include: Debit, Credit, and Prepaid.

Note: The value of this parameter is null when paying with international cards, wallets or Samsung Pay.

None

paymentResultInfo.paymentMethodRegion

Yes

The region code that represents the country or region of the payment method. The value of this parameter is a 2-letter ISO country code or GLOBAL.

None

paymentResultInfo.paymentMethodType

Yes

Payment method.

None

extendInfo.AD1

No

Additional note 1 from the acquirer.

None

extendInfo.AD2

No

Additional note 2 from the acquirer.

None

The following code shows a sample of the response message:

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

Use PurchaseCancel to cancel a payment with the following parameters:

Request parameters

Parameter name

Required

Description

Sample

requestId

Yes

Cancel ID on the merchant side. The requestId is unique for each request.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

creditPayPlan.installmentNum

No

The number of installments.

None

acquirerInfo.acquirerMetaData

Yes

Original data returned by the acquirer. Pass the value of acquirerInfo.acquirerMetaData returned by the Purchase command to this parameter.

None

acquirerInfo.acquirerTerminalId

No

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

No

Merchant business license number.

None

The following code shows a sample of the request message:

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=="
  }
}

Returned parameters

Parameter name

Required

Description

Sample

requestId

Yes

Cancel ID on the merchant side. The requestId is unique for each request.

None

result.resultCode

Yes

Cancel result.

None

result.resultMessage

Yes

Cancel result message.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

taxAmount.value

Yes

Value-added tax amount.

None

taxAmount.currency

Yes

Currency of the value-added tax.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

acquirerInfo.notice

No

Transaction description.

" 매입사제출테스트 거래임"

"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"

"전표:효력없음 userLoginId 000000000602"

acquirerInfo.acquirerResultCode

Yes

Result code returned from the acquirer.

None

acquirerInfo.acquirerResultMessage

No

Message description returned from the acquirer.

None

acquirerInfo.acquirerTerminalId

No

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

No

Merchant business license number.

None

acquirerInfo.acquirerApprovalNum

Yes

Transaction approval number of KICC.

None

acquirerInfo.acquirerMerchantId

Yes

Merchant's ID in the acquirer.

None

acquirerInfo.acquirerTransactionId

Yes

Transaction serial number of the acquirer.

None

acquirerInfo.acquirerMetaData

No

Original data returned by the acquirer.

None

acquirerInfo.acquirerName

Yes

Acquirer name.

KICC

extendInfo.AD1

No

Additional note 1 from the acquirer.

None

extendInfo.AD2

No

Additional note 2 from the acquirer.

None

The following code shows a sample of the response message:

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

Use CashReceipt to perform cash tax reporting with the following parameters:

Request parameters

Parameter name

Required

Description

Sample

requestId

Yes

Tax reporting ID on the merchant side. The requestId is unique for each request.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

buyerType

No

Type of the transaction entity for cash receipt. Valid values are:

  • Individual: An individual. This is the default value.
  • Business: Enterprise.

None

reportType

No

Tax reporting method. Valid values are:

  • auto: Automatic approval of cash receipts. This is the default value.
  • manual: Manual approval of cash receipts (proactive issuance).

None

acquirerInfo.acquirerTerminalId

No

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

No

Merchant business license number.

None

The following code shows a sample of the request message:

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

Returned parameters

Parameter name

Required

Description

Sample

requestId

Yes

Tax reporting ID on the merchant side. The requestId is unique for each request.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

taxAmount.value

Yes

Value-added tax amount.

None

taxAmount.currency

Yes

Currency of the value-added tax.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

acquirerInfo.notice

No

Transaction description.

" 매입사제출테스트 거래임"

"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"

"전표:효력없음 userLoginId 000000000602"

result.resultCode

Yes

Processing result.

None

result.resultMessage

Yes

Processing result message.

None

cashIdentificationNo

Yes

Cash receipt identification number, which is usually a phone number.

123456*******

institutionCode

Yes

Tax bureau code.

None

acquirerInfo.acquirerResultCode

Yes

Result code returned from the acquirer.

None

acquirerInfo.acquirerResultMessage

No

Message description returned from the acquirer.

None

acquirerInfo.acquirerTransactionId

Yes

Transaction serial number of the acquirer.

None

acquirerInfo.acquirerMetaData

Yes

Original data returned by the acquirer, which must be provided when cancelling the cash tax reporting.

None

acquirerInfo.acquirerTerminalId

No

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

No

Merchant business license number.

None

acquirerInfo.acquirerApprovalNum

Yes

Transaction approval number of KICC.

None

acquirerInfo.acquirerName

Yes

Acquirer name.

KICC

The following code shows a sample of the response message:

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

Use cashReceiptCancel to cancel cash tax reporting with the following parameters:

Request parameters

Parameter name

Required

Description

Sample

requestId

Yes

ID of the merchant side to cancel the tax reporting. The requestId is unique for each request.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

buyerType

No

Type of the transaction entity for cash receipt. Valid values are:

  • Individual: An individual. This is the default value.
  • Business: Enterprise.

Note: The value of this parameter must be the same as the value in the CashReceipt request.

None

reportType

No

Tax reporting method. Valid values are:

  • auto: Automatic approval of cash receipts. This is the default value.
  • manual: Manual approval of cash receipts (proactive issuance).

Note: The value of this parameter must be the same as the value in the CashReceipt request.

None

acquirerInfo.acquirerMetaData

Yes

Original data returned by the acquirer. Pass the value of acquirerInfo.acquirerMetaData returned by the CashReceipt command to this parameter.

None

acquirerInfo.acquirerTerminalId

No

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

No

Merchant business license number.

None

The following code shows a sample of the request message:

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=="
  }
}

Returned parameters

Parameter name

Required

Description

Sample

requestId

Yes

ID of the merchant side to cancel the tax reporting. The requestId is unique for each request.

None

paymentAmount.value

Yes

Total payment amount.

None

paymentAmount.currency

Yes

Currency of the payment.

KRW

taxAmount.value

Yes

Value-added tax amount.

None

taxAmount.currency

Yes

Currency of the value-added tax.

KRW

tipAmount.value

Yes

Service fee amount.

None

tipAmount.currency

Yes

Currency of the service fee.

KRW

acquirerInfo.notice

No

Transaction description.

" 매입사제출테스트 거래임"

"현금영수증 문의 Tel.126-1-1 http:\/\/hometax.go.kr"

"전표:효력없음 userLoginId 000000000602"

result.resultCode

Yes

Processing result.

None

result.resultMessage

Yes

Processing result message.

None

cashIdentificationNo

Yes

Cash receipt identification number, which is usually a phone number.

123456*******

institutionCode

Yes

Tax bureau code.

None

acquirerInfo.acquirerMetaData

No

Original data returned by the acquirer.

None

acquirerInfo.acquirerTransactionId

Yes

Transaction serial number of the acquirer.

None

acquirerInfo.acquirerResultCode

Yes

Result code returned from the acquirer.

None

acquirerInfo.acquirerResultMessage

No

Message description returned from the acquirer.

None

acquirerInfo.acquirerTerminalId

No

ID of the terminal device (cards and wallets usually use different ID).

None

acquirerInfo.acquirerRegistrationNo

No

Merchant business license number.

None

acquirerInfo.acquirerApprovalNum

Yes

Transaction approval number of KICC.

None

acquirerInfo.acquirerName

Yes

Acquirer name.

KICC

The following code shows a sample of the response message:

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

Use GetLastTransaction to query the most recent transaction. The format of the returned parameters is variable and depends on the responseCommand field type. The types include:

  • Purchase
  • PurchaseCancel
  • CashReceipt
  • CashReceiptCancel

The following sample code shows of a response format for 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=="
  }
}

Event codes

You may encounter the following types of event codes:

  • Initialization type: Returned by onInitResult during the global initialization phase.
  • Command execution type: Returned by onCommandFailed when the device command execution fails.
  • Business processing type: Returned by onBusinessFailed when the business processing fails.

Type

Event code

Description

Further action

Initialization type

INIT_SUCCESS

Initialization succeeded.

No further action required.

INIT_FAILED

Initialization failed.

Please try again.

INIT_PARAM_ERROR

Initialization parameter error.

Please read Step 4: Instantiate the SDK and check the input parameter.

Command execution type

CommandInvalidResponse

Returned result of the command is incorrect.

Please try again.

CommandResponseTimeout

The command was executed, but no response was returned. See Timeout for more information.

Please try again.

CommandNotSupport

The command is not supported.

Please read Step 5: Send commands to the device and input valid commands.

CommandDeviceBusy

The device is executing the command.

Wait for the previous command to response and try again.

CommandParamError

Abnormal parameter.

Check the parameters of the input command.

Business processing type

REPEAT_REQ_REJECT

There is an existing order with the same requestId.

Please retry with a new requestId.

INVALID_CONTRACT

Contract is invalid.

Please check the input merchantId information.

ACCESS_DENIED

Access is denied.

Contact KICC for detailed reasons and support.

PROCESS_FAIL

A general business failure occurred.

Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue.

PARAM_ILLEGAL

The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, or the length and type of the parameter are wrong.

Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.

ORDER_STATUS_INVALID

The order status is invalid.

Check the order status.

ORDER_IS_CANCELED

The transaction is canceled.

You cannot refund the transaction because it is canceled.

USER_AMOUNT_EXCEED_LIMIT

The payment amount exceeds the user payment limit.

Create a new payment by using an amount less than or equal to the account's available balance, or contact Antom Technical Support.

USER_BALANCE_NOT_ENOUGH

The payment cannot be completed because the user balance in the corresponding payment method is not enough.Please top up the account or choose other payment methods.

INVALID_CARD_NUMBER

The number of the card used for the transaction is invalid.

Check and verify whether the required request fields of the current API are correctly passed and valid.

IDENTITY_VERIFY_FAILED

Identity verification timed out or the result couldn't be retrieved.

Please confirm your identification details and try again.

UNKNOWN

Unknown scenarios.

Contact KICC for detailed reasons and support.