Svea Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The Svea Checkout Adapter integrates Svea Checkout with Norce Checkout. This page focuses on the unique technical details and configuration for Svea.

Supported payment methods and other features: Features Overview

Configuration in Norce Admin

The adapter is configured using the following details obtained from Svea and your storefront URLs:

Required Settings

Optional Settings

Svea API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), Svea uses the following external API environments:

B2B vs B2C Handling

The adapter automatically detects whether the customer is a business (B2B) or private consumer (B2C) based on the customer.type field in the Norce order. When the customer type is Organization, the adapter sets the IsCompany preset value to true in the Svea checkout session.

Key differences for B2B orders:

• The minAge validation option is not supported for B2B orders (Svea limitation)
• PEPPOL invoicing is available for B2B customers

Note that the adapter always sends prices including VAT to Svea. The VAT rate is calculated from each item's vatRate field. For discounts, the VAT rate is derived from the difference between includingVat and excludingVat values.

Billing Address Fallback for Finland (Svea Checkout Adapter)

In Finland, Svea Checkout does not return the customer's billing address; Svea states that Finnish law prohibits them from sharing it. As a result the billing address on the Norce Checkout order is not populated from Svea, and the order typically carries only a partial billing object such as { "type": "person", "country": "FI" } with no email. This can cause issues for merchants that require a billing address on the order.

The Svea Checkout Adapter provides an opt-in useShippingAsBillingFallback configuration option to handle this. Set useShippingAsBillingFallback to true in the Svea adapter configuration in Norce Admin to enable it. The option defaults to false, so existing merchants are unaffected unless they enable it.

When useShippingAsBillingFallback is enabled, during order validation the Svea Checkout Adapter copies Svea's shipping address into the Norce Checkout order's billing address only when all of the following conditions are met:

• useShippingAsBillingFallback is true.
• The order's billing address is missing or incomplete (it is null or has no email).
• Svea's billing address is incomplete (no country code).
• Svea's shipping address is complete (has a country code).

The email used for the billing address is taken from Svea's order-level email and is applied to the resulting billing address. If any condition is not met, the billing address is left unchanged. The fallback applies only to the validation flow; it does not change behavior for other Svea Checkout Adapter flows such as customer updates or recurring orders.

Merchant Settings (Auto-generated Callbacks)

When creating a Svea checkout session, the adapter automatically generates the following callback URLs. These are sent to Svea as part of the merchantSettings and do not need to be configured manually:

Creating a Recurring Payment

To create an order using a previously stored recurring token:

POST /api/checkout/v1/orders/{order_id}/payments/recurring
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}
Content-Type: application/json

{
  "token": "cd45444b-e125-4660-b5c0-08dce7ff05be"
}

Pending Payment Handling

Svea payments can enter a pending state when the payment requires additional processing before a final decision is made. Common reasons include:

• Manual fraud review by Svea's risk team
• Waiting for an external provider or bank to respond (e.g., direct bank transfers)
• Missing delivery address information required by Svea

When a payment is pending, the Norce order moves to the Accepted state, but the payment state on the Norce payment object is set to Pending instead of Reserved. The order remains in Accepted and does not transition to Completed until Svea resolves the pending status.

How Pending Payments Are Resolved

Svea resolves pending payments asynchronously by sending event notifications to the adapter. The adapter handles two event types relevant to pending payments:

When the adapter receives a CheckoutOrder.PendingStatusReleased event, it fetches the Svea admin order to confirm the system status. If the status maps to Reserved, the adapter updates the Norce payment state, transitions the order to Completed, and refreshes available payment actions (capture, cancel, refund).

When the adapter receives a CheckoutOrder.Closed event, it updates the Norce payment state to Declined and transitions the order to Declined.

Registering Svea Event Subscriptions (Required for Pending Payments)

To receive these event notifications, a Svea event subscription must be registered for each merchant and channel during onboarding. Without this subscription, Svea will not notify the adapter when a pending payment is resolved, and the order will remain stuck in the Accepted state with a Pending payment.

The partner or integration team must call the Svea adapter's Add Subscription endpoint once per merchant/channel combination:

POST /api/checkout/v1/admin/subscription
Host: svea-adapter.checkout.{env}.internal.norce.tech
x-merchant: {merchant}
x-channel: {channel}

This endpoint performs two actions:

1. Registers a callback subscription with the Svea Payment Admin API (POST /api/v2/callbacks/subscriptions) for the events CheckoutOrder.PendingStatusReleased and CheckoutOrder.Closed.
2. Verifies the subscription with Svea (POST /api/v2/callbacks/subscriptions/{subscriptionId}/verify) by responding to a Subscription.Ping event.

The response returns the subscriptionId (a GUID) assigned by Svea. Store this ID if you need to remove the subscription later.

To remove an existing subscription:

DELETE /api/checkout/v1/admin/subscription/{subscription_id}
Host: svea-adapter.checkout.{env}.internal.norce.tech
x-merchant: {merchant}
x-channel: {channel}

For the full Svea callbacks documentation, see Svea Add Subscription API.

Troubleshooting (Svea Specific)

In addition to the generic troubleshooting steps:

• Review the order status directly in Svea's Payment Admin.
• If Capture fails, verify the Norce order is in the reserved state and that the Svea order status is Final.
• Use the Svea-specific refresh call to update available payment actions:

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

Links and References

• Svea Checkout Adapter (Business Overview)
• Svea Checkout Adapter OpenAPI Specification
• Svea Checkout Documentation (External)