Skip to main content

CCC Configurations

The Checkout App's settings are configured using the Customer Controlled Configuration (CCC) API. This service enables remote configuration management for different platforms.

The app currently utilizes the cha.settings.v1 schema. Remote settings and configurations are retrieved during login action.

Table of Contents

How to configure

Link to schema cha.settings.v1 Link to CCC Api Documentation

The schema outlines properties and types, with validations to be implemented subsequently.

Currently, only the "host" property is mandatory and will default to "https://testrunner-eu.checkout-api.retailsvc.com".

The ccc-api OpenAPI JSON collection facilitates the adding of configurations via tools such as Postman or Swagger, offering interim functionality until the development of a dedicated configuration portal.

⚠️ Important: Configuration settings can be defined at the workstation, business unit, business unit group, or tenant level. In the absence of specific configurations at lower levels, they will be inherited from higher levels, if available.

Here is example of curl request for updating the configuration on workstation level.

curl --location --request PUT 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"server": {
"host": "https://testrunner-eu.checkout-api.retailsvc.com",
"networkCallTimeout": 30000
},
},
"mpos": {
"server": {
"host": "https://testrunner-eu.checkout-api.retailsvc.com",
"networkCallTimeout": 20000
}
}
}
}'

POS Settings

Minimum required setup

In order to have a workable workstation, the Checkout App requires a two-step setup process:

  1. Initial Workstation Settings

    See Minimum required settings for desktop

  2. CCC API Configuration

    Minimum required:

    • Server settings (link)
    • SCO enabled setting if using SCO (link)

See below for complete configuration options.

Server (required)

  • host (required) - The Checkout Engine server that the workstation should connect to. This is a domain name, a computer name or an IP address
  • networkCallTimeout (required) - Specifies number of milliseconds to wait while the server performs the request. If the server doesn't send the response during this timeout, corresponding error will be displayed

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"server": {
"host": "https://testrunner-eu.checkout-api.retailsvc.com",
"networkCallTimeout": 30000
}
}
}
}'

Edge (optional)

  • host - Host URL for offline Edge solution. This setting is required if using Checkout Client connected to a Edge deployed Checkout Engine

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"edge": {
"host": "https://testrunner-eu.checkout-api.retailsvc.com/"
}
}
}
}'

Peripherals (optional)

  • scanner (scanner1 and scanner2):
    • logicalName (required) - Scanner's logical name, specified in config file (jpos.xml)
    • autoConnect (required) - Enables auto connect after app loading
  • printer:
    • enabled (required) - If this variable is on (true) then the system will try to connect to a real printer
    • autoConnect (required) - Enables auto connect
    • logicalName (required) - Printer's logical name specified in configuration file (jpos.xml)
    • cashdrawerEnabled - If true, then Checkout Engine will try to use a real cashdrawer. If false, then emulated cashdrawer will be used instead, optional
    • cashdrawerLogicalName - Specifies logical name of the cashdrawer in the configuration file of the printer (jpos.xml), as the cashdrawer is connected using printer, optional

Note: To run dummy peripherals:

  • printer:
"printer": {
"enabled": true,
"autoConnect": true,
"logicalName": "Emulator",
}
  • scanner - no support for dummy scanner

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"peripherals": {
"scanner1": {
"logicalName": "SCANNER1",
"autoConnect": true
},
"scanner2": {
"logicalName": "SCANNER2",
"autoConnect": true
},
"printer": {
"enabled": true,
"autoConnect": true,
"logicalName": "PRINTER1",
"cashdrawerEnabled": true,
"cashdrawerLogicalName": "CASHDRAWER1"
}
}
}
}
}'

Lock (optional)

  • timeout - Number of idle seconds before automatically being logged out from the App if there are no active receipt (default: 0)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"lock": {
"timeout": 300
}
}
}
}'

Receipt (optional)

  • clearTimeout (required) - Duration for finalized receipt on screen visibility after finalization in milliseconds (default: 5000)
  • layout (optional):
    • identifierType - Type of identifier to display ("id" or "barcode", default: "ID")
    • visibleAttributes - Array of visible attributes ("color", "size")

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"receipt": {
"clearTimeout": 5000,
"layout": {
"identifierType": "barcode",
"visibleAttributes": ["color", "size"]
}
}
}
}
}'
  • enabled - Enables embedded url links in the Checkout App GUI (default: false)
  • links - Embedded URL links list
    • url (required) - External web page url
    • name (required) - Name of the web site to display in the choice list
    • shareAuthorizationToken (optional) - Set true to share authorization token with this website
    • shareRetailInformation (optional) - Set true to share retail info like: countryCode, businessunitId, workstationId, operatorId, tenantId

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"externalLinks": {
"enabled": true,
"links": [
{
"url": "https://example.com/support",
"name": "Support Portal",
"shareAuthorizationToken": true,
"shareRetailInformation": false
}
]
}
}
}
}'

Variant Search (optional)

  • enabled - Enables variant search functionality (default: false)

Note: A pre-requisite for this functionality is that you have correctly applied item links on your items and provided into Hii Retail in the Item Input api's.

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"variantSearch": {
"enabled": true
}
}
}
}'

Prompt (optional)

  • integerMonetary - If on (true) then monetary inputs will have value without decimals (with .00 at the end)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"prompt": {
"integerMonetary": true
}
}
}
}'

Auto Update (optional)

  • channel (required) - Release channel ("preview", "stable")

Note: All new updates will appear in the preview channel before being promoted to the stable channel. A preview channel will get preview and stable updates. A stable channel will get only stable updates. Customers are encouraged to setup a few tills on the preview channels to test drive new updates before being promoted to stable

  • Maintenance window settings (required) - The maintenance window for the update
    • days (required) - Days of the week when the maintenance can occur (["MO", "TU", ...]), min items - one
    • start (required) - The start time of the maintenance window. Specify in the UTC time zone (18:00)
    • end (required) - The end time of the maintenance window. Specify in the UTC time zone (24:00)

Note: During this window the update will download and install automatically. To start update, the app must be open else it will try to update on the next maintenance window. The maintenance window is applied to preview and stable channels for major, minor and patch updates(see semantic versioning)

  • Maintenance Exclusion settings - The maintenance exclusion window for the update, optional
    • start (required) - The start date and time of the maintenance exclusion. UTC time zone (2024-01-14T07:00:00.000Z)
    • duration (required) - The number of days from the start date for the maintenance exclusion to take precedence

Note: The exclusion maintenance period takes precedence over any scheduled maintenance window. Maximum of 30 days allowed. The exclusion window is applied only for stable channel and only for major and minor updates (we follow semantic versioning best practices (semver.org) for all of our updates)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"autoUpdate": {
"channel": "stable",
"maintenanceExclusion": {
"start": "2024-01-14T07:00:00.000Z",
"duration": 5
},
"maintenanceWindow": {
"days": ["MO", "TU", "WE"],
"start": "18:00",
"end": "24:00"
}
}
}
}
}'

Additional Settings

Fullscreen (required)

Kiosk (required)

Item Pictures (optional)

Price Verification (optional)

Theme (optional)

Wallpaper URI (optional)

Logs (optional)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"pos": {
"fullscreen": true,
"kiosk": false,
"itemPicturesEnabled": true,
"priceVerificationEnabled": true,
"wallpaperUri": "https://example.com/wallpaper.jpg",
"logs": {
uploadEnabled: true
},
"theme": {
"colors":{
"primary":"#484543",
"primaryLight":"#A5A29F",
"primaryDark":"#262422"
}
}
}
}
}'

SCO Settings

Enable SCO (optional)

If on (enabled: true) then SCO will be enabled with the casco OCMS (default: false)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"enabled": true
}
}
}
}'

Session alive time (required)

  • sessionKeepAliveInterval - Time to keep session alive. If this variable is missing, 10 minutes interval is used as default. To be set in milliseconds

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"sessionKeepAliveInterval": 600000
}
}
}
}'

Receipt (optional)

  • layout:
    • identifierType - Type of identifier to display ("id" or "barcode", default: "ID")
    • visibleAttributes - Array of visible attributes ("color", "size")

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"receipt": {
"layout": {
"identifierType": "barcode",
"visibleAttributes": ["color", "size"]
}
}
}
}
}'

Bags (optional)

  • enabled (required) - If on (true) then SCO Bags button will be shown (default: false)
  • paperBag (required):
    • ean (required) - EAN of the paper bag
    • title (required) - Name of the paper bag
  • plasticBag (required):
    • ean (required) - EAN of the plastic bag
    • title (required) - Name of the plastic bag

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"bags": {
"enabled": true,
"paperBag": {
"ean": "10001",
"title": "Paper bag"
},
"plasticBag": {
"ean": "10002",
"title": "Plastic bag"
}
}
}
}
}'

Language (optional)

  • availableLanguages (required) - Defines the available languages in SCO mode. Comma separated i.e en-GB,sv-SE (default: "en-GB,sv-SE,de-DE,fr-FR,es-ES,da-DK,fi-FI,nb-NO")
  • defaultLanguage (required) - Default language (default: "en-GB")

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"language": {
"availableLanguages": "en-GB,sv-SE,de-DE,fr-FR,es-ES,da-DK,fi-FI,nb-NO",
"defaultLanguage": "en-GB"
}
}
}
}'

PLU (optional)

  • enabled (required) - Enables PLU button in SCO mode
  • shortcutsEnabled - Allows PLU shortcut items button in main view (default: false)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"plu": {
"enabled": true,
"shortcutsEnabled": true
}
}
}
}'

Loyalty (optional)

  • countryCodePrefix (required) - Prefix for loyalty card phone number input.
  • cardReminderEnabled - Enables loyalty card reminder dialog (default: false)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"loyalty": {
"countryCodePrefix": "+503",
"cardReminderEnabled": true
}
}
}
}'

Lock (optional)

  • enabled (required) - If on (true) then SCO lockscreen feature will be enabled (default: false)
  • timeout - Number of idle seconds before appearance of the sco lockscreen (default: 15)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"lock": {
"enabled": true,
"timeout": 300
}
}
}
}'

Attendant (optional)

  • enabled (required) - If on (true) the attendant feature in SCO mode is enabled

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"attendant": {
"enabled": true
}
}
}
}'

Logo URI (optional)

  • logoUri - URI for logo in SCO mode (must be HTTPS URL or base64 data URI for jpg/jpeg/png)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"logoUri": "https://example.com/wallpaper.jpg"
}
}
}'

Call Assistant (optional)

  • callAssistantEnabled - Enables call assistant button (default: false)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"callAssistantEnabled": true
}
}
}'

Decrease Enabled (optional)

  • decreaseEnabled - Allows item quantity decrease (default: false)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"sco": {
"decreaseEnabled": true
}
}
}'

CFD Settings

Auto Start (required)

  • autoStart - If on (true) then CFD is displayed when the app is loaded without manual opening (default: false)

Welcome Message (optional)

  • welcomeMessage - After opening, CFD will show the CFD welcome message until you start a new receipt. Minimum formating is supported in the form of new line breaks. e.g "Before \n after break line."

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"cfd": {
"autoStart": true,
"welcomeMessage": "Welcome \n Scan your items"
}
}
}'

MPOS Settings

Minimum required setup

At least the folodwing should be set to have a workable MPOS:

  1. Initial Workstation Settings

    See Minimum required settings for mobile

  2. CCC API Configuration

    Minimum required:

    • Server settings (link)

See below for complete configuration options.

Server (required)

  • host (required) - The Checkout Engine server that the workstation should connect to. This is a domain name, a computer name or an IP address
  • networkCallTimeout (required) - Specifies number of milliseconds to wait while the server performs the request. If the server doesn't send the response during this timeout, corresponding error will be displayed

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"mpos": {
"server": {
"host": "https://testrunner-eu.checkout-api.retailsvc.com",
"networkCallTimeout": 30000
}
}
}
}'

Receipt (optional)

  • clearTimeout (required) - Duration for finalized receipt on screen visibility after finalization in milliseconds (default: 5000)
  • layout (optional):
    • identifierType - Type of identifier to display ("id" or "barcode", default: "ID")
    • visibleAttributes - Array of visible attributes ("color", "size")

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"mpos": {
"receipt": {
"clearTimeout": 3000,
"layout": {
"identifierType": "barcode",
"visibleAttributes": ["color", "size"]
}
}
}
}
}'

Peripherals (optional)

  • printer:
    • enabled - Enables the printing, optional

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"mpos": {
"peripherals": {
"printer": {
"enabled": true
}
}
}
}
}'

Connect (optional)

  • provider - Sets the Soft terminal provider ("viva", "softpay", or null), default: null

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"mpos": {
"connect": {
"provider": "softpay"
}
}
}
}'

Lock (optional)

  • timeout - Number of idle seconds before automatically being logged out from the App if there are no active receipt (default: 0)

Example:

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"mpos": {
"lock": {
"timeout": 300
}
}
}
}'

MPOS Additional Settings

Theme (optional)

Wallpaper URI (optional)

Logs (optional)

Example

curl --location --request PATCH 'https://ccc-api.retailsvc.com/api/v1/config/cha.settings.v1/values/business-units/{businessUnitId}/workstations/{workstationId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **INSERT_YOUR_TOKEN_HERE**' \
--data '{
"value": {
"mpos": {
"wallpaperUri": "https://example.com/wallpaper.jpg",
"logs": {
uploadEnabled: true
},
"theme": {
"colors":{
"primary":"#484543",
"primaryLight":"#A5A29F",
"primaryDark":"#262422"
}
}
}
}
}'