Documentation

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.