Documentation

InStore integration overview

Learn how to integrate with commercetools InStore.

We recommend following the backend-for-frontend (BFF) pattern for your integration. All calls to InStore APIs should be done from a secure server. Tenant IDs, connection keys, and access tokens should not be sent to the client application. The only token that should be provided to the client is a user access token, which cannot be used to access InStore APIs. It can only be used by InStore to identify a user and their permissions. All other services should be fronted by the integration service.

Integration patterns

All InStore processes, such as payments or refunds, follow the same integration pattern with your commerce application. InStore assumes that you will use an integration server to manage the integration between InStore and Composable Commerce, as described above.

Get a user access token

All operations between the client/host application and InStore require a user access token. This should only be requested after the user has been authenticated by your identity management system (IMS).

The following diagram demonstrates the login process:

Component model

If your application is built using webpack 5.0 or greater, such as on React, Angular, or Vue, then you can use InStore as a federated component—in this case, treat InStore as a component in your application. When you render an InStore component with the necessary parameters such as, cart ID, location, and workstation, then InStore completes the necessary steps for you. When InStore has completed the transaction, it emits a custom event to notify the host application so the next appropriate step may be taken.

Callbacks

When InStore collects payment or processes refunds for a Cart, it must first retrieve the Cart from your integration API. You must register callback URLs for both sale Cart and return Cart retrievals. The InStore API server will call the registered endpoint with the registered retailer key and the Cart ID, and the callback endpoint is expected to return the requested Cart in the specified JSON format. For more information about the structure of the Cart retrieval callbacks, see Callbacks.
InStore also requires the user's access token to process any transaction. To ensure tokens are not transmitted from the browser, you need to generate a user key every time a new access token is granted for a user. The user key will be used by InStore to retrieve the access token for subsequent processing. For more information, see Callbacks.

Webhooks

Results of all processes are posted to a webhook that you have previously registered in the InStore Center. For more information about how to register a webhook, see Environment setup. For more information about the structure of the webhook, see Webhooks.

Events

In the federated component model, InStore notifies the host application of the current status of the requested process through a custom event. For more information, see Events.

Payment extensions

InStore supports several payment providers. You can implement their own integration between InStore and the payment provider and register the payment URL when you set up a custom payment provider during environment setup. For more information about the structure of the extension API, see Payment extensions.

Environment variables

You can add environment variables to your integration server to achieve specific outcomes.

Improve startup performance

By default, InStore reloads parameters when the browser initializes. The client-side application typically includes a browser that runs InStore as a federated component, and initialization occurs once at the start of a user's working session.

However, you can choose to override this default behavior using environment variables to let your application initialize a new InStore browser session after each transaction. This allows you to use a workstation-level cached configuration for the getFullConfig and getTenantConfig API calls. Additionally, you can specify how often to clear the cache to optimize the workstation's performance. By default, InStore stores the cached configurations in memory but you can modify this to suit your needs in your integration server's code.

While caching is supported, we do not recommend it as it can cause your workstations to run with outdated settings.

To enable configuration caching, set the following environment variables on your integration server:

Variable nameDescriptionExample
ENABLE_CACHE_SETUP_WORKSTATIONIf set to true, the workstation caches locations, tenant configuration, and full configuration settings.ENABLE_CACHE_SETUP_WORKSTATION=true
TTL_MS_CACHE_SETUP_WORKSTATIONSpecifies how often the cache is cleared. If you enable caching but do not set this variable, a default of 23 hours is used.The following example sets cache clearing to 8 hours (1000 ms x 60 seconds
x 60 minutes x 8 hours): TTL_MS_CACHE_SETUP_WORKSTATION=1000 * 60 * 60 * 8