Configuration

Norce Checkout uses Norce Configuration API to configure your channel, checkout experience and your payment and shipping adapters. Can store any configuration that the your adapter or app needs to function. You start by defining the contract in the form of a JSON schema. This schema can then be used to validate any configurations that is sent to the API. The schema is also used to generate a UI in Norce Admin to allow users to configure your adapter.

JSON Schema

JSON Schema is a declarative language that you can use to annotate and validate the structure, constraints, and data types of your JSON documents. It provides a way to standardize and define expectations for your JSON data.

Read up on JSON Schema at json-schema.org.

The configuration API has a basic schema that all configurations will be validated against (and their own.). You should therefore extend this schema with your own schema to define the configuration model for your adapter.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://checkout-configuration.test.norce.tech/openapi/v1/schemas/configuration.json",
  "title": "Configuration",
  "description": "Basic configuration",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The schema used to validate this configuration, must also be valid with the original basic configuration schema."
    },
    "id": {
      "type": "string",
      "description": "The identifier for a configuration. Vital for batch updates."
    },
    "active": {
      "type": "boolean",
      "description": ""
    },
    "adapter": {
      "type": "object",
      "properties": {
        "publicUrl": {
          "type": "string",
          "description": "The public URL for the adapter."
        },
        "internalUrl": {
          "type": "string",
          "description": "The internal URL for the adapter."
        }
      },
      "required": ["publicUrl"]
    }
  },
  "required": ["$schema", "id"]
}

As an example, if adding configuration for an adapter with id my-adapter. That needs a setting called secret. A schema would be declared and hosted in the adapter like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://checkout-configuration.test.norce.tech/openapi/v1/schemas/configuration.json",
  "title": "Configuration",
  "description": "Basic configuration",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The schema used to validate this configuration, must also be valid with the original basic configuration schema."
    },
    "id": {
      "type": "string",
      "description": "The identifier for a configuration. Vital for batch updates."
    },
    "active": {
      "type": "boolean",
      "description": ""
    },
    "adapter": {
      "type": "object",
      "properties": {
        "publicUrl": {
          "type": "string",
          "description": "The public URL for the adapter."
        }
      },
      "required": ["publicUrl"]
    },
    "secret": {
      "type": "string"
    }
  },
  "required": ["$schema", "id", "secret"]
}

{
  "$schema": "https://my-adapter.com/schemas/my-adapter.json",
  "id": "my-adapter",
  "active": true,
  "adapter": {
    "publicUrl": "https://my-adapter.com"
  },
  "secret": "very-secret"
}