Configuration
The Norce Checkout Configuration API stores and validates settings for your checkout channel, adapters, and custom applications. Each adapter (payment, shipping, voucher, or platform) retrieves its configuration from this API based on the channel context. You define the configuration contract using JSON Schema, which enables validation and automatic UI generation in Norce Admin.
How Configuration Works
When an adapter receives a request, it queries the Configuration API using the merchant and channel from the request headers. The API returns the configuration document for that adapter, which contains credentials, feature flags, and adapter-specific settings. This approach keeps sensitive configuration separate from your application code and allows different settings per channel.
JSON Schema
JSON Schema is a declarative language for defining the structure and validation rules of JSON documents. Norce Checkout uses JSON Schema to validate configurations and generate configuration forms in Norce Admin.
Read up on JSON Schema at json-schema.org.
Base Configuration Schema
All configurations extend the base schema, which defines common fields that every adapter configuration must include:
{
"$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"]
}Realistic Configuration Examples
Payment Adapter Configuration (Klarna)
A Klarna Checkout adapter configuration includes merchant credentials, regional settings, and checkout behavior options:
{
"$schema": "https://klarna-checkout-adapter.api.norce.tech/schemas/klarna-checkout.json",
"id": "klarna_checkout_adapter",
"active": true,
"adapter": {
"publicUrl": "https://your-merchant.api-se.stage.norce.tech/checkout/klarna-checkout-adapter",
"internalUrl": "http://klarna-checkout-adapter:8080"
},
"credentials": {
"username": "PK12345_abcdef123456",
"password": "your-klarna-api-password"
},
"region": "eu",
"purchaseCountry": "SE",
"purchaseCurrency": "SEK",
"locale": "sv-SE",
"options": {
"colorButton": "#000000",
"colorButtonText": "#ffffff",
"radiusBorder": "4px"
}
}Shipping Adapter Configuration (Ingrid)
An Ingrid shipping adapter configuration specifies API credentials and delivery options:
{
"$schema": "https://ingrid-adapter.api.norce.tech/schemas/ingrid.json",
"id": "ingrid_adapter",
"active": true,
"adapter": {
"publicUrl": "https://your-merchant.api-se.stage.norce.tech/checkout/ingrid-adapter",
"internalUrl": "http://ingrid-adapter:8080"
},
"siteId": "your-ingrid-site-id",
"apiKey": "your-ingrid-api-key",
"environment": "stage",
"defaultLocale": "sv-SE",
"showDeliveryDate": true
}Norce Adapter Configuration
The Norce Adapter connects Norce Commerce to Norce Checkout. Its configuration includes Commerce API credentials and order mapping settings:
{
"$schema": "https://norce-adapter.api.norce.tech/schemas/norce-adapter.json",
"id": "norce_adapter",
"active": true,
"adapter": {
"publicUrl": "https://your-merchant.api-se.stage.norce.tech/checkout/norce-adapter",
"internalUrl": "http://norce-adapter:8080"
},
"commerce": {
"baseUrl": "https://your-client.commerce.norce.tech",
"clientId": "your-oauth-client-id",
"clientSecret": "your-oauth-client-secret",
"applicationId": 12345
},
"orderExport": {
"paymentMethodId": 239,
"deliveryMethodId": 128,
"statusIdOnComplete": 1
}
}Extending the Base Schema
When building a custom adapter, extend the base schema with your adapter-specific fields. Here is an example schema for a custom validation adapter:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://your-adapter.example.com/schemas/validation-adapter.json",
"title": "Validation Adapter Configuration",
"description": "Configuration for custom order validation",
"type": "object",
"allOf": [
{ "$ref": "https://checkout-configuration.stage.norce.tech/openapi/v1/schemas/configuration.json" }
],
"properties": {
"validationService": {
"type": "object",
"properties": {
"apiEndpoint": {
"type": "string",
"description": "The validation service API endpoint"
},
"apiKey": {
"type": "string",
"description": "API key for authentication"
},
"validateOnStateChange": {
"type": "boolean",
"description": "Whether to validate on every state change"
},
"blockOnFailure": {
"type": "boolean",
"description": "Whether to block checkout if validation fails"
}
},
"required": ["apiEndpoint", "apiKey"]
}
},
"required": ["$schema", "id", "validationService"]
}A configuration instance for this adapter would look like:
{
"$schema": "https://your-adapter.example.com/schemas/validation-adapter.json",
"id": "validation_adapter",
"active": true,
"adapter": {
"publicUrl": "https://your-merchant.api-se.stage.norce.tech/checkout/validation-adapter"
},
"validationService": {
"apiEndpoint": "https://api.yourservice.com/v1/validate",
"apiKey": "vs_live_abc123def456",
"validateOnStateChange": true,
"blockOnFailure": false
}
}Managing Configurations
You can manage configurations through the Configuration API or through Norce Admin. The API supports creating, updating, and deleting configurations, as well as batch operations for managing multiple configurations at once. See the Configuration API reference for detailed endpoint documentation.