Klarna Getting Started: Account, Keys, and First API Call (2026)

Getting started overview

Integrating Klarna into an application or e-commerce platform involves a series of steps, from setting up a merchant account to making successful API calls. The core process includes obtaining API credentials, configuring your development environment, and then initiating payment requests using Klarna's APIs or one of its official SDKs. Klarna supports various payment methods, including Pay in 4, Pay in 30 days, and Financing, which require specific API interactions depending on the desired user experience.

The following table outlines the key steps to begin your integration:

Create an account and get keys

Before making any API requests, you must establish a merchant account with Klarna. This process typically begins with an application on the Klarna Business portal. During the application, you will provide details about your business, including its legal structure, industry, and anticipated transaction volumes. Klarna reviews these applications to ensure compliance with its financial regulations and operational policies.

Upon approval, you will gain access to the Klarna Merchant Portal. This portal serves as the central hub for managing your Klarna account, viewing transactions, and configuring integration settings. Within the Merchant Portal, you can find your essential API credentials:

• Merchant ID (MID): A unique identifier for your merchant account.
• Shared Secret: A confidential key used to authenticate your API requests and ensure their integrity. It is crucial to treat the Shared Secret as sensitive information, similar to a password, and store it securely.

These credentials are required for all authenticated API interactions, including creating orders, managing refunds, and retrieving order details. Klarna's authentication mechanism typically involves using these keys in an HTTP Basic Authentication header for RESTful API calls. For example, when making a request, the Authorization header might be structured as Basic <base64-encoded-MID:SharedSecret>, as detailed in the Klarna API reference documentation.

It is recommended to use separate credentials for testing (sandbox) and production environments to prevent accidental live transactions during development. Klarna provides distinct environments for this purpose, each with its own set of API keys.

Your first request

Once you have your Merchant ID and Shared Secret, you can proceed with making your first API request. A common first step is to create a new order, which involves defining the items, customer details, and payment options. Klarna's API is primarily RESTful, utilizing JSON for request and response bodies.

Here's an example using the /payments/v1/sessions endpoint to create a payment session, which is a foundational step for initiating a Klarna checkout flow. This example uses a generic HTTP client, but the principles apply when using one of Klarna's SDKs (JavaScript, PHP, Python, Ruby, Java, Android, iOS, .NET).

POST /payments/v1/sessions HTTP/1.1
Host: api.klarna.com
Authorization: Basic <base64-encoded-MID:SharedSecret>
Content-Type: application/json

{
  "purchase_country": "US",
  "purchase_currency": "USD",
  "locale": "en-US",
  "order_amount": 10000, 
  "order_tax_amount": 1000, 
  "order_lines": [
    {
      "type": "physical",
      "name": "Klarna T-Shirt",
      "quantity": 1,
      "unit_price": 10000,
      "total_amount": 10000,
      "total_tax_amount": 1000
    }
  ],
  "merchant_urls": {
    "terms": "https://www.example.com/terms",
    "checkout": "https://www.example.com/checkout",
    "confirmation": "https://www.example.com/confirmation",
    "push": "https://www.example.com/push"
  }
}

Explanation of parameters:

• purchase_country: The two-letter ISO 3166-1 alpha-2 country code for the purchase.
• purchase_currency: The three-letter ISO 4217 currency code.
• locale: The locale of the checkout (e.g., en-US).
• order_amount: Total amount of the order, including tax and shipping, in minor units (e.g., 10000 for $100.00).
• order_tax_amount: Total tax amount for the order in minor units.
• order_lines: An array of items in the order, each with its own details like type, name, quantity, and price.
• merchant_urls: An object containing various URLs Klarna uses for redirects and callbacks during the checkout process. These are critical for guiding the customer through the payment flow and receiving updates on transaction status.

A successful response to this request will include a session_id and client_token, which are then used to either render the Klarna checkout widget on your front-end or to continue the payment process through subsequent API calls. The client_token is particularly important for initializing the Klarna JavaScript SDK for front-end integrations.

Common next steps

After successfully creating your first payment session, several common next steps typically follow to complete a Klarna integration:

1. Integrating the Klarna Checkout Widget: For web-based integrations, you'll likely use the client_token obtained from the payment session creation to initialize the Klarna JavaScript SDK. This renders the Klarna checkout widget within your application, allowing customers to select their preferred payment method (e.g., Pay in 4, Pay in 30 days) and complete their purchase. Klarna's Klarna Payments integration guide provides detailed instructions for this process.
2. Handling Order Captures: Once a customer completes their purchase through Klarna, the order is typically authorized but not yet captured. To finalize the transaction and initiate the transfer of funds, you'll need to make an API call to capture the order. This usually happens after the goods have been shipped or the service has been rendered.
3. Managing Refunds and Voids: Klarna's API also supports operations for managing orders post-purchase. This includes processing refunds for returned items or voiding authorized but uncaptured orders. Implementing these endpoints is crucial for comprehensive payment management.
4. Webhooks for Asynchronous Updates: To receive real-time notifications about changes in order status (e.g., payment captured, refund processed), you should configure webhooks. Klarna sends POST requests to specified URLs when events occur, allowing your system to react asynchronously without constant polling.
5. Testing in Sandbox and Production: Thoroughly test your integration in Klarna's sandbox environment before deploying to production. The sandbox mimics the production environment without processing real payments, allowing you to validate your implementation. Once testing is complete, switch to your production API credentials and endpoints.

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here are some troubleshooting tips for your first Klarna API request:

• Incorrect API Credentials: Double-check your Merchant ID and Shared Secret. Ensure they are correctly base64-encoded and included in the Authorization header. Even a single character mismatch can lead to authentication failures. Verify you are using the correct credentials for the environment (sandbox vs. production).
• Environment Mismatch: Make sure you are pointing your API requests to the correct Klarna API endpoint for your chosen environment. Sandbox URLs typically differ from production URLs. For example, the sandbox might use api.playground.klarna.com while production uses api.klarna.com. Consult the Klarna developer documentation for the specific endpoint URLs.
• Invalid JSON Payload: Review your request body for any syntax errors in the JSON. Missing commas, unclosed brackets, or incorrect data types can cause the API to reject your request. Use a JSON linter or validator to check your payload structure.
• Missing Required Fields: Ensure all mandatory fields in the request body are present and correctly populated. The Klarna API documentation specifies which fields are required for each endpoint. Common missing fields include purchase_country, purchase_currency, order_amount, and order_lines.
• Incorrect Amount Formatting: Klarna expects all monetary values (e.g., order_amount, unit_price, total_amount) to be in minor units (e.g., cents for USD) and as integers. Sending float values or incorrect whole number representations will result in errors. For instance, $100.00 should be sent as 10000.
• Network Issues or Firewall Restrictions: Confirm that your server or development environment can reach Klarna's API endpoints. Firewall rules or network configurations might be blocking outgoing HTTP requests.
• Reviewing API Error Messages: Klarna's API responses include detailed error messages when a request fails. Parse these responses carefully, as they often provide specific clues about what went wrong (e.g., INVALID_MERCHANT_ID, BAD_VALUE_FOR_FIELD). The Klarna API error codes documentation can help interpret these messages.
• SDK Specific Issues: If using an SDK, ensure it is the latest version and correctly initialized. Refer to the specific SDK documentation for proper usage and common pitfalls.