A Medusa v2 payment provider that integrates Klarna as a payment option. Supports Klarna's Hosted Payment Page (HPP) flow, direct authorization, fraud detection webhooks, and multiple regions (EU, NA, Oceania).

Features

• Full payment lifecycle: initiate, authorize, capture, refund, cancel
• Klarna Hosted Payment Page (HPP) integration
• Direct authorization token flow
• Fraud detection webhook handling (accepted, rejected, stopped)
• Multi-region support (EU, NA, Oceania)
• Playground and live environments
• Automatic retry with exponential backoff on server errors
• Idempotent capture and refund operations
• Zero-decimal currency support (JPY, KRW, etc.)
• Custom line item support with tax handling

Installation

yarn add @stackd-solutions/medusa-payment-klarna

Configuration

Register the module in your medusa-config.ts:

import {defineConfig} from '@medusajs/framework/utils'

export default defineConfig({
	// ... other config
	modules: [
		{
			resolve: '@stackd-solutions/medusa-payment-klarna/modules/payment-klarna',
			options: {
				apiKey: 'your-klarna-api-key',
				environment: 'playground',
				region: 'eu',
				defaultCountry: 'NL',
				defaultLocale: 'nl-NL',
				storefrontUrl: 'https://shop.example.com'
			}
		}
	]
})

Module Options

| Option | Type | Required | Default | Description | | ---------------- | -------------------------- | -------- | ----------------------------------- | ------------------------------------------------- | | apiKey | string | Yes | -- | Klarna API key or raw username:password credentials | | environment | 'playground' | 'live' | Yes | -- | Klarna API environment | | region | 'eu' | 'na' | 'oc' | Yes | -- | Geographic region for API endpoints | | defaultCountry | string | Yes | -- | 2-letter ISO country code (e.g. "NL", "SE") | | defaultLocale | string | Yes | -- | RFC 1766 locale code (e.g. "nl-NL", "en-US") | | storefrontUrl | string | Yes | -- | Base URL of your storefront | | callbackPath | string | No | /{language}/order/callback/klarna | Path for payment completion callback | | checkoutPath | string | No | /{language}/checkout | Path for cancellation redirect |

API Key Format

The apiKey option accepts either:

• A Klarna API key (e.g. "klarna_test_api_MzRkMjY...") which is sent as-is via Authorization: Basic <API_KEY>
• A raw username:password string (e.g. "K12345_abcdef:secretkey") which will be Base64-encoded automatically

Payment Flow

1. Initiate -- Creates a Klarna payment session and HPP session. Returns client_token and hpp_redirect_url in the session data.
2. Authorize -- Processes authorization via HPP completion or a direct authorization_token. Creates the Klarna order.
3. Capture -- Captures the authorized payment amount (idempotent).
4. Refund -- Issues a refund for the specified amount (idempotent).
5. Cancel -- Cancels the payment and deletes the authorization.

Fraud Detection

Klarna performs asynchronous fraud checks. The provider handles fraud webhooks automatically:

• FRAUD_RISK_ACCEPTED -- Payment is authorized
• FRAUD_RISK_REJECTED -- Payment is cancelled
• FRAUD_RISK_STOPPED -- Payment requires manual review

Line Items

Pass custom line items via data.line_items when initiating or updating a payment:

const lineItems: Array<KlarnaLineItemInput> = [
	{
		name: 'Product Name',
		quantity: 2,
		unit_price: 1999, // in minor units (cents)
		tax_rate: 2100, // 21.00% in basis points
		reference: 'SKU-001', // optional
		type: 'physical' // optional
	},
	{
		name: 'Shipping',
		quantity: 1,
		unit_price: 499,
		tax_rate: 2100,
		type: 'shipping_fee'
	}
]

Build

yarn build

Development

yarn dev

Types

import type {
	KlarnaOptions,
	KlarnaLineItemInput,
	KlarnaSessionData,
	KlarnaPaymentData,
	KlarnaOrderLine,
	KlarnaPaymentMethodCategory,
	KlarnaOrderResponse,
	KlarnaOrderDetails
} from '@stackd-solutions/medusa-payment-klarna'

import {
	KlarnaApiError,
	KlarnaFraudStatus,
	KlarnaOrderStatus,
	KlarnaHppSessionStatus,
	KlarnaWebhookEvent
} from '@stackd-solutions/medusa-payment-klarna'

License

Apache 2.0