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.

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

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

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

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.

Custom Fields tab

1. Enter the names of the Product 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

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.

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 name	Value you type after the URL
   Webhook URL	*/webhooktest
   Webhook Verification Key	Use 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 name	Value you type after the URL
   Token Retrieval URL	*/usertoken/
   Callback API Key	Use the same value as your integration server value.
   Key Sync URL	*/tenant
   Sync API Key	Use the same value as your integration server value.

Activate Environment button

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

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.