CloudIM Developer Guide

1. Quick Start

Overview

CloudIM (CIM) enables seamless integration with Sola devices via cloud-based APIs, eliminating the need for physical connections, drivers, or local SDKs. This setup allows you to manage transactions remotely using simple REST API calls once the device is connected to the merchant’s network (either via LAN or Wi-Fi).

Currently, only credit card transactions (swipe, tap, and dip) are supported. Debit, EBT, and gift cards are not supported at this time.

Step-by-Step Quick Start

Sign Up: Create a Cardknox account and retrieve your API Key and API Secret from the merchant dashboard.
Authentication: Use the API Key and API Secret to request an Access Token. This token is required for making authenticated API calls.
Create Device: Before initiating transactions, you need a Device ID. Follow the instructions below to create and obtain the device ID.
Make Your First API Call: Start by making a simple payment request via the POST /payments endpoint.
Test in Swagger UI: Use Swagger UI to test the API directly in your browser. This is a quick way to familiarize yourself with the API and see how it responds.

2. Authentication Flow (Using Your API Key)

Create API Key

Once registered, your API Key will be available in your Cardknox account dashboard.

Portal>Cardknox Account Settings>Keys>Create a Key - Link

Once the API Key is obtained, include it in the Authorization header of all requests.

3. Before You Start - Device Setup

To start initiating transactions, you need a Device ID. Here’s how you can get the device ID and ensure that your device is ready:

Step 1: Check Device Status

Before initiating any transactions, ensure that CloudIM is running on the device.

Check for the "Running…" Notification: Swipe down from the top of the terminal to verify that the CloudIM service is active. If you don’t see the "Running..." notification, reboot the terminal.
Wait for a minute until the notification appears indicating that CloudIM is up and running.

Step 2: Create Device

Once CloudIM is running, you need to create a Device ID. To do this, send a POST request to the /v1/Device endpoint. This requires the device’s serial number, device make, and a friendly name (a name of your choosing for easier reference).

Endpoint: POST /v1/Device
Required parameters: Serial number, device make, friendly name.

Example Request:

POST <https://device.cardknox.com/v1/Device>
Content-Type: application/json
Authorization: API Key

{
  "serialNumber": "1234567890",
  "deviceMake": "Sola500",
  "deviceFriendlyName": "Terminal 1"
}

Response:

{
	"xDeviceId": "16fbd30d7-2e86-4ddc-8e52-442e9332be0e",
	"xRefnum": "cim111003924",
	"xResult": "S"
}

Step 3: Verify Device Status

Now that you have a Device ID, you can check the device’s status using the GET /v1/Device/{xDeviceId} endpoint.

Endpoint: GET /v1/Device/{xDeviceId}
Status: The response will indicate whether the device is CONNECTED or DISCONNECTED. You can only initiate transactions once the device status is CONNECTED.

Example Request:

GET <https://device.cardknox.com/v1/Device/xDeviceId123>
Authorization: API Key

Response:

{
  "deviceId": "xDeviceId123",
  "deviceName": "Terminal 1",
  "status": "CONNECTED"
}

4. Transaction Flow

Once your device is connected and ready to go, you can start processing transactions. The transaction flow involves the following key steps:

Step 1: Initiate the Transaction

You will initiate the transaction via the [POST] /v1/Session/initiate API. This request starts the transaction on the terminal, which then requests the card details from the user.

Note: cc:save is not supported yet. You can only perform cc:sale of cc:credit transactions.

Although additional payload can be passed during this call, required fields include: xCommand, xAmount, xExternalRequestID (unique per transaction), xSoftwareName, xSoftwareVersion, xDeviceID

Endpoint: POST /v1/Session/initiate

Example Request:

POST <https://device.cardknox.com/v1/Session/initiate>
Content-Type: application/json
Authorization: API Key

{
  "xPayload": {
    "xCommand": "cc:sale",
		 "xAmount": "0.01",
    "xEnableTipPrompt": true,
    "xExternalRequestId": "1234654",
    "xSoftwareName": "MySoftware",
    "xSoftwareVersion": "1.0.0",
  },
  "xDeviceId": "1ac25fc88-da3a-44ba-9b8f-0db642613cb7"
}

Response:

{
	"xSessionId": "session111004629",
	"xRefnum": "cim111004629",
	"xResult": "S"
}

Step 2: Process the Transaction on the Terminal

The terminal will now prompt for the card information (swipe, tap, or dip).
The terminal processes the transaction and sends back an approved, timeout, or error response to the API.

Step 3: Poll for the Session Status

After initiating the transaction, the POS system will need to ping the API to get the transaction status. You will use the [GET] /v1/Session/{xSessionId} endpoint to check the status.

Endpoint: GET /v1/Session/{xSessionId}

Example Request:

GET <https://device.cardknox.com/v1/Session/session12345>
Authorization: API Key

Response (for an approved transaction):

{
	"xSessionStatus": "COMPLETED",
	"xGatewayRefnum": "10204219792",
	"xGatewayStatus": "Approved",
	"xTransactionResult": {},
	"xRefnum": "cim111008282",
	"xResult": "S"
}

Step 4: Retrieve Additional Transaction Details (Optional)

After the transaction has been completed successfully, you can retrieve additional details from the Gateway Reporting API using the xRefNum provided.

5. Schemas

This section describes the common schemas used in the Cardknox API. These schemas define the structure of the request and response payloads for key API endpoints such as device management, session initiation, and transaction result retrieval.

In the CardKnox API, schemas are used for both request and response bodies. When interacting with various endpoints such as device management, session initiation, and transaction result retrieval, you will often need to send data in the formats described in the schemas above. Similarly, the responses you receive from the API will follow the structures defined in these schemas, helping you to parse and process the returned data accordingly.

By following these schema definitions, developers can ensure that they send and receive data in the correct format, which reduces errors and improves the overall experience when integrating with the CardKnox API.

A. Device Schema

The Device Schema represents the structure of a device object used within the system. Devices are registered on the platform and are assigned unique device IDs to facilitate transactions.

Request Payload (For device creation):

When creating a device, you need to provide the device’s serial number, make, and a friendly name.

{
  "deviceSerialNumber": "SN987654321",
  "deviceMake": "PAX",
  "deviceFriendlyName": "POS-Terminal-01"
}

Response Example:

The API will respond with a unique device ID and the status of the device.

{
  "deviceId": "12345",
  "deviceSerialNumber": "SN987654321",
  "deviceMake": "PAX",
  "deviceFriendlyName": "POS-Terminal-01",
  "status": "CONNECTED"
}

deviceId: Unique identifier for the device.
deviceSerialNumber: Serial number of the device.
deviceMake: The manufacturer or model of the device.
deviceFriendlyName: A custom name for the device.
status: The current state of the device (e.g., "CONNECTED", "DISCONNECTED").

B. Session Schema

The Session Schema is used when initiating a transaction. It tracks the session ID and associated details such as the transaction type, amount, and status.

Request Payload (For session initiation):

When initiating a transaction, you need to provide the device ID, transaction type, and amount.

{
  "deviceId": "12345",
  "transactionType": "cc:sale",
  "amount": 100.00
}

Response Example:

The API responds with the session ID and status of the initiated transaction.

{
  "sessionId": "abc123",
  "deviceId": "12345",
  "transactionType": "cc:sale",
  "amount": 100.00,
  "status": "IN_PROGRESS",
  "responseCode": "00",
  "xRefNum": "X123456789"
}

sessionId: A unique identifier for the session.
deviceId: The ID of the device associated with this session.
transactionType: The type of transaction (e.g., cc:sale, cc:credit).
amount: The amount of the transaction.
status: The current status of the session (e.g., "IN_PROGRESS", "COMPLETED").
responseCode: The response code from the payment processor (e.g., "00" for success).
xRefNum: Cross-reference number for reporting and future use.

C. Transaction Result Schema

The Transaction Result Schema is used when retrieving the details of a completed transaction. It includes the transaction status, reference number, and other relevant details.

Response Example (Transaction Result):

After polling the session status, you can retrieve the transaction details.

{
  "xRefNum": "X123456789",
  "transactionType": "cc:sale",
  "amount": 100.00,
  "status": "approved",
  "approvalCode": "123456",
  "transactionDate": "2024-11-01T12:00:00"
}

xRefNum: Cross-reference number used for reports and follow-up transactions.
transactionType: The type of transaction (e.g., cc:sale, cc:credit).
amount: The total amount processed in the transaction.
status: The status of the transaction (e.g., "approved", "declined").
approvalCode: The authorization code returned from the payment processor.
transactionDate: The date and time when the transaction was completed.

D. Error Response Schema

In the event of an error, the API will return an error message describing what went wrong. The structure of an error response is as follows:

Error Response Example:

{
	"xError": "dynamic error code",
	"xRefnum": "cim123456",
	"xResult": "E"
}

Common error codes might include:

INVALID_REQUEST: Missing required fields or invalid data.
UNAUTHORIZED: Invalid or expired access token.
DEVICE_NOT_FOUND: The device ID provided does not exist in the system.
TRANSACTION_FAILED: The transaction could not be processed.
Session_not_found: The session ID is incorrect

6. Troubleshooting & Common Issues

If you encounter issues, the following steps can help you troubleshoot effectively:

Invalid API Key

If you receive an Authentication error, make sure the API Key is still valid.

Device Not Responding

Ensure the device is connected to the internet.
Restart the app or reboot the terminal.
If the problem persists, contact support with the necessary details (e.g., device serial number, connection status).

Device Status Not CONNECTED

If the device status is not CONNECTED, ensure the device is correctly registered and the Cloud IM app is installed and active.

Session Not Completing

If the transaction session does not complete, check the terminal for errors, and ensure it is connected to the internet. Review the session logs for more details.

7. FAQs

Q. How do I activate Cloud IM on my terminal? A. Cloud IM starts up automatically when the terminal is booted. No user action is required.

Q. How do I know if Cloud IM is running? A. Look for the "Running..." notification at the top of the terminal screen. If it’s not there even after waiting a few minutes, reboot the terminal.

Q. My device is not responding. What should I do? A. Ensure the device is connected to the internet. If it is, reboot the terminal. If issues persist, contact support.

Q. Where can I find the Swagger API docs? A. https://device.cardknox.com/api/v1/swagger/index.html

Last updated 5 hours ago

Table of Contents

1. Quick Start

2. Authentication Flow (Using Your API Key)

3. Before You Start - Device Setup

4. Transaction Flow

5. Schemas

6. Troubleshooting & Common Issues

7. FAQs