N950 EDC integration guide

Antom supports Omnichannel payments, which includes the in-person payment channel, allowing merchants using in-store POS/Kiosk host systems to integrate with Antom payment terminals through integration, achieving unified acquiring, multi-channel fund aggregation and centralized management, improving operational efficiency and reconciliation experience. This topic introduces how to integrate N950 EDC devices through Antom Omnichannel to accept in-store payments.

Payment flow

The following figure shows how to accept in-store payments by integrating N950 EDC devices through Antom Omnichannel:

1. Buyer selects products and places order.
2. Check payment terminal status.
   Call the diagnosis USB cable communication or diagnosis Wi-Fi LAN communication API to check the payment terminal status, including network status, printer status, and global status. Only when the terminal device status is normal can subsequent operations be performed.
3. Initiate payment request.
   Call the pay USB cable communication or pay Wi-Fi LAN communication API to initiate a payment request.
4. Get payment result. 
   If you do not receive a payment response after timeout, you can call the inquiryPayment USB cable communication or inquiryPayment Wi-Fi LAN communication API to query the payment status.
5. (Optional) Refund. Wi-Fi LAN communication
   When a transaction needs to be refunded, you can call the refund API to initiate a refund request. 
6. (Optional) Get refund result. Wi-Fi LAN communication
   If you do not receive a refund response after timeout, you can call the inquiryRefund API to query the refund result.

Integration preparation

To ensure a smooth integration of the payment terminal, please prepare by following these steps:

1. Contact Antom Business Support to complete the contract signing and device procurement, and obtain the SDK resource package.
2. Select one communication mode that suits you from the two communication modes.
3. Configure communication interface endpoint: Wi-Fi LAN communication
   Interface endpoint format: http://{terminal_static_ipAddress}:8344/{version}/{restfulPath} (terminal_static_ipAddress is the static IP of the network LAN connected by your terminal device)
4. Complete key exchange for in-store terminal devices:

• Private key: You can use the Alipay key tool to generate public and private keys for the production environment. After generating the private key, be sure to save your private key information. Follow the steps below to use OpenSSL to generate a key pair and save the private key locally (POS private key):

$ 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

• Public key: Exchange the production environment public key you generated with Antom Business Support via email. After the Antom Business Support obtains your production environment public key, they will configure it for your ClientID and share the Antom public key and ClientID (payment terminal serial number SN) with you.

Select one device communication mode

You must first determine which communication option is suitable for your integrated POS / Kiosk host system and then integrate one of the following modes:

Note: You must choose and integrate only one of these communication modes.

Initial setup of the payment terminal device

Follow the steps below to complete the initial setup of the payment terminal device:

1. Hardware check: Upon receiving the device, confirm that the device, power supply, and manual are all included. We recommend distributing the device to your professional development and testing staff for debugging and integration.

Note: The Newland terminal device does not include a USB data cable or receipt paper. You will need to prepare these suitable accessories yourself.

2. Power on and connect to network:

• Connect the Type-C power supply and start the device.
• Set up Wi-Fi or an Ethernet cable (it must be on the same network as the POS) and configure a static IP address. Wi-Fi LAN communication
• If you choose the USB communication mode, ensure you have a Type-C data cable to connect the terminal to your host POS/Kiosk system. USB cable communication
• The terminal device does not come with receipt paper. We recommend preparing your own receipt paper with a width of 5.5cm-5.7cm.

3. Onboard to D-store and install the app:

• You need to onboard to the D-store Console to manage your in-store devices.
• Contact Antom Business Support to download the D-store Payment Terminal App (latest version is 1.6.0).
• After completing the D-store Console onboarding, follow the path Create Store > POS > Device to configure a new payment terminal, and obtain the download QR code and login password.

• After creating the store in D-store, send the D-store store ID to Antom Business Support to complete the in-store channel registration.

4. Record the serial number (SN): Find the SN on the back of the terminal or in its settings. This will be used as the Client-Id for API requests.

Configure a static IP address Wi-Fi LAN communication

Before setting up a static IP address, please contact Antom technical support to assign a fixed IP address to the terminal. The setup steps are as follows:

1. Select network: Select the Wi-Fi network that the store is currently using.
2. Enter settings:

• Click the network to enter the password, or click the pencil button in the upper right corner to edit Wi-Fi settings.
• If you do not see these configuration options, click advanced options to expand the settings menu.

3. Configure IP settings: Under the IP settings option, select static.
4. Enter network information:

• In the IP address input box, enter the fixed IP address assigned to you by Antom.
• In the Gateway input box, enter the gateway address obtained from the POS.

After completing the above steps, you can begin API development and testing.

Integration steps

Follow these steps to enable your POS application to communicate with terminal devices via HTTP protocol over the local network:

1. Merchant POS application initiates payment request to terminal device:

• Wi-Fi LAN communication: Trigger the payment flow on the device through LAN and HTTPS interface calls.
• USB wired communication: Trigger the payment flow on the device by integrating the client SDK and device connection.

2. Terminal device forwards the request to the PDS payment platform to execute transaction processing.
3. Transaction results will be returned to your system in real-time through synchronous responses.

Step 1: Integrate payment terminal APIs

Follow these steps to integrate payment terminal APIs:

• Configure terminal network Wi-Fi LAN communication: Use DHCP reservation or manually configure static IP address to complete the terminal's network setup.
• Ensure local communication security: Encrypt request information and generate digital signatures to ensure data transmission security.
• Build payment flow: Use the terminal's IP address (for example: http://192.168.71.58:8344/{path}) to send payment requests and complete transaction processing. Refer to Overview to understand the message structure and end-to-end message transmission workflow.

During the payment process, the POS system may send multiple payment requests with the same paymentRequestId due to reasons such as network timeout or duplicate submission. Antom uses an idempotency key to ensure that the same payment request is only processed once, effectively preventing duplicate charges and ensuring user fund security. For more information, refer to Idempotency.

Related APIs

The following table shows the related API information and call direction. You can call the APIs according to your needs:

1. Initialize the SDK USB cable communication

In USB cable communication mode, you must call the initConnection API to initialize the connection and check the communication between the POS and the payment terminal. Ensure that you call the initConnection API before creating a payment request.

Before initialization, if your POS system includes scanning/pairing devices, please ensure that your system allows one POS device to pair with multiple terminal devices. After successfully connecting to the scanned device, you will receive the following device information:

("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")

To establish stable and reliable communication between your application and the USB payment terminal, you need to follow these steps to check device permissions and determine the connection mode:

1. It is mandatory that you follow the method below to check and request access permission for the USB device:

if (UsbDeviceHelper.checkAndRequestUsbPermission(this, usbDevice)) {
    permissionGranted(usbDevice)
}else{
    Logger.d("Selected a USB device but no permission$usbDevice", tag = "UsbHotActivity")
}

2. It is mandatory that you follow the method below to check if the USB device is in accessory mode.

• If this method returns true, the device is already in accessory mode and you can start data communication directly.
• If it returns false, you must perform subsequent steps to switch to accessory mode.

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

3. If the device is not in accessory mode, you must check if the device supports the accessory protocol and switch it to accessory mode.

1. It is mandatory that you follow the method below to open the device connection and check protocol support:

Log.d(TAG, "Not in accessory mode, checking for accessory protocol support")
val connection: UsbDeviceConnection = usbManager!!.openDevice(device)
val protocolSupported: Boolean = checkAccessoryProtocol(connection)
Log.d(TAG, "Does device $device" + device.deviceName + "support accessory protocol:" + protocolSupported)
connection.close()
if (protocolSupported) {
    Log.d(TAG, "Accessory mode supported. Send command to switch to accessory mode and reconnect")
    UsbDeviceHelper.initAccessory(this, device, 1000)
} else {
    Log.d(TAG, "Accessory mode not supported")
    runOnUiThread {
        Toast.makeText(this@UsbHotActivity, "Accessory mode not supported", Toast.LENGTH_SHORT).show()
    }
}

b. It is mandatory that you follow the method below to query whether the device supports the Android accessory protocol through control transfer:

fun checkAccessoryProtocol(connection: UsbDeviceConnection): Boolean {
    // Send Android accessory protocol query request
    val buffer = ByteArray(2)
    val requestType = 0xC0 // Direction: device to host, Type: vendor, Recipient: device
    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. If the device supports the accessory protocol, it is mandatory that you follow the method below to switch the device to accessory mode:

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

        try {
            // Use the same connection for all control transfers
            with(connection) {
                // Initialize string control transfer
                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
                )
                // Start accessory mode
                controlTransfer(0x40, 53, 0, 0, ByteArray(0), 0, timeOut)
            }
            return true
        } catch (e: Exception) {
            Logger.e("initAccessory error: ${e.message}")
            return false
        } finally {
            // Close connection
            connection.close()
        }
    }

2. Check the payment terminal status

You need to call the diagnosis USB cable communication or diagnosis Wi-Fi LAN communication API to check the payment terminal status, including network status, printer status, and global status. Only when the terminal device status is ready can subsequent operations be performed.

3. Initiate a payment request

After the buyer selects their products and places an order, call the pay USB cable communication or pay Wi-Fi LAN communication API to initiate the payment request. You can specify the payment method using the paymentMethod parameter. For the payment method enum values, see Supported payment methods.

4. Get the payment result

If you do not receive a payment response after timeout, you can call the inquiryPayment USB cable communication or inquiryPayment Wi-Fi LAN communication API to query the payment status.

(Optional) 5. Refund Wi-Fi LAN communication

When a transaction needs to be refunded, you can call the refund API to initiate a refund request. If a refund response is not received within the timeout period, you can call the inquiryRefund API to query the refund result.

Before calling the refund API, you must first confirm the running mode of your terminal device. Follow these steps to check your device configuration:

1. Log in to the D-store Console portal.
2. Select POS > Device.
3. Find the created payment terminal and click Edit device.
4. View the status of Customer Mode: click to enable or disable it.

Refund support details

The refund support for POS - terminal with Customer Mode enabled or disabled is as follows:

• Customer Mode disabled: Only full refunds can be initiated by calling the refund API; partial refunds are not supported. If the refund API is not integrated, accounts with store manager or higher permissions can select orders in the D-store POS app on the terminal for full or partial refunds.
• Customer Mode enabled: Once enabled, the terminal will stay on the home page, and users cannot operate or view payment records on the terminal. In this case, full refunds can be initiated by calling the refund API, but only one partial refund can be made.

Step 2: Perform production acceptance testing

Contact Antom Business Support to obtain the terminal device integration test cases. After all tests are completed, you can go live.

Step 3: Reconciliation

After the transaction is completed, use the financial reports provided by Antom for reconciliation. For more information on how to reconcile and Antom settlement rules, refer to Reconciliation.

Supported payment methods

View the payment methods and enum values supported for N950 EDC device integration:

• Singapore
• Malaysia

Common merchant use cases

Wi-Fi communication normal scenario

1. Cashier initiates payment: On the POS page side that has already integrated with the payment terminal, select an in-store payment method (such as card swipe, QR code, etc.).
2. POS-side processing: The POS system encrypts transaction information (such as amount, order number, etc.) and adds a digital signature to ensure data integrity and prevent tampering.
3. Send transaction request: The POS sends the encrypted transaction request message to the payment terminal via API.
4. Payment terminal verification: After receiving the request, the payment terminal decrypts the data and verifies the signature (to ensure the data comes from a legitimate POS and has not been modified).
5. Initiate payment instruction to D-store Payment Terminal App: The terminal encapsulates the transaction message and sends it to the D-store Payment Terminal App server for payment processing, and polls to query the payment result until the final payment status is obtained (such as success, failure, etc.).

Note: After the buyer makes payment, if the payment result from the acquirer is not received in time due to network issues, resulting in order timeout but deduction on the buyer's side, the final order status is determined by the payment result displayed on the terminal device.

6. Pre-return response processing: When the payment terminal is ready to respond, it encrypts and signs the return result (such as payment status, amount, etc.).
7. Return to POS system: The terminal sends the encrypted response message back to the POS system.
8. POS-side result verification: The POS system decrypts the response message, verifies the signature correctness, ensures the data has not been tampered with, and extracts the complete payment result.
9. Print transaction receipt: Based on the payment result (such as transaction success or failure), the POS system prints a transaction slip for the customer to keep. The terminal can also be configured to print payment receipt slips (buyer and merchant receipts).

Wi-Fi refund scenarios

Wi-Fi refund scenarios are divided into two situations: integrated scenario and non-integrated scenario: