Documentation

Environment

Set up and manage your InStore environment.

Environment setup

You must request at least one environment for each currency where the retailer does business. You can request additional environments by contacting us.

The first time you log in, some information for your environment will already be populated. The Environment page is where you select global settings for parameters and receipts that will apply by default to all locations in the current environment. These can be overridden later for one or more locations.
The environment type, such as Test or Production, is always displayed in the Environment Information section title. If the flag in the title says New, then you must activate the environment before you can add locations to it.

Access environment settings

  1. If you have received more than one environment, click Settings (gear icon) > Switch Environment to verify you're in the correct environment. If you're not, select the environment and click Switch.
  2. Within the InStore Center, access the Environment menu option.

General tab

The general tab on the Environment page is where you assign basic identifying information, some of which may be used on receipts or may influence settings at the location and workstation levels.

  1. You can assign the following:

    • Label: optionally, rename the default label to a short name. Only administrators see this label, which is used for switching among environments.
    • Name: assign a unique name for the environment, such as "Wales-All."
    • Description: provide a description that identifies the intended purpose and users of the environment, such as "Test Environment for All Wales Locations."
    • TaxId: provide the tax ID or VAT identifier to print on receipts, if the retailer prints this information. Use sample information for test environments.
    • Locale: select a locale (geography-specific language) to apply by default to locations in this environment. InStore uses ISO notation to identify the locale. For example, en-US indicates English as spoken in the USA. This field lists all locales that InStore supports.
    • Currency: select a currency to apply to this environment. After saving this environment as active, you cannot change this selection. InStore assumes a single currency. If the retailer's business covers multiple currencies, you'll need to request additional environments.
    • Parameter Set: select the parameter set to apply by default to locations in this environment. This can be overridden later for individual locations and workstations. See Parameter sets.
    • Template Set: select the receipt template set to apply by default to locations in this environment. This can be overridden later for individual locations. See Receipt templates.
  2. Click Save Changes.

Payment Processors tab

The Payment Processors tab on the Environment page is where you add, edit, or delete the payment processors that handle payment and refund transactions at workstations within the environment.

  1. View the processors that have been registered for this environment, if any.

  2. Optionally, click the icon to edit or delete a processor.

  3. Optionally, click Add Payment Processor and complete these fields for a new processor:
    • Processor: select a processor from the available options. If you select Custom, you must define a connection for each payment type to be processed. For more information about how to do this, see Payment extensions.
      The Simulator option is deprecated, do not select it.
    • Custom Processor Name: displayed only if the processor is Custom. Provide the name to display to administrators during location setup.
    • Supported Payment Types: select from among Credit Card, Gift Card, Wallet, Pay by Link, and Pay on Account as available.
    • Timeout: displayed only if the processor is Custom. Enter the number of milliseconds to wait for a response from the payment provider before determining that there is no response. The default value is 15000 (15 seconds). If specified, this value is passed with other custom payment information in the processAsyncPostRequest calls in the creditProxyAPI of mist-client.
    • Processor Key: displayed only if the custom processor is Adyen, Stripe, or Citcon. As appropriate, enter a valid test key or production key that was provided by the processor vendor. on setup.
    • Supported Payment Types: select from Credit Card, Gift Card, Wallet, Pay by Link, and Pay on Account as available.
    • Processor Verification Key: displayed for each payment type associated with this processor. Enter a valid key that was provided by the processor vendor.
    • Processor (Webhook) Url: displayed for each payment type associated with this processor. Enter the valid webhook URL where InStore should send payment information.
    • Test/Production: displayed only if the custom processor is Adyen. Use the toggle to indicate whether this is a test or production configuration.
    • Merchant ID: displayed only if the custom processor is Adyen. Provide the retailer's Adyen credential.

      Never use production level keys or credentials for testing.

  4. Click Add.

Project settings tab

The values on the Project settings tab of the Environment page are required for InStore to connect to the retailer's Composable Commerce project.

  1. Complete these fields:

    • Project Key: this value was generated during self-serve Composable Commerce project creation. Retrieve the value that you saved then. The Project Key must be at least two characters long
    • Client Secret: click the icon to input the identifier, which is a string of random characters generated by Composable Commerce when the API Client is created. Save this in a secure location because you cannot access it again from the InStore Center.
    • Client ID: this value was generated during the self-serve Composable Commerce project creation.
    • Auth URL: this value was generated during the self-serve Composable Commerce project creation.
    • Host: this was called API URL in your project.
    • Scopes: the list of scopes was generated during the self-serve Composable Commerce project creation. We recommended creating individually controlled entries by pasting a comma-delimited list and then pressing Enter. Do not insert a space-delimited or line-break-delimited list.
    • Cart Key Prefix: optionally, specify a prefix for the generated cart key (order number). If provided, this must be an alphanumeric value of 1-6 characters.
    If provided, the value of Cart Key Prefix must be unique across all environments connected to the same commercetools project. Assign a distinct prefix per environment to avoid conflicts, especially when a retailer reuses the same location and workstation numbers in each of its environments, which is a common practice.
    • Cart Key Sequence Length: specify the length for the transaction sequence number portion of the generated cart key (order number). This can be a numeric value between 3 and 12, and is usually a customary 6. The generated cart key conforms to Composable Commerce cart requirements.
    Use caution when modifying Cart Key Prefix or Cart Key Sequence Length. Changing these values may lead to duplicate order numbers in future transactions.
    • InStore Order Type: the key that identifies this type that you defined in your API.
    • InStore Lineitem Type: the key that identifies this type that you defined in your API.
    • Customer Type: the key that identifies this type that you defined in your API.
    • InStore Payment Type: the key that identifies this type that you defined in your API.
    • Transaction Type: the key that identifies this type that you defined in your API.
  2. Click Save Changes.

If you must change any of these values (such as scopes), you will need to replace the API client to include the new values and update the mappings shown on this page. It is good practice to replace the API client periodically for better security.

Custom Fields tab

  1. Enter the names of the Attributes that will be used for Barcode Array and Receipt Text fields. Ensure that these attributes exist on all Product Types and values are included on all Product Variants to be used in InStore implementations.
  2. In the next pane, review the list of required attributes derived from your Composable Commerce project.
  3. In the Custom Field column for each, verify or correct the corresponding field name as it exists in your implementation of InStore. The options must match your Composable Commerce Project. For more information, see Mapping Custom Fields and List of Custom Fields.
  4. Click Save Changes in the top pane.

Integration settings tab

The Integrations settings tab contains important information for connecting each environment to its own integration server.
The value in the Tenant ID field uniquely identifies this environment. It is not available for editing.
The value in the Connection Key field authorizes your store application and digital retail platform to communicate with InStore.

If the connection key ever becomes lost or compromised, you will be directed to generate a replacement key for the retailer's developer to insert into the InStore colleague app code.

Do not click the Generate New Connection Key button when locations are open for business. If you generate a new key, all locations and other administrators with access to InStore Center will be locked out, and your store application instances will not be able to connect to InStore. You must communicate the new connection key to administrators offline, and your store application must be programmed to use the new connection key.

To generate a new key, complete these actions:

  1. Access the Environment menu option.
  2. On the Integration Settings panel, click Generate New Connection Key.
  3. Click Copy Key to Clipboard.
  4. Click Save Changes to activate the new key. If you didn’t mean to generate a new key, navigate away from the page without saving.

  5. Paste the key into a safe location.

  6. Complete the following settings, substituting * with a unique, assigned integration-server URL. Webhook URL is the fully specified internet location where the InStore server will provide responses for your store application to retrieve.
    Setting nameValue you type after the URL
    Webhook URL*/webhooktest
    Webhook Verification KeyUse the same value as your integration server value.
    Webhook API Key(Request from commercetools)
    Cart Retrieval URL*/commercetools/checkout/
    Return Cart Retrieval URL*/commercetools/refund/
  7. In the Webhook API Key field, enter the verification key or header token that the retailer's API gateway expects to precede all inbound requests. This value is set on the Composable Commerce cart retrieval server where the x-api-key header sent from the MIST API server is validated (for example, in the /checkout/:cartId endpoint). You can only set or reset the key here; you cannot view it. For security purposes, this key is hidden from all API responses.
  8. Complete the following settings, substituting * with the URL of your store application followed by the suffixes shown. The format should be similar to https://store.nebulaterra.com/*.
    Setting nameValue you type after the URL
    Token Retrieval URL*/usertoken/
    Callback API KeyUse the same value as your integration server value.
    Key Sync URL*/tenant
    Sync API KeyUse the same value as your integration server value.

Activate Environment button

The Activate Environment button is available only after you complete the necessary fields. If it is not available for a new environment, verify that you have completed required fields on the previous tabs and have at least one processor listed. You must also have set up at least one Store Role and an administrator.
After the environment is activated, you can add and activate locations, however, you must refresh the InStore Center app before adding locations.

Allowed URLs tab

This tab is a place to add external domains that are allowed to interact with this retailer's instance of InStore.

  1. Enter an allowed URL in the field.
  2. Click Add Allowed URL.
  3. Optionally, use the Actions icons to edit or delete a listed URL.

Theme tab

The Theme tab contains information about making changes to the Responsive Material UI theme that determines application interface details. You can brand the interface and make InStore better match the fonts, buttons, icons, and colors in your store application. To modify the appearance of InStore, complete these actions:
  1. In the Logo field, specify a file to display in the InStore interface that users will see. It is best to use files with a PNG or JPG extension and avoid BMP files.
  2. In the Font Family field, select a font that is supported by the retailer's application.
  3. Toggle the Header Visible on or off. Toggle it on to include a page title on components that are retrieved when needed by the retailer's mobile calling app or mobile or fixed clienteling app. To avoid duplicate headers, toggle this off if the retailer runs InStore as a federated component in a point-of-sale context.
  4. In the Colors fields, select main and secondary colors for online display, expressed as industry-standard RGB hex color codes.
  5. Click Save. The changes are visible the next time a user logs into InStore.