> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Klarna via Adyen

> Set up Klarna Pay Later, Pay Now and Pay Over Time through Adyen in Payrails, including stored Klarna agreements for MIT.

<picture noZoom>
  ![Klarna logo](https://assets.payrails.io/img/logos/klarna/logo-full-bleed.svg)
</picture>

<picture noZoom>
  ![Adyen logo](https://assets.payrails.io/img/logos/adyen/logo-full-bleed.svg)
</picture>

Accept [Klarna](https://docs.payrails.com/docs/integrations/payment-methods/klarna) payments with Adyen as the payment service provider (PSP). The customer selects a Klarna option, confirms the purchase on a Klarna page and returns to your site.

## Supported workflows

<table>
  <thead>
    <tr><th>Workflow</th><th>Supported</th></tr>
  </thead>

  <tbody>
    <tr><td>Payrails SDK</td><td>✔</td></tr>
    <tr><td>Payrails API</td><td>✔</td></tr>
    <tr><td>[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)</td><td>✔</td></tr>
    <tr><td>[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)</td><td>✔</td></tr>
  </tbody>
</table>

## Before you begin

Complete these steps before you send your first Klarna payment through Adyen:

1. Set up an Adyen integration in your workspace. Follow the [Adyen integration setup guide](https://docs.payrails.com/docs/integrations/payment-providers/adyen.md) if you don't have one yet.
2. Ask Adyen to enable the Klarna products you need on your Adyen merchant account, for the countries you sell in.
3. In the Payrails Portal, go to **Settings → Integrations**, open your Adyen integration, select **Klarna Pay Later**, **Klarna Pay Now** or **Klarna Pay Over Time** under **Payment methods**, and save.
4. Add each Klarna product as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md) in your workflow.

## Request fields for Adyen

Send these fields in the authorize request, in addition to the standard [authorize fields](https://docs.payrails.com/reference/authorizeaction.md). **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to the PSP when you include them.

| Field | Status | Description |
| - | - | - |
| `meta.order.lines` | Required | The basket. Sent to Adyen as line items. |
| `meta.order.lines[].unitPrice` | Required | Every line needs a valid unit price. |
| `meta.order.lines[].name`, `description`, `quantity`, `taxPercentage` | Optional | Sent to Adyen with each line item. Payrails uses `name` when `description` is empty. |
| `meta.order.billingAddress` | Required | Must include `street`, `doorNumber`, `city`, `postalCode` and `country.code`. Payrails falls back to the instrument's billing address when the order has none. |
| `meta.customer.country.code` | Required | Sent to Adyen as the country code. Klarna uses it to select the products it offers. |
| `meta.customer.email` | Required | Sent to Adyen as the shopper email. |
| `meta.customer.language` | Optional | Sent to Adyen as the shopper locale. Falls back to `meta.clientContext.language`. |
| `meta.customer.name`, `meta.customer.lastName` | Optional | Sent to Adyen as the shopper name. |
| `meta.order.deliveryAddress` | Optional | Sent to Adyen as the delivery address. |
| `holderReference` | Required | Needed to save the instrument. Set on the execution. Sent to Adyen as the shopper reference for the stored Klarna agreement. |
| `paymentComposition[].paymentInstrumentData.futureUsage` | Required | Needed to save the instrument. `Subscription` or `UnscheduledCardOnFile`. Adyen rejects `CardOnFile` for Klarna. |

## Authorize a Klarna payment

### Klarna payment method codes

Adyen offers three Klarna products, and Payrails treats each one as its own payment method. Send the code for the product the customer selects. Payrails doesn't route the generic `klarna` code to Adyen.

| Product | `paymentMethodCode` | What the customer gets |
| - | - | - |
| Klarna Pay Later | `klarnaPayLater` | Pay within 30 days. |
| Klarna Pay Now | `klarnaPayNow` | Pay in full straight away. |
| Klarna Pay Over Time | `klarnaPayOverTime` | Pay in installments. |

Adyen filters the Klarna products by amount and country, so lookup can return only some of them for a given basket. Klarna Pay Over Time has a minimum amount that depends on the market.

Call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) with `klarnaPayLater`, `klarnaPayNow` or `klarnaPayOverTime` as the `paymentMethodCode`. The response includes the redirect to Klarna.

```json Authorize request theme={null}
{
  "amount": {
    "value": "109.90",
    "currency": "EUR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "klarnaPayLater",
      "amount": {
        "value": "109.90",
        "currency": "EUR"
      },
      "storeInstrument": true,
      "paymentInstrumentData": {
        "futureUsage": "UnscheduledCardOnFile"
      }
    }
  ],
  "meta": {
    "customer": {
      "email": "anna.becker@example.com",
      "name": "Anna",
      "lastName": "Becker",
      "language": "de-DE",
      "country": {
        "code": "DE"
      }
    },
    "order": {
      "billingAddress": {
        "street": "Beispielstraße",
        "doorNumber": "1",
        "postalCode": "10115",
        "city": "Berlin",
        "country": {
          "code": "DE"
        }
      },
      "lines": [
        {
          "id": "sku-1001",
          "name": "Running shoes",
          "quantity": 1,
          "unitPrice": {
            "value": "109.90",
            "currency": "EUR"
          }
        }
      ]
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}
```

This example saves the instrument. Leave out `storeInstrument` and `paymentInstrumentData` for a one-off payment.

After the customer confirms the purchase, Klarna returns them to your `success` or `error` URL. Confirm the result through [webhook notifications](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md) or the execution status before you fulfill the order.

## How Adyen handles Klarna

* With delayed capture, Payrails sends the payment to Adyen as a pre-authorization. When Adyen captures it depends on the Klarna capture setting of your Adyen merchant account. With instant capture, Payrails asks Adyen to capture straight away.
* Payrails doesn't restrict the currency. Use a currency Klarna supports for the customer's country, or Adyen declines the payment.
* To save the instrument, set `storeInstrument` to `true` on the payment composition. Adyen returns a recurring reference, and Payrails stores it as a PSP token.
* For an MIT, send the stored PSP token, keep the same Klarna code as the `paymentMethodCode`, and use `Subscription` or `Unscheduled` as the processing type. Payrails rejects `CardOnFile` and any MIT without a stored token. The basket fields in the preceding table are still required, and the payment completes without a redirect.


## Related topics

- [Klarna](https://docs.payrails.com/docs/integrations/payment-methods/klarna.md)
- [Klarna via Stripe](https://docs.payrails.com/docs/integrations/payment-methods/klarna/stripe.md)
- [Bancontact via Adyen](https://docs.payrails.com/docs/integrations/payment-methods/bancontact/adyen.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.