Enable mTLS for Klarna Payments callbacks

Enable mutual TLS (mTLS) authentication for Klarna Payments callbacks so Klarna webhooks platform authenticates to your endpoint using client certificates.

Mutual Transport Layer Security (mTLS) extends standard TLS by requiring both parties to authenticate during the connection handshake. While standard TLS only verifies the server's identity, mTLS also verifies the client's identity using certificates. For callbacks, this means both Klarna and your endpoint authenticate to each other, providing stronger security guarantees than HMAC signatures alone.

Overview

Klarna Network webhooks platform supports mTLS authentication for Klarna Payments callbacks, including:

Authorization callbacks
Hosted Payment Page (HPP) status update callbacks
Hosted Payment Page (HPP) distribution update callbacks

Authorization callbacks are server-side callbacks sent after a successful payment authorization. These callbacks help optimize conversion rates by ensuring order creation even when client-side communication fails. For detailed information about authorization callbacks, refer to the Authorization callback documentation.

HPP status update callbacks notify your system whenever the status of an HPP session changes based on consumer actions (e.g., IN_PROGRESS, COMPLETED, FAILED, CANCELLED). HPP distribution update callbacks notify your system when an HPP session is distributed to a consumer. For detailed information about HPP callback payloads and behavior, refer to the HPP Status Callbacks documentation.

HMAC and mTLS configuration for callbacks

By default, callbacks sent via the Klarna Network webhooks platform do not include HMAC authentication.

Important: Once a callback configuration is registered as a webhook for a given legacy merchant ID, it will be fully respected. This means callbacks matching the subscribed event types will be sent to the URL specified in the registered webhook configuration, rather than the callback URLs specified in the individual payment requests.

If your integration requires callbacks to be secured with authentication:

HMAC authentication only: Register your Klarna Payments callbacks as webhooks through the Notifications API using the following event types. This enables HMAC signature verification for callback requests:
- klarna_payments.kp.authorization - for authorization callbacks
- klarna_payments.hpp.status_update - for HPP status update callbacks
- klarna_payments.hpp.distribution_update - for HPP distribution update callbacks
HMAC authentication + mTLS: Register your callbacks as webhooks with the event types listed above and configure them with the outbound_client_certificate_id field. Follow the step-by-step guide below to enable both HMAC and mTLS authentication for your callbacks.

When you enable mTLS for callbacks, you gain:

Bidirectional authentication: Klarna authenticates to your endpoint using a client certificate when delivering callbacks as webhooks, and your endpoint validates Klarna's identity before processing payloads.
Defense-in-depth security: mTLS works in conjunction with HMAC signature verification for layered protection.

mTLS configuration

Klarna-managed certificates

Klarna manages the mTLS client certificates used for callback deliveries:

Simplified management: Klarna handles certificate creation, rotation, and lifecycle management
Certificate Authority: Klarna uses DigiCert public CA for certificate issuance
Automatic rotation: Klarna rotates certificates as needed without prior announcement
No certificate pinning: Partners must not pin the specific certificate; instead, verify it's valid and matches the expected Subject CN
Subject CN verification:
- Production: CN=webhooks-client.klarna.com
- Playground: CN=webhooks-client.test.klarna.com
Setup: Contact your Klarna integration manager to obtain the correct certificate_id for configuring your webhooks

Prerequisites

Before enabling mTLS for callbacks, ensure you have:

1.
A Klarna Merchant ID with API credentials
2.
Contact your Klarna integration manager to obtain the certificate_id
3.
A callback endpoint that supports mTLS client authentication

Step-by-step guide

This guide walks you through configuring mTLS for callbacks sent as webhooks.

sequenceDiagram participant Partner as PARTNER participant API as NOTIFICATIONS API participant Webhook as WEBHOOK ENDPOINT participant Platform as KLARNA WEBHOOKS PLATFORM autonumber Partner->>Webhook: Configure endpoint to require mTLS Partner->>API: Create signing key Note over Partner, API: POST /v2/notification/signing-keys API-->>Partner: Return signing_key_id and signing_key Partner->>API: Create webhook with mTLS Note over Partner, API: POST /v2/notification/webhooks<br/>with outbound_client_certificate_id API-->>Partner: Return webhook_id Partner->>API: Test webhook Note over Partner, API: POST /v2/notification/webhooks/{id}/simulate API->>Platform: Trigger webhook delivery Platform->>Webhook: Deliver webhook with client certificate Note over Platform, Webhook: mTLS handshake Webhook->>Webhook: Verify client certificate Webhook->>Webhook: Verify HMAC signature Webhook-->>Platform: Return 200 OK

Step 1: Configure your callback endpoint to require mTLS

Before Klarna can authenticate to your callback endpoint using mTLS, configure your endpoint to accept and verify client certificates.

Understanding the outbound_client_certificate_id field

The outbound_client_certificate_id field is an optional parameter used when creating or updating webhooks. This field enables mTLS authentication for webhook deliveries:

Purpose: Specifies which client certificate Klarna webhooks platform should present when connecting to your webhook endpoint
Type: Optional string field
Format: Must be a valid client certificate ID (e.g., krn:partner:global:notification:client-certificate:a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d)
Availability: Reach out to your Klarna contact to obtain the valid certificate_id for your account
When to use: Include this field when creating callback configuration if you want Klarna to authenticate using mTLS when delivering notifications to your endpoint

If you omit the outbound_client_certificate_id field when configuring a callback as a webhook, Klarna delivers callbacks without mTLS client certificate authentication. You can add it later by updating the webhook.

Configure your server to accept client certificates

Configure your webhook endpoint to:

1.
Require client certificate authentication during the TLS handshake
2.
Verify the client certificate is issued by a trusted CA
3.
Verify the certificate Subject CN matches the expected value:
- 3.1.
  Production: CN=webhooks-client.klarna.com
- 3.2.
  Playground: CN=webhooks-client.test.klarna.com

The specific configuration depends on your server infrastructure.

Sample code:

NGINX

1 2 3 4 5 6 7 8 9 10

server {
    listen 443 ssl;
    server_name your-webhook-endpoint.com;
    
    ssl_certificate /path/to/your/server-cert.pem;
    ssl_certificate_key /path/to/your/server-key.pem;
    
    # Require client certificate
    ssl_verify_client on;
    ssl_client_certificate /path/to/trusted-ca-bundle.pem;

Best practice: Implement both mTLS certificate verification and HMAC signature verification for defense-in-depth security. HMAC authentication is supported when you configure your callback endpoint as a webhook.

Step 2: Create a signing key

Webhooks platform requires a signing key for HMAC signature verification. Create one using the Notifications API:

BASH

1 2 3 4

curl -X POST \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/notification/signing-keys

Sample response:

JSON

1 2 3 4 5 6

{
  "signing_key_id": "krn:partner:global:notification:signing-key:49bcd37b-79a7-4e6e-b067-2903b45fef42",
  "signing_key": "b040893b9e02f6445b205ae2102e3e9e1d0aa9035e61cdebde39b5c230a7bc5a",
  "created_at": "2025-02-06T12:00:00Z"
}

Store the signing_key value securely. It's only shown once and can't be retrieved later.

Step 3: Create a webhook with mTLS enabled

Create a webhook using the Notifications API with the outbound_client_certificate_id parameter and the appropriate Klarna Payments event types:

BASH

1 2 3 4 5 6 7 8 9 10

curl -X POST \
  -H "Authorization: Basic $API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api-global.klarna.com/v2/notification/webhooks \
  -d '{
    "url": "https://your-webhook-endpoint.com/callbacks/klarna",
    "event_types": [
      "klarna_payments.kp.authorization",
      "klarna_payments.hpp.status_update",
      "klarna_payments.hpp.distribution_update"

Use the signing_key_id from Step 2 and the certificate_id provided by your Klarna integration manager.

Sample response:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "webhook_id": "krn:partner:global:notification:webhook:120e5b7e-dee8-43ca-9858-dca726e639b5",
  "url": "https://your-webhook-endpoint.com/callbacks/klarna",
  "event_types": [
    "klarna_payments.kp.authorization",
    "klarna_payments.hpp.status_update",
    "klarna_payments.hpp.distribution_update"
  ],
  "event_version": "v2",
  "signing_key_id": "krn:partner:global:notification:signing-key:49bcd37b-79a7-4e6e-b067-2903b45fef42",

Step 4: Test the callback webhook flow

Test your callback configuration using the Notifications API:

BASH

1 2 3 4 5 6 7 8 9

curl -X POST \
  -H "Authorization: Basic $API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api-global.klarna.com/v2/notification/webhooks/{webhook_id}/simulate \
  -d '{
    "event_type": "klarna_payments.kp.authorization",
    "event_version": "v2"
  }'

Verify:

1.
Your endpoint receives the webhook notification
2.
The client certificate is presented during the TLS handshake
3.
The certificate CN matches the expected Klarna-managed certificate CN
4.
HMAC signature verification succeeds

Optional: Update an existing callback to enable mTLS

If you have an existing callback configured as a webhook and want to add mTLS, use the PATCH endpoint (contact your designated technical point of contact at Klarna to request access to the API reference documentation):

BASH

1 2 3 4 5 6 7 8

curl -X PATCH \
  -H "Authorization: Basic $API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api-global.klarna.com/v2/notification/webhooks/{webhook_id} \
  -d '{
    "outbound_client_certificate_id": "krn:partner:global:notification:client-certificate:a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d"
  }'

Use the certificate_id provided by your Klarna integration manager.

Recommendation: Test the updated callbacks as webhooks configuration thoroughly before using it for production traffic. Use the webhook simulation feature to validate the setup.

Certificate management

All certificate management including rotation, expiration monitoring, and lifecycle management is handled entirely by Klarna. You don't need to perform any certificate management tasks.

Security best practices

1.
Use defense in depth: Implement both mTLS and HMAC signature verification
2.
Validate certificate details: Verify the CN matches the expected Klarna-managed certificate CN (webhooks-client.klarna.com for production, webhooks-client.test.klarna.com for playground)
3.
Log authentication failures: Monitor and alert on mTLS authentication failures
4.
Test thoroughly: Use the webhook simulation feature to validate your setup before going live
5.
Do not pin certificates: Never pin the specific certificate as Klarna may rotate it without notice. Always verify the certificate is valid and matches the expected CN instead.

Troubleshooting

Callback deliveries fail after enabling mTLS

Possible causes:

Your endpoint isn't configured to accept client certificates
The client certificate isn't trusted by your endpoint (verify your trusted CA bundle includes the correct CA)
Certificate CN validation is failing

Solution:

1.
Check your server logs for TLS handshake errors
2.
Verify your endpoint is configured to require client certificates
3.
Ensure DigiCert public CA certificates are in your trusted CA bundle
4.
Verify CN validation logic matches the expected certificate CN

Certificate validation errors

Possible causes:

Certificate has expired
Certificate was revoked
Wrong certificate ID specified in callback webhook configuration

Solution:

1.
Contact your Klarna integration manager to verify the certificate ID and status

Callback webhook simulation succeeds but production callbacks fail

Possible causes:

Different endpoint configurations between test and production
Firewall or load balancer not configured for client certificates
Certificate trust chain issues

Solution:

1.
Verify your production endpoint configuration matches your test setup
2.
Check firewall and load balancer configurations
3.
Test mTLS connectivity using tools like openssl s_client
4.
Review your certificate trust chain

Testing connectivity with OpenSSL

Test your callback endpoint's mTLS configuration using OpenSSL:

BASH

1 2 3 4 5 6 7 8 9 10

# Test that your endpoint requires a client certificate
openssl s_client -connect your-webhook-endpoint.com:443 -servername your-webhook-endpoint.com

# Test with the client certificate
openssl s_client -connect your-webhook-endpoint.com:443 \
  -cert webhook-cert.pem \
  -key webhook-key.pem \
  -servername your-webhook-endpoint.com \
  -showcerts

The first command should fail or show a certificate request. The second command should successfully establish a connection.