> For the complete documentation index, see [llms.txt](https://docs.solapayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solapayments.com/products/cloudim-developer-guide.md). # CloudIM Developer Guide ## CloudIM Developer Guide: Quick Start, Authentication, Device Setup, and Transaction Flow ## 1. Overview CloudIM (CIM) lets your point-of-sale software drive a Sola payment terminal over the cloud. There are no cables, drivers, or local SDKs: once the terminal is connected to the internet, your software starts a transaction with a REST call, the cardholder completes it on the terminal, and the result comes back to you synchronously, by polling, or by webhook. Sola Terminal is Sola's proprietary Android application for PAX terminals. ``` POS ──REST──▶ CloudIM API ──▶ Sola Terminal App (screens, prompts, receipts) └─▶ Sola Gateway (authorization, settlement) POS ◀──sync response / poll / webhook── CloudIM API ``` ### What Sola Terminal supports | Tender | Supported | Notes | | --------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | Credit | Sale, auth-only, refund | Swipe, insert (dip), tap, and keyed entry. Tip and surcharge supported. | | PIN Debit | Sale, with optional cash back | PIN entered on the PAX encrypted PIN pad. Cardholder can be prompted for Credit vs. Debit. | | EBT Food Stamp (SNAP) | Sale, refund/return, balance inquiry | PIN required. Remaining balance returned to the POS. | | EBT Cash Benefit | Sale, balance inquiry | PIN required. Optional cash back. Remaining balance returned to the POS. | | Gift | Issue, redeem, balance, activate | Remaining balance returned to the POS. | | Surcharge | Credit only | Calculated and disclosed by the terminal from the merchant's Sola surcharge settings. Fee returned to the POS as `xTranFee`. | Not supported at this time: eWIC, signature capture, and check/ACH. See [**What's New**](#id-15.-whats-new) for what is planned. {% hint style="info" %} **Note:** CloudIM must be enabled on your Sola account, and the merchant's terminals must be boarded as Sola Terminal devices. To request activation, contact Support. {% endhint %} *** ## 2. Quick Start 1. **Sign up.** Create a Sola account and ask Support to enable CloudIM. 2. **Get an API key.** Portal → Account Settings → Keys → Create a Key. 3. **Board the terminal.** The terminal must have TermLink and the Sola Terminal App installed, with a device auth token for the merchant's account (see Device Setup). This is done during deployment; confirm with Support if you are unsure. 4. **Register the device** with `POST /v1/Device` to get an `xDeviceId`. 5. **Confirm the device is** `CONNECTED` with `GET /v1/Device/{xDeviceId}`. 6. **Run your first sale** with `POST /v2/session` (synchronous). The terminal prompts the cardholder; the response contains the gateway result. 7. **Explore in Swagger.** *** ## 3. Authentication & Environments ### API key Your API key is created in the Sola Portal: **Portal → Sola Account Settings → Keys → Create a Key** ([link](https://portal.cardknox.com/cardknox-account-settings/key-management)). How the key is sent depends on the endpoint version: | Endpoints | How to authenticate | | -------------------------------------------------------- | ----------------------------------------- | | `/v1/*` (Device, Webhook, legacy Session) | `Authorization: ` request header | | `/v2/session`, `/v2/session/async`, `/v2/session/result` | `xKey` field in the JSON request body | {% hint style="info" %} **Note:** The V2 session endpoints read the key from the **body**, not the header. Sending the key only in the `Authorization` header to a V2 endpoint returns `"xError": "xKey required"`. {% endhint %} ### Environments | Environment | Base URL | | ----------- | ----------------------------- | | Production | `https://device.cardknox.com` | ### API versions | Version | Endpoints | Status | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | **V2** | `POST /v2/session`, `POST /v2/session/async`, `POST /v2/session/result` | **Recommended for all new integrations.** Flat request body; the sync endpoint returns the full gateway result. | | V1 | `POST /v1/Session/initiate`, `GET /v1/Session/{xSessionId}`, `GET /v1/Session/ExternalRequestId/{xExternalRequestId}`, `POST /v1/Session/cancel` | Supported for existing integrations. Nested `xPayload`; result is returned inside `xTransactionResult`. | Device and Webhook management endpoints are `/v1/` for both. *** ## 4. Before You Start — Device Setup ### Supported devices | Model | Status | Notes | | ---------------- | --------- | ----------------------------------------------------------------- | | PAX A920 Pro | Supported | 5.5" portrait. Prints receipts only when battery is 7% or higher. | | PAX A920 MAX | Supported | 6.5" portrait. Prints receipts only when battery is 1% or higher. | | PAX A3700 | Supported | Landscape layout is implemented in the Sola Terminal App. | | PAX A6630, A6650 | Supported | Mobile devices | | PAX A35, A80 | Supported | Devices with physical keyboards | > **Note:** Do not order or board a device for Sola Terminal unless it is listed as supported above. ### What must be on the terminal Sola Terminal devices are boarded by Sola Deployments. For reference, a correctly boarded device has: * **TermLink** (developer: PAX USBO) with the Sola EMV configuration files, QuickChip enabled, and a **credit/debit preference** template: *Prefer Credit*, *Prefer Debit*, or *Customer Selects* (see Credit vs. Debit prompt). * **Sola Terminal App** (developer: Cardknox Development) configured with the **Backend** URL (production or dev) and a per-device **auth token** (a JWT generated from the terminal serial number and the merchant's MID). * No other payment applications installed; they conflict with Sola Terminal. The Sola Terminal App validates the auth token against the terminal at startup. If the serial number in the token does not match the device, the app shows an alert and will not process transactions. #### Step 1: Check that the terminal is ready The terminal should show the Sola **idle screen** (Sola logo). If it shows "Initializing…", wait for it to finish. If it shows an error or the Android home screen, see Troubleshooting. #### Step 2: Create the device Register the terminal on your account to get a **Device ID**. You need the serial number printed on the device label, the make (`pax`), and a friendly name of your choosing. ```http POST https://device.cardknox.com/v1/Device Content-Type: application/json Authorization: { "xDeviceSerialNumber": "1234567890", "xDeviceMake": "pax", "xDeviceFriendlyName": "Front Counter 1" } ``` ```json { "xDeviceId": "16fbd30d7-2e86-4ddc-8e52-442e9332be0e", "xRefnum": "cim111003924", "xResult": "S" } ``` * `xDeviceSerialNumber` must be 8–16 digits. * The `xDeviceId` is unique to the Sola account that created it. Store it; you will use it on every session request. * If a device with that serial number already exists on the account, the existing `xDeviceId` is returned and the friendly name is **not** changed. The response includes `"xExistingDeviceFound": true` and the current `xDeviceFriendlyName`. Use `PUT /v1/Device/{xDeviceId}` to rename. #### Step 3: Verify device status ```http GET https://device.cardknox.com/v1/Device/16fbd30d7-2e86-4ddc-8e52-442e9332be0e Authorization: ``` ```json { "xDeviceFriendlyName": "Front Counter 1", "xDeviceSerialNumber": "1234567890", "xDeviceMake": "pax", "xDeviceModel": "A920Pro", "xDeviceOSVersion": "10", "xDeviceCardknoxApplicationVersion": "2.91", "xDeviceLocalIpAddress": "192.168.1.25", "xDeviceStatus": "CONNECTED", "xRefnum": "cim111003930", "xResult": "S" } ``` You can only start a session when `xDeviceStatus` is `CONNECTED`. See Device statuses. *** ## 5. Device API | Method | Endpoint | Purpose | | ------ | ------------------------ | --------------------------------------------------------------------- | | `POST` | `/v1/Device` | Create (register) a device and get its `xDeviceId`. | | `GET` | `/v1/Device` | List all devices on the account. | | `GET` | `/v1/Device/{xDeviceId}` | Get a device's details and current status. | | `PUT` | `/v1/Device/{xDeviceId}` | Update the device friendly name (`{ "xDeviceFriendlyName": "..." }`). | ### Device fields | Field | Description | | ----------------------------------- | --------------------------------------------------------- | | `xDeviceId` | Device identifier used on all session requests. | | `xDeviceFriendlyName` | Your label for the device. | | `xDeviceSerialNumber` | Terminal serial number. | | `xDeviceMake` | `pax` | | `xDeviceModel` | Terminal model, e.g. `A920Pro`. | | `xDeviceOSVersion` | Android OS version reported by the device. | | `xDeviceCardknoxApplicationVersion` | Version of the Sola Terminal App on the device. | | `xDeviceLocalIpAddress` | The device's IP on the merchant network. | | `xCurrentMID` | MID of a session currently running on the device, if any. | | `xDeviceStatus` | See below. | ### Device statuses | `xDeviceStatus` | Meaning | What to do | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `CONNECTED` | Online and idle. | Sessions can be started. | | `BUSY` | A session is in progress (or the device is re-initializing). CloudIM marks the device `BUSY` as soon as a session is accepted, before the terminal acknowledges it. | Wait for the current session to finish. New session requests are rejected while `BUSY`. | | `DISCONNECTED` | The device has not checked in. | Check power, network, and that the Sola Terminal App is running. | | `NOT_REGISTERED` | The device exists but has not completed registration with CloudIM. | Confirm the auth token / boarding; contact Support. | | `UPDATE_NEEDED` | The Sola Terminal App on the device is too old for this API. | Update the app via PAXSTORE. | | `UNKNOWN` | Status could not be determined. | Retry; contact Support if it persists. | *** ## 6. Webhooks Webhooks deliver the session result to a URL you control as soon as the session reaches an end state. They are optional for the synchronous flow and recommended for the asynchronous flow. | Method | Endpoint | Purpose | | ------ | -------------------------- | ----------------------------------------------------------------------------------------------- | | `POST` | `/v1/Webhook` | Create a webhook. Body: `xWebhookUrl` (required), `xWebhookFriendlyName`. Returns `xWebhookId`. | | `GET` | `/v1/Webhook/{xWebhookId}` | Get `xWebhookUrl`, `xWebhookFriendlyName`, `xEnabled`. | | `PUT` | `/v1/Webhook/{xWebhookId}` | Update the friendly name. | Pass the `xWebhookId` on any session request. When the session ends, CloudIM POSTs a JSON body to your URL containing the same fields as the session result plus: | Field | Description | | ------------- | ---------------------------------- | | `xSessionId` | The session the result belongs to. | | `xWebhookUrl` | The URL the result was sent to. | Your endpoint should respond with an HTTP 2xx quickly. The session result also reports `xWebhookCallbackStatus` (e.g. `SUCCEEDED`) so you can tell whether the callback was delivered. Always correlate on `xExternalRequestId` or `xSessionId`, never on order of arrival. *** ## 7. Transaction Flow ### Choosing a flow | Flow | Endpoint(s) | When to use | | ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Synchronous (recommended)** | `POST /v2/session` | The HTTP call stays open until the terminal finishes, then returns the gateway result. Simplest integration. | | **Asynchronous** | `POST /v2/session/async` → `POST /v2/session/result` (poll) and/or webhook | Your POS cannot hold a connection open, or you want event-driven results. | | Legacy V1 | `POST /v1/Session/initiate` → `GET /v1/Session/{xSessionId}` | Existing integrations only. | ### Timeouts | Phase | Limit | What happens | | --------------------------------------------------- | ----------- | --------------------------------------------------------------- | | Initiation (device acknowledges the request) | 15 seconds | Session ends with `TIMEOUT` / `ERROR`; check the device status. | | Processing (cardholder interaction + authorization) | 180 seconds | Session ends with `TIMEOUT`. The terminal returns to idle. | Set your HTTP client timeout for `POST /v2/session` **above 200 seconds**. If your client closes the synchronous connection early, CloudIM **cancels the session** on the terminal. Some terminal prompts (for example, tip) have their own on-screen timeout that matches the device timeout setting. ### Synchronous flow (Recommended) **Step 1: Initiate the transaction** ```http POST https://device.cardknox.com/v2/session Content-Type: application/json { "xKey": "", "xDeviceId": "1ac25fc88-da3a-44ba-9b8f-0db642613cb7", "xWebhookId": "55022ca1-9bec-403d-8c68-200b4159ff6e", "xSoftwareName": "MySoftware", "xSoftwareVersion": "1.0.0", "xCommand": "cc:sale", "xAmount": "12.50", "xInvoice": "INV-10021", "xExternalRequestId": "pos7-20260903-000481" } ``` `xWebhookId` is optional. See Request fields for the full list. **Step 2: The cardholder completes the transaction on the terminal** The terminal wakes from the idle screen and walks the cardholder through the prompts for the command: swipe/insert/tap (or keyed entry), Credit vs. Debit selection, PIN, cash back, tip confirmation, and the approval or decline screen. What is shown depends on the command, the request fields, and the merchant's device settings. See Terminal Behavior & Device Settings. **Step 3: Read the response** The call returns when the session ends. An approved credit sale looks like: ```json { "xResult": "A", "xStatus": "Approved", "xRefnum": "10954413433", "xAuthCode": "08232A", "xAuthAmount": "12.50", "xBatch": "51158105", "xCardType": "MasterCard", "xMaskedCardNumber": "5xxxxxxxxxxx0078", "xExp": "1249", "xName": "", "xEntryMethod": "Contactless_EMV", "xIsEMV": true, "xAID": "A0000000041010", "xAIDName": "MASTERCARD", "xIAD": "0111A04003220000000000000000000000FF", "xTSI": "0000", "xTVR": "0000008001", "xAvsResultCode": "NNN", "xCvvResultCode": "", "xErrorCode": "0", "xToken": "4h8g009h37678536pq983727hpnq6667", "xDate": "6/30/2026 5:05:16 PM" } ``` * `xResult` is the outcome: `A` approved, `D` declined, `E` error. `xStatus` is the matching text (`Approved`, `Declined`, `Error`). * `xRefnum` on an approved/declined response is the **Sola Gateway reference number**. Use it for voids, refunds, and reporting through the Gateway API. * When the session ends without a gateway transaction (cancelled, timed out, device error), `xResult` is `E`, `xStatus` is `Error`, and `xError` describes the reason; `xRefnum` is then a CloudIM reference (`cim…`). A cardholder cancel on the terminal: ```json { "xResult": "E", "xStatus": "Error", "xError": "Transaction canceled", "xRefnum": "cim115093556" } ``` Field-by-field details are in Response fields. ### Asynchronous flow **Step 1: Initiate the transaction** Same body as the synchronous request, different endpoint: ```http POST https://device.cardknox.com/v2/session/async Content-Type: application/json { "xKey": "", "xDeviceId": "1ac25fc88-da3a-44ba-9b8f-0db642613cb7", "xWebhookId": "55022ca1-9bec-403d-8c68-200b4159ff6e", "xSoftwareName": "MySoftware", "xSoftwareVersion": "1.0.0", "xCommand": "cc:sale", "xAmount": "12.50", "xExternalRequestId": "pos7-20260903-000482" } ``` ```json { "xSessionId": "session111004629", "xRefnum": "cim111004629", "xResult": "S", "xStatus": "Success" } ``` `xResult: "S"` means the session was accepted and sent to the device; it says nothing about the payment yet. **Step 2: The cardholder completes the transaction on the terminal** As in the synchronous flow. **Step 3: Get the result** Either wait for the webhook or poll `POST /v2/session/result` by session ID or by your external request ID: ```http POST https://device.cardknox.com/v2/session/result Content-Type: application/json { "xKey": "", "xSessionId": "session111004629" } ``` ```http POST https://device.cardknox.com/v2/session/result Content-Type: application/json { "xKey": "", "xExternalRequestId": "pos7-20260903-000482" } ``` While the session is still running the result returns `"xResult": "I"`, `"xStatus": "InProgress"`. When it has ended, the response is identical to the synchronous response above. Poll no more often than once per second. ### Legacy V1 flow V1 wraps the transaction fields in `xPayload` and returns the gateway result nested in `xTransactionResult`. Use it only if you already have a V1 integration. ```http POST https://device.cardknox.com/v1/Session/initiate Content-Type: application/json Authorization: { "xDeviceId": "1ac25fc88-da3a-44ba-9b8f-0db642613cb7", "xWebhookId": "55022ca1-9bec-403d-8c68-200b4159ff6e", "xPayload": { "xCommand": "cc:sale", "xAmount": "12.50", "xExternalRequestId": "pos7-20260903-000483", "xSoftwareName": "MySoftware", "xSoftwareVersion": "1.0.0" } } ``` ```json { "xSessionId": "session111004629", "xRefnum": "cim111004629", "xResult": "S" } ``` Then poll `GET /v1/Session/{xSessionId}` or `GET /v1/Session/ExternalRequestId/{xExternalRequestId}`: ```json { "xSessionStatus": "COMPLETED", "xGatewayRefnum": "10954413433", "xGatewayStatus": "Approved", "xWebhookCallbackStatus": "SUCCEEDED", "xSessionCompletedTime": "2026-06-30T17:05:18.76", "xTransactionResult": { "xResult": "A", "xStatus": "Approved", "xRefnum": "10954413433", "xAuthCode": "08232A", "xAuthAmount": "12.50", "xCardType": "MasterCard", "xMaskedCardNumber": "5xxxxxxxxxxx0078", "xEntryMethod": "Contactless_EMV", "xIsEMV": true, "xAID": "A0000000041010", "xAIDName": "MASTERCARD", "xToken": "4h8g009h37678536pq983727hpnq6667", "xDate": "6/30/2026 5:05:16 PM" }, "xRefnum": "cim111008282", "xResult": "S" } ``` If a V1 request re-uses an `xExternalRequestId` that already exists, the response is `400` with `xDuplicateSessionId` pointing at the original session. ### Session statuses Session statuses are returned on V1 results and webhooks (`xSessionStatus`). They describe the **session**, not the payment. | Status | Meaning | POS action | | ---------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `INITIATING` | Session created; the terminal has not acknowledged it yet. | Wait. If it stays here, check device status, network, and that the app is running. | | `PROCESSING` | The terminal has the request and the cardholder is interacting with it. | Wait. Look at the terminal. | | `COMPLETED` | The session finished and a gateway response exists. | **Read** `xGatewayStatus` / `xTransactionResult`. **Completed is not the same as approved** — a decline is also `COMPLETED`. | | `TIMEOUT` | The terminal did not respond within the time limit. | Check the session result and the Gateway before retrying; do not assume the sale failed. | | `USER_CANCELLED` | Cancel was pressed on the terminal. | Treat as no sale. | | `API_CANCELLED` | The session was cancelled by the API (cancel command, or the sync connection was dropped). | Treat as no sale. Confirm the terminal is back on the idle screen before starting another session. | | `ERROR` | CloudIM, terminal, or gateway error, including declines on some paths. | Read `xSessionError` / `xGatewayError`. | ### Retrieving additional transaction details Every approved or declined transaction is a normal Sola Gateway transaction. Use the gateway `xRefnum` (`xGatewayRefnum` in V1) with the Gateway Reporting API for full details, and with the Gateway Transaction API for `cc:void`, `cc:capture` (after `cc:authonly`), and linked refunds. *** ## 8. Supported Commands `xCommand` selects what the terminal does. ### Credit | `xCommand` | Description | Amount required | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `cc:sale` | Sale. Also the tender-agnostic entry point: if the cardholder presents a debit card (or chooses Debit when prompted), the transaction runs as PIN debit. | Yes | | `cc:authonly` | Authorization only; capture later through the Gateway API (`cc:capture`). The terminal shows "Authorization Successful — Awaiting Capture". | Yes | | `cc:credit` | Refund to a card presented at the terminal. The terminal shows "Refund Processed Successfully". For a refund against a previous sale without the card, use the Gateway API (`cc:refund` with the original `xRefnum`). | Yes | ### PIN Debit There is no separate debit command. Debit runs through `cc:sale`: * The **TermLink credit/debit preference** on the device (Prefer Credit, Prefer Debit, or Customer Selects) decides how dual-interface cards are routed and whether the cardholder is asked to choose. * When the merchant's **cash back** setting is on and the request has no `xCashbackAmount`, the terminal always asks Credit or Debit first; Debit continues to the cash back prompt and PIN, Credit skips both. * Sending `xCashbackAmount` on a `cc:sale` forces the transaction to debit (cash back is a debit-only feature) and skips the cash back prompt. * PIN is entered on the PAX encrypted PIN pad. If the cardholder bypasses PIN (green key), the transaction completes as **signature debit** unless the merchant is configured to require PIN. * Keyed entry is hidden when the transaction is debit or when cash back is in the request. Keyed debit, where allowed, completes with automatic PIN bypass. ### EBT | `xCommand` | Description | Amount required | | --------------- | ---------------------------------------------------------------------------------------------- | --------------- | | `ebtfs:sale` | EBT Food Stamp (SNAP) purchase. | Yes | | `ebtfs:credit` | EBT Food Stamp return/refund. | Yes | | `ebtfs:return` | Alias of `ebtfs:credit`. | Yes | | `ebtfs:balance` | Food Stamp balance inquiry. | No | | `ebtcb:sale` | EBT Cash Benefit purchase. Optional cash back when the merchant's EBT cash back setting is on. | Yes | | `ebtcb:balance` | Cash Benefit balance inquiry. | No | EBT always requires PIN. Keyed EBT does not ask for CVV or expiration. Remaining balances come back as `xRemainingBalanceEBTFS` / `xRemainingBalanceEBTCB` and are shown on the approval screen and printed receipt. ### Gift | `xCommand` | Description | Amount required | | --------------- | -------------------------------------------- | --------------- | | `gift:issue` | Load value onto a new or existing gift card. | Yes | | `gift:redeem` | Pay with a gift card. | Yes | | `gift:balance` | Balance inquiry. | No | | `gift:activate` | Activate a card. | Yes | Keyed gift does not ask for CVV or expiration. The remaining balance is returned as `xRemainingBalance`. `gift:deactivate` is present in the Swagger `xCommand` enum but is reserved and not yet supported on Sola Terminal. Deactivate gift cards through the Transaction API instead. ### Device commands | `xCommand` | Description | | ----------------------- | ------------------------------------------------------------------------------ | | `device:cancel` | Cancel the session that is in progress on the device. See Canceling a Session. | | `device:reprintreceipt` | Reprint the receipt for a previous session on the device. | ### Field applicability by command | Field | Credit sale / auth | Credit refund | Debit (via `cc:sale`) | EBT sale / credit | Balance inquiries | Gift issue / redeem / activate | | --------------------------- | ------------------ | ------------- | --------------------- | ---------------------------- | ----------------- | ------------------------------ | | `xAmount` | Required | Required | Required | Required | Not used | Required | | `xTip` / `xEnableTipPrompt` | Yes (sale) | — | — | — | — | — | | `xCashbackAmount` | Forces debit | — | Yes | `ebtcb:sale` via prompt only | — | — | | `xInvoice` | Yes | Yes | Yes | Yes | — | Yes | | `xStreet` / `xZip` | Keyed only | Keyed only | — | — | — | — | | `xAllowDuplicate` | Yes | Yes | Yes | Yes | — | Yes | *** ## 9. Request & Response Reference ### Request fields These fields are sent flat in the V2 body. In V1, the fields marked *payload* go inside `xPayload`. | Field | Required | Type | Description | | ------------------------------ | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `xKey` | Yes (V2) | String | Your API key. V1 uses the `Authorization` header instead. | | `xDeviceId` | Yes | String | Device to run the session on. | | `xWebhookId` | No | String | Webhook to receive the result. | | `xCommand` | Yes (payload) | String | See Supported Commands. | | `xExternalRequestId` | Yes (payload) | String | Your unique ID for this request. **Max 32 characters.** Used to look up the result and to detect duplicates. | | `xSoftwareName` | Yes (payload) | String | Name of your software. | | `xSoftwareVersion` | Yes (payload) | String | Version of your software. | | `xAmount` | Yes for transactions (payload) | Numeric | Total to charge, **including** any tip you pass in `xTip`. Excludes surcharge (the terminal adds it) and cash back (added from `xCashbackAmount` or the prompt). Not used on balance inquiries. | | `xTip` | No (payload) | Numeric | Tip amount already included in `xAmount`. A positive `xTip` makes the terminal show base / tip / total for the cardholder to approve or decline. `0` or negative skips the confirmation. | | `xEnableTipPrompt` | No (payload) | Boolean | Ask the cardholder for a tip on the terminal before the card is read. Also enabled by the device setting `enableTipPrompt`. The tip chosen is added to `xAmount` and returned in the result. | | `xCashbackAmount` | No (payload) | Numeric | Cash back for a debit sale. Forces debit and skips the cash back prompt. Must not exceed the merchant's cash back maximum (default $100) or the sale amount. | | `xInvoice` | No (payload) | String | Invoice number. Max 20 characters. | | `xStreet` | No (payload) | String | Cardholder billing street, for AVS on keyed transactions. | | `xZip` | No (payload) | String | Cardholder billing ZIP, for AVS on keyed transactions. | | `xAllowDuplicate` | No (payload) | Boolean | Allow the gateway to process a transaction it would otherwise flag as a duplicate (same card, amount, and short time window). | | `xReferencedSessionId` | For `device:cancel`, `device:reprintreceipt` | String | Session to cancel or reprint. | | `xReferencedExternalRequestId` | For `device:reprintreceipt` | String | Alternative to `xReferencedSessionId`. | Unknown or unsupported fields on a session request return `400` with an `xError` naming the fields. [Additional Gateway Parameters](/products/cloudim-developer-guide/additional-gateway-parameters.md) lists the optional gateway parameters accepted by transaction commands. ### Response fields (V2) Returned by `POST /v2/session` and `POST /v2/session/result`. Fields with no value are omitted, so do not code against a key always being present. | Field | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `xResult` | `A` approved, `D` declined, `E` error, `I` in progress (result endpoint only), `S` success (non-transaction commands and async initiation). | | `xStatus` | `Approved`, `Declined`, `Error`, `InProgress`, `Success`. | | `xError` | Error or decline message when `xResult` is `E` or `D`. | | `xRefnum` | Sola Gateway reference number for approved/declined transactions; CloudIM reference (`cim…`) otherwise. | | `xAuthCode` | Issuer authorization code. | | `xAuthAmount` | Amount authorized, including tip, surcharge, and cash back. Negative on refunds. | | `xTranFee` | **Surcharge** amount applied by the terminal. Present only when a surcharge was applied; absence means no surcharge. | | `xBatch` | Batch number (`0` for auth-only). | | `xCardType` | `Visa`, `MasterCard`, `Amex`, `Discover`, `EBT`, `Gift`, etc. | | `xMaskedCardNumber` | e.g. `5xxxxxxxxxxx0078`. | | `xExp` | Card expiration `MMYY`. | | `xName` | Cardholder name from the card, when available. | | `xEntryMethod` | `EMV`, `Contactless_EMV`, `Swipe`, `Keyed`, etc. | | `xIsEMV` | `true` for chip/contactless EMV. | | `xAID`, `xAIDName` | EMV application ID and label (e.g. `A0000000031010`, `VISA DEBIT`). Useful to tell debit from credit. | | `xIAD`, `xTSI`, `xTVR` | EMV issuer application data, transaction status information, terminal verification results. Print these on EMV receipts. | | `xAvsResultCode` | AVS result (keyed with `xStreet`/`xZip`). | | `xCvvResult`, `xCvvResultCode` | CVV result (keyed credit). | | `xCurrency` | Currency code. | | `xErrorCode` | Gateway error code (`0` on approval). | | `xToken` | Card token for card-on-file follow-ups through the Gateway API. | | `xDate` | Gateway transaction date/time. | | `xRemainingBalance` | Remaining gift card balance (gift commands). | | `xRemainingBalanceEBTFS` | Remaining EBT Food Stamp (SNAP) balance at the time of approval, two decimals (e.g. `50.40`). Returned on EBT transactions when the processor supplies it. | | `xRemainingBalanceEBTCB` | Remaining EBT Cash Benefit balance at the time of approval, two decimals. Returned on EBT transactions when the processor supplies it. | | `xRemainingBalanceEBTW` | Reserved for eWIC: per-category remaining balances as a JSON list, e.g. `[{"CategoryCode":"19","Balance":"3.00"}]`. eWIC is not yet available on Sola Terminal. | {% hint style="info" %} **Note:** The EBT balances are the balances **at the moment of approval**, not a live balance. Use `ebtfs:balance` / `ebtcb:balance` for a current balance. {% endhint %} ### Session result fields (V1 and webhook) | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------ | | `xSessionStatus` | See Session statuses. | | `xSessionError` | CloudIM or device error message, if any (e.g. `Device Error: ABORTED`, `Transaction canceled`). | | `xGatewayRefnum` | Gateway reference number. | | `xGatewayStatus` | `Approved`, `Declined`, `Error`. | | `xGatewayError` | Gateway error message, if any. | | `xWebhookCallbackStatus` | Delivery status of the webhook callback, if a webhook was used. | | `xSessionCompletedTime` | ISO 8601 timestamp of session completion. | | `xTransactionResult` | Object with the same fields as the V2 response, including `xTranFee` and the remaining-balance fields. | | `xRefnum` | CloudIM reference for this API call (`cim…`). | | `xResult` | `S` the lookup succeeded, `E` the lookup failed. | *** ## 10. Terminal Behavior & Device Settings The Sola Terminal App's behavior is controlled by **device settings** managed by Sola. Merchants request changes through Support or their account manager; settings apply per device and can be inherited from account-level defaults. The terminal refreshes its settings periodically and after a remote re-initialize. | Setting | Effect on the terminal | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enableTipPrompt` | Prompt for a tip on every `cc:sale` (the request can also turn this on with `xEnableTipPrompt`). | | `promptForCreditDebit` | Ask the cardholder Credit or Debit before reading the card. | | `enableCashback` | Offer cash back on debit. When on, the terminal asks Credit or Debit first and only offers cash back after Debit is chosen. | | `cashbackPromptOptions` | Comma-delimited preset cash back amounts, up to 3 (e.g. `10,20,30`). A fourth button, **Custom**, lets the cardholder enter an amount up to the merchant's maximum. | | `enableEBTCBCashback` | Offer cash back on `ebtcb:sale`. Separate from debit cash back so it can be disabled where state rules require. | | `enableKeyed` | Show **Manually Enter Card Instead** on the card-present screen for credit. Keyed EBT and gift remain available even when this is off. | | `requireCVV` | Ask for CVV on keyed credit. | | `requireZipOnKeyed` | Ask for billing ZIP on keyed credit (sent as `xZip` for AVS). | | `enableMerchantReceipt` | Print the merchant copy automatically after approval. | | `enableCustomerReceipt` | Show a **Print Receipt** button on the approval screen for the customer copy. When off, the button reads **Close**. | | `disableAuthOnlyReceipt` | Suppress receipts for `cc:authonly`. | | `paymentSuccessConfirmationDurationSeconds` | How long the approval screen stays up before returning to idle. | | `enableFullScreenMode` | Kiosk mode: hides Android navigation and keeps the device locked to the Sola Terminal App. | ### What the cardholder sees **Idle.** Sola logo. The device waits for a CloudIM session. **Card present.** The amount and Swipe / Insert / Tap icons. If surcharging applies, a notice such as "A 3% surcharge ($0.38) will apply to credit card payments." is shown before the card is read. **Cancel** returns to idle and ends the session as `USER_CANCELLED`. **Manually Enter Card Instead** appears when keyed entry is enabled. **Keyed entry.** Card number (PAX secure keyboard), expiration, CVV (if required), ZIP (if required). EBT and gift skip CVV and expiration. **Credit vs. Debit prompt.** Shown when TermLink is set to *Customer Selects*, when cash back is enabled and no `xCashbackAmount` was sent, or after a swipe fallback. Debit continues to cash back and PIN; Credit does not. **Cash back.** Preset amounts, **Custom**, and **No Cash Back**. Skipped when `xCashbackAmount` is in the request. Cash back cannot exceed the sale amount or the merchant maximum. **PIN.** "Enter your PIN" with the PAX encrypted PIN pad. Used for debit and EBT. PIN never passes through the Sola UI, CloudIM, or your POS. **Tip.** With `xEnableTipPrompt` or `enableTipPrompt`: tip options including $0 and a custom amount, followed by an Amount / Tip / Total confirmation. With a positive `xTip` from the POS: the Amount / Tip / Total confirmation only; if the cardholder declines, the session ends with an error and nothing is charged. **Surcharge (credit only).** When the merchant is surcharge-enabled (and the surcharge effective date has passed), the terminal calculates the fee from the merchant's Sola surcharge settings, discloses it before the card is read, adds it to the authorization, prints it as a separate receipt line, and returns it as `xTranFee`. Debit, EBT, and gift are never surcharged. If the merchant stops being surcharge-enabled, the terminal stops surcharging without any POS change. **Processing.** "Processing…" while CloudIM and the gateway authorize. **Approval.** "Approved — Thank You" (or "Authorization Successful — Awaiting Capture", "Refund Processed Successfully"). When a surcharge applied, the screen shows Sub-total / Surcharge / Total. Gift and EBT show the remaining balance. Optional **Print Receipt** button. "Remove Card" is shown while a chip card is still inserted. **Decline / error.** A red banner with the gateway or device message (e.g. `Invalid Card # (Length = 15)`, `Printer Error: OUT OF PAPER`, `Transaction canceled`). Retryable errors stay on the banner so the cardholder can try again; non-retryable errors end the session. **Receipts.** Printed on the terminal according to the receipt settings. EMV data (`xAID`, `xTVR`, `xTSI`, `xIAD`), surcharge, tip, cash back, and EBT/gift balances are printed when applicable. "Printing… Please wait…" is shown while printing. ### Displaying surcharge on the POS When `xTranFee` is present, show and print it as a separate line: ``` Sub-total $12.50 (xAmount) Surcharge $0.38 (xTranFee) Total $12.88 (xAuthAmount) ``` If `xTranFee` is absent, no surcharge was applied. *** ## 11. Canceling a Session & Reprinting a Receipt ### Cancel from the POS Send `device:cancel` for the device, referencing the session to cancel: ```http POST https://device.cardknox.com/v2/session Content-Type: application/json { "xKey": "", "xDeviceId": "1ac25fc88-da3a-44ba-9b8f-0db642613cb7", "xCommand": "device:cancel", "xReferencedSessionId": "session111004629", "xCancelMessage": "Cancelled by cashier", "xExternalRequestId": "pos7-20260903-000484-cancel", "xSoftwareName": "MySoftware", "xSoftwareVersion": "1.0.0" } ``` The terminal aborts the prompt, shows "Transaction canceled", and returns to idle. The original session ends with status `API_CANCELLED`. V1 equivalent: `POST /v1/Session/cancel` with `{ "xDeviceId": "...", "xCancelMessage": "..." }` (cancels whatever session is running on the device). A cancel can only stop a session before the authorization is sent. If the terminal has already sent the authorization, the session will complete; check the result and void through the Gateway API if needed. ### Reprint a receipt ```http POST https://device.cardknox.com/v2/session Content-Type: application/json { "xKey": "", "xDeviceId": "1ac25fc88-da3a-44ba-9b8f-0db642613cb7", "xCommand": "device:reprintreceipt", "xReferencedExternalRequestId": "pos7-20260903-000481", "xExternalRequestId": "pos7-20260903-000481-reprint", "xSoftwareName": "MySoftware", "xSoftwareVersion": "1.0.0" } ``` Use `xReferencedSessionId` or `xReferencedExternalRequestId` to identify the original transaction. The device must be `CONNECTED` and idle. *** ## 12. Errors ### Error response shape ```json { "xResult": "E", "xStatus": "Error", "xError": "xKey required", "xRefnum": "cim215376719" } ``` V1 endpoints omit `xStatus`. Always log `xRefnum` — Support uses it to find the request. ### HTTP status codes | HTTP | Meaning | | ----- | --------------------------------------------------------------------------------------------------------------------------- | | `200` | Request processed. For transactions, read `xResult` — a decline is still `200`. | | `400` | Validation error: missing or unsupported field, bad value, duplicate `xExternalRequestId` (V1), cash back over the maximum. | | `401` | Missing or invalid API key. | | `403` | The key is not allowed to use this device or session (different account). | | `404` | Device, session, or webhook not found. | | `500` | Server error. Retry with the same `xExternalRequestId` after checking the session result. | | `504` | Timed out waiting for the device (async initiation). Check the session result before retrying. | ### Common `xError` values | `xError` | Cause | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `'Authorization' header is missing` / `Unauthorized` | V1 call without a valid key. | | `xKey required` | V2 call without `xKey` in the body. | | `A non-empty request body is required.` | Empty body. | | `The xDeviceSerialNumber field is required.` (etc.) | Missing required field. | | `Device not found` | Wrong `xDeviceId`, or the device belongs to another account. | | `Device is not available` | Device is `BUSY`, `DISCONNECTED`, or `NOT_REGISTERED`. | | `Cashback Exceeds Max Amount: $100` | `xCashbackAmount` above the merchant maximum. | | `Transaction canceled` | Cancelled on the terminal or by the API. | | `Device Error: TIME OUT` | The cardholder did not complete the prompt in time. | | `Device Error: ABORTED` | The terminal aborted the card read. | | `Printer Error: OUT OF PAPER` | Receipt could not print (the transaction itself may have been approved). | | Gateway messages (`Declined`, `Invalid Card # (Length = 15)`, `Insufficient Funds`, …) | Processor or gateway decline. | *** ## 13. Troubleshooting & Common Issues **Invalid API key.** Confirm the key is active in Portal → Keys and that you are sending it the right way for the endpoint version (header for V1, `xKey` in body for V2). Confirm the key and the device belong to the same account and environment. **Device status is** `DISCONNECTED`. Check power and network. Open the Sola Terminal App (or reboot the terminal) and wait for the idle screen. If the device stays disconnected, verify that the app's **Backend** parameter matches the environment you are calling. **Device status is** `NOT_REGISTERED` **or the app shows a serial-number alert.** The auth token on the device does not match the terminal or the merchant account. Contact Support to re-issue the token. **Device status is** `BUSY` **but nothing is on the screen.** A previous session may still be finishing. Wait for the processing timeout (up to 180 seconds), or send `device:cancel`. **Session stays** `INITIATING`. The terminal never acknowledged the request: wrong `xDeviceId` (serial number and Device ID are different things), the device is offline, or the app is not running. **Session ends with** `TIMEOUT` **but the cardholder says they paid.** Look up the session by `xExternalRequestId` and check the Gateway before retrying. A timeout can still carry an approved transaction. `Device is not available` **after an account-setting change.** After certain account changes the terminal must re-initialize. Support can trigger this remotely; PAXSTORE parameter pushes also re-initialize the app after the current transaction ends. Wait for the idle screen and retry. **Terminal shows a different payment app instead of the Sola idle screen.** The device was not boarded for Sola Terminal. Sola Terminal requires TermLink + Sola Terminal App only; contact Deployments. **Receipts do not print.** Check paper and battery (A920 Pro prints at 7% or higher, A920 MAX at 1% or higher) and the receipt settings for the device. `device:reprintreceipt` can reprint once the issue is fixed. **Surcharge is not applied / is applied unexpectedly.** Surcharge follows the merchant's Sola surcharge settings and effective date, and only applies to credit. The POS cannot turn it on or off per transaction. **The POS shows a failure but the terminal and gateway approved.** Your POS timed out or mis-mapped the response. Raise the HTTP client timeout above 200 seconds for sync calls, and always reconcile with `POST /v2/session/result` by `xExternalRequestId`. When contacting Support, include: MID, last four of the API key, terminal serial number, `xDeviceId`, `xSessionId`, `xExternalRequestId`, the CloudIM `xRefnum` (`cim…`), the gateway `xRefnum`, the terminal model, and the Sola Terminal App version (from `GET /v1/Device/{xDeviceId}`). *** ## 14. FAQs **Q. How do I start Sola Terminal on the device?** A. It starts automatically when the terminal boots and shows the Sola idle screen. No user action is needed. **Q. How do I get to the terminal's Wi-Fi / Android settings when kiosk mode is on?** A. Tap the four corners of the screen (clockwise) and enter today's date as `MMDDYYYY`. Choose the Wi-Fi network from Android settings, then return to the app. **Q. How do I run a debit sale?** A. Send `cc:sale`. The terminal handles Credit vs. Debit routing (per the device's TermLink preference and prompts) and PIN entry. To pre-set cash back, add `xCashbackAmount`, which forces debit. **Q. How do I know if a transaction was debit or credit?** A. Check `xAIDName` (e.g. `VISA DEBIT`) and `xEntryMethod` on the response, and the transaction type in Gateway reporting. **Q. Can I surcharge through CloudIM?** A. Yes, on Sola Terminal only. Surcharging is enabled on the merchant account by Sola; the terminal discloses and applies it automatically and returns the fee in `xTranFee`. **Q. Can I use the same** `xExternalRequestId` **twice?** A. No. It must be unique per request (max 32 characters). Reuse returns a duplicate error; use `POST /v2/session/result` with the ID to get the original result. **Q. Can I void or refund from CloudIM?** A. Use `cc:credit` on the terminal for a card-present refund. For voids, captures, and refunds against a prior transaction, use the Gateway API with the gateway `xRefnum` returned by CloudIM. **Q. Is eWIC supported?** A. Not yet. eWIC on Sola Terminal is in development; `xRemainingBalanceEBTW` is reserved for it. **Q. Where are the Swagger docs?** A. *** ## 15. What's New Changes since the previous CloudIM Developer Guide, as they apply to Sola Terminal: * **Sola Terminal** (Sola Terminal App + TermLink) is the device stack for all CloudIM merchants. Sola owns the cardholder screens, prompts, and receipts. * **Supported devices** are A920 Pro and A920 MAX A3700, A6630, A6650, A35 and A80. * **PIN debit and cash back** via `cc:sale`, with `xCashbackAmount`, cash back prompt presets, Credit/Debit selection, and signature-debit PIN bypass. * **EBT**: `ebtfs:sale`, `ebtfs:credit`, `ebtfs:return`, `ebtfs:balance`, `ebtcb:sale`, `ebtcb:balance`; `xRemainingBalanceEBTFS` / `xRemainingBalanceEBTCB` on results. * **Gift**: `gift:activate` with no amount is no longer converted to `gift:issue`; `xRemainingBalance` on results. * **Surcharge**: terminal-side disclosure and calculation; `xTranFee` on V1 and V2 results. * **Tip**: a positive `xTip` is shown to the cardholder for approval instead of being ignored; tip prompts allow $0 and custom amounts. * **Keyed entry** with optional CVV and ZIP; keyed EBT/gift without CVV/expiration. * **Receipts** on the terminal (merchant / customer / auth-only settings) and `device:reprintreceipt`. * `device:cancel` command on V2 with `xReferencedSessionId` and `xCancelMessage`. * **Result lookup by** `xExternalRequestId` on V1 and V2. * **Device statuses** `BUSY`, `NOT_REGISTERED`, `UPDATE_NEEDED`; devices are marked `BUSY` at session start to prevent overlapping sessions. * **Clearer error responses**: validation and auth failures return an explicit `xError` with a `cim` `xRefnum` instead of a generic 401. * **Timeouts** tightened to 15 s initiation / 180 s processing; dropping a sync connection cancels the session. * `xAllowDuplicate` request field. * `xExistingDeviceFound` on `POST /v1/Device` when the serial number is already registered. * **Kiosk (full-screen) mode**, remote re-initialize after account changes, and re-initialize after PAXSTORE parameter pushes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.solapayments.com/products/cloudim-developer-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.