API Access Overview

Prerequisites for API Access

To interact with our APIs, you'll need to keep the following information in mind:

1. Base URL : Includes your identifier (slug), location, and environment.
2. Headers : Include your merchant identifier, channel, and authorization bearer token.

Merchant

Each merchant is assigned a unique identifier, referred to as the "merchant identifier" or simply "merchant." This identifier is used across all API interactions.

• Example 1: The store "Things & Stuff" is assigned the merchant identifier thingsandstuff .
• Example 2: The partner "Very Commerce Web Solutions" manages checkouts for multiple stores. They have the merchants verycommercewebsolutions-1 , verycommercewebsolutions-2 , and can request additional identifiers if needed.

You will be assigned a unique identifier, referred to as "merchant identifier" or simply "merchant" throughout this documentation.

Example: The store "Things & Stuff" is building their own checkout, they are assigned the merchant thingsandstuff.

Example: The partner "Very Commerce Web Solutions" is building a checkout for another store "Stuff & Things", as well as some other projects. They are assigned the merchants verycommercewebsolutions-1, verycommercewebsolutions-2 and can request more if needed.

API Base URL Structure

The API Base URL follows this format:

{{slug}}.{{location}}.{{environment}}.norce.tech/{{domain}}/{{service}}

For the production environment the .{{environment}} is excluded.

{{slug}}.{{location}}.norce.tech/{{domain}}/{{service}}

Example URL

https://thingsandstuff.api-se.playground.norce.tech/checkout/order

URL Components

• Slug : Your merchant identifier, eg thingsandstuff .
• Location : Indicates the geographic region. For Sweden, use api-se .
• Environment : Identifies the API environment
  • Playground : Development environment, use playground .
  • Stage : Pre-production, for testing before going live, use stage .
  • Production : Production environment, exclude the environment from the url.
• Domain & Service : Specific to each core service and Norce-hosted adapter. For example, /checkout/order is used for the Norce Checkout order API.

Request Headers

To interact with the Norce Checkout services, include the following headers:

• X-Merchant : Contains your merchant identifier, eg., thingsandstuff .

Authorization (Bearer Token)

You can request multiple bearer tokens. A primary and secondary token will be issued. While there is no official time-to-live (TTL) for tokens, the primary token can be revoked at any time, at which point you'll need to use the secondary token. We will provide a new token or pair of tokens as needed.

To include the merchant and token in the request:

X-Merchant: {{merchant}}
Authorization: Bearer {{token}}

Note: Each merchant has unique tokens. Tokens cannot be shared between merchants, e.g., verycommercewebsolutions-1 and verycommercewebsolutions-2 must use separate tokens.

Channel

Norce Checkout allows customization via "channels." A channel represents a set of configurations for a merchant and is defined by the X-Channel header.

Example:

• A Swedish channel might be represented as se .
• A channel used for A/B testing might be se-no-psp .

We recommend using lowercase letters and hyphens for channel names.

X-Channel: {{channel}}

Example Flow

1. The client makes a request to the order service at {{slug}}.{{location}}.{{environment}}.norce.tech/checkout/order .
2. The load balancer routes the call to the appropriate service.
3. The order service verifies the token for the given merchant and restricts access to entities belonging to that merchant.

Internal URLs

When configuring Norce-hosted adapters via the configuration API, internal URLs are required. Internal URLs do not use the load balancer and follow a simplified structure:

{{service}}.{{domain}}.{{environment}}.internal.norce.tech

Example Internal URL

https://order.checkout.playground.internal.norce.tech

Jetshop Environment

While the information above is relevant for Norce Checkout deployed in Norce environment, Jetshop has its own environment and its own deployment of Norce Checkout. It shares the same code base and release cycle but accessing it slightly different.

You will still be assigned a merchant and token as described above but APIs are accessed through other urls.

Jetshop API Base URL Structure

The Jetshop API Base URL follows this format:

{{domain}}-{{service}}.{{environment}}.norce.tech

Example Jetshop URL

https://checkout-order.test.norce.tech/

https://checkout-jetshop-adapter.test.norce.tech/

https://checkout-klarna-adapter.test.norce.tech/

Internal Jetshop URLs

Used when configuration Norce-hosted adapters (in Jetshop environment.)

{{domain}}-{{service}}.{{environment}}.jetshopcloud.io

Example Jetshop Internal URL

https://checkout-order.test.jetshopcloud.io/

https://checkout-jetshop-adapter.test.jetshopcloud.io/

https://checkout-klarna-adapter.test.jetshopcloud.io/