Payment Adapters Overview

Payment Service Provider (PSP) adapters handle the payment flow in Norce Checkout. They integrate with external payment providers like Klarna, Adyen, Svea, and others to process payments, manage authorization, and handle post-purchase operations.

For general requirements and access details, see How to access Norce Checkout.

API Environments and URLs

All Norce Checkout payment adapters use the same URL pattern:

Replace {slug} with your unique Norce instance slug and {adapter} with the provider-specific name (e.g., klarna, adyen, svea).

Payment Lifecycle

Payment adapters participate in the checkout flow through a standardized lifecycle:

1. Create Payment Session

After creating a Norce Checkout order via the Norce Adapter, your application calls the payment adapter to create a payment session. The adapter:

1. Retrieves its configuration
2. Fetches the associated Norce Checkout order
3. Maps the order to a provider-specific payment session
4. Returns session information (redirect URL, HTML snippet, or widget configuration) for your frontend to render

2. Frontend Rendering

Your frontend uses the session information to render the payment UI. This could be an embedded widget (Klarna, Adyen Drop-in), a redirect to the provider's hosted page, or a custom form.

3. Hooks and Callbacks

Payment adapters register hooks on the order to stay synchronized:

• Cart hooks: Notify the adapter when cart contents change, allowing it to update the payment session
• State hooks: Notify the adapter when order state changes, enabling validation and blocking invalid transitions

When the customer interacts with the payment UI (e.g., selects shipping, enters details), the provider notifies the adapter via callbacks, which updates the Norce Checkout order accordingly.

4. Order State Transitions

As the payment progresses, the order transitions through states:

1. Checkout - Initial state, order is being configured
2. Processing - Payment is being processed (order locked for changes)
3. Accepted - Payment accepted, order is being finalized
4. Completed - Order complete, all adapters have finished

The payment adapter drives these transitions based on provider responses and registers notifications to trigger actions (like exporting the order to Norce Commerce) when specific states are reached.

Standardized Payment States

All PSP adapters report payment status using these standardized states:

Post-Purchase Operations

These API calls are used for post-purchase management and are available for most PSP adapters. All operations use the orderId returned when creating the order and the paymentId from the payment session.

Capturing a Payment

Used to notify the payment provider that the order is fulfilled and funds should be drawn (transitions from reserved to captured).

POST /api/order/v1/orders/{orderId}/payments/{paymentId}/capture
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Refunding a Payment

Used to refund a customer. Can only be performed on a payment in the captured state.

POST /api/order/v1/orders/{orderId}/payments/{paymentId}/refund
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Canceling a Payment

Used to cancel a payment in the reserved state before it has been captured.

POST /api/order/v1/orders/{orderId}/payments/{paymentId}/cancel
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Available Payment Adapters

• Svea Checkout
• Klarna Checkout
• Adyen Checkout
• Walley Checkout
• PayPal Checkout
• Qliro Checkout
• Avarda Checkout
• Non-PSP Adapter - For manual or invoice-based flows