# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# Klarna

Klarna is a global payments and shopping service that enables consumers to pay online using flexible payment options. Your consumers can quickly complete purchases using saved payment details and choose how to pay while also accessing tools to track spending and manage their finances.

## Before you begin

Ensure you complete the following before you proceed:

- Onboard as a merchant with J.P. Morgan. Contact your relationship manager if you are an existing client or contact [Sales](https://developer.payments.jpmorgan.com/contact/sales) if you are a new client.

- Onboard the [Notifications API](/docs/commerce/optimization-protection/capabilities/notifications/index) to receive notifications for Klarna transactions.

## Availability

 
**Klarna availability**

| Payment method | Payment type | Consumer country | Merchant country | Supported presentment currencies | 
| --- | --- | --- | --- | --- | 
| Klarna | Wallet | AT, AU, BE, CA, CH, CZ, DE, DK, ES, FI, FR, GB, GR, HU, IE, IT, MX, NL, NO, NZ, PL, PT, RO, SE, SK, US | US | USD | 

## How Klarna works

The Klarna payment process follows these steps:

1. Your consumer selects Klarna as their preferred method of payment from your checkout page.

2. You return the redirect URL to your consumer’s browser.

3. The consumer is automatically redirected to Klarna’s hosted payment page for authentication.

4. Once the consumer is authenticated, they select the payment program of their choice.

5. Klarna approves the payment and returns the consumer to your website to complete the order.

6. J.P. Morgan processes the payment transactions and displays the confirmation of a successful transaction on the payment result page.

7. A notification is sent to you containing all the relevant information.

## Payment programs

Klarna offers the following payment programs to your consumers.

 
**Klarna payment options**

| Payment programs | Description | 
| --- | --- | 
| Pay in full | Consumers pay for the order immediately in a single payment. | 
| Pay later | Consumers pay for the order in a single payment within 30 days. | 
| Pay in N | Consumers pay for the purchase in three or four interest-free installments. Note: The total transaction amount is typically spread equally across the installments, but Klarna might occasionally charge your consumer more in the first installment based on the consumer's purchase power and other credit factors. | 
| Financing | Consumers pay for the purchase over a longer term of up to 36 months, which might include interest. Note: Not all consumers are approved for the maximum amount, and approval is subject to credit worthiness. | 

## Presenting Klarna in your payment form

Present Klarna in your payment form by performing the following steps:

1. Integrate the Klarna web SDK.

2. Initialize Klarna web SDK in your checkout experience.

3. Request Klarna’s payment presentation for the current payment context.

4. Render Klarna payment program(s) dynamically in the payment form according to the instructions.

5. Allow the customer to select and deselect a Klarna payment program.

6. Display the Klarna button and start the payment process when clicked.

For a full step by step guide including best practices, refer to the [Klarna Docs](https://docs.klarna.com/acquirer/jpm/recommended-integration/build-the-checkout/klarna-websdk/).

## Conversion features

You can implement Klarna’s [Conversion features](https://docs.klarna.com/acquirer/jpm/additional-features/partner-portal/conversion-boosters/) with your payments. These features should be implemented directly on your online store using the guidelines provided in Klarna Docs and the Klarna Partner Portal:

- [Klarna Express Checkout](https://docs.klarna.com/acquirer/jpm/express-checkout/integration-prerequisites/)

- [On-site Messaging](https://docs.klarna.com/acquirer/jpm/on-site-messaging/integration-prerequisites/)

- [Sign in with Klarna](https://docs.klarna.com/acquirer/jpm/sign-in-with-klarna/integration-prerequisites/)

For conversion features, make sure to add the interoperability-token returned by the Klarna web SDK to the `POST /payments` call.

- Token type (paymentMetadataList.metadataAttribute) - The type of token or key (i.e. Interoperability-token)

- Token value (paymentMetadataList.metadataAttributeValue) - The value for the token.

## Settlement funding

Transaction funding occurs in the same currency as presentment. Klarna sends the settlement file to J.P. Morgan, and we handle settlement processing.

## Refunds

Klarna supports full and partial refunds, which allows you to refund up to 3 years after the payment completes.

**How refunds work:**

- Klarna cancels any remaining payments on a refunded amount and returns the already-paid amount to the consumer.
  - You can also issue multiple partial refunds up to the amount of the original amount.

- Partial refunds update the order to reflect the new total amount.
  - If the partial refund is greater than the remaining balance of the order, Klarna deducts the refund amount from the outstanding balance and returns the difference.
  - If the partial refund is less than the remaining balance of the order, Klarna deducts the amount from the outstanding balance and spreads refunds evenly across the remaining payments.

For more information on how to refund a transaction, refer to [Refund a payment](/docs/commerce/online-payments/capabilities/online-payments/how-to/refund-payment).

> Klarna does not support refunding a payment when it has been escalated to a dispute.
> 

## Supplementary purchase data

You can enhance the consumer experience by including the Supplementary Purchase Data (SPD) in your payment request. This enables more accurate pre-assessment of eligibility, reduces false declines, and helps present the most suitable payment programs. SPD consists of the following fields:

- retailAddenda.level3.lineItems[]

- shipTo[]

- accountHolder[]

- merchantOrderNumber

For more information on Klarna's decision engine and guidelines, refer to the [Klarna Docs](https://docs.klarna.com/acquirer/jpm/get-started/maximize-sales-with-klarna/optimize-conversion-rate/#improve-approval-rates-with-supplementary-purchase-data-spd).

## Payment parameters

The following fields are required for Klarna transactions. All **required (R)** and **conditionally required (CR)** fields must be included for a request to be successful, while **optional (O)** fields increase the approval rate and add extra functionality to a request.

 
**Required fields for Klarna**

| Field name | Description | R, O, or CR | Comments | 
| --- | --- | --- | --- | 
| captureMethod | This value determines whether the payment is captured immediately, after a delay (default is 120 minutes), or manually with a separate API call. If excluded, the payment is captured immediately. - NOW - Indicates the payment is finalized and ready for further processing. Once captured, the payment details cannot be modified. - DELAYED - Indicates the payment will automatically be captured 120 minutes after authorization. This enables voiding the payment for a configured period of time. This delay time is configured at merchant onboarding. - MANUAL - Indicates the payment may change and you will send a subsequent API request to modify the payment details, including the capture method. | O |  | 
| initiatorType | The party who actively initiates the payment, and is related to the Merchant Initiated Framework (MIT). If this field is not provided in the request, it defaults to CARDHOLDER. - MERCHANT - Indicates the request is not directly initiated by the cardholder. - CARDHOLDER - Indicates the request is initiated by the cardholder. | O | For Klarna transactions, the initiatorType must be MERCHANT. | 
| amount | Total monetary value of the payment including all taxes and fees. | R |  | 
| currency | Identifier of the currency for the amount fields. This is the 3 character ISO 4217 currency code. | R |  | 
| merchant.merchantSoftware.companyName | The company name of the software integrated to this API. If merchant is directly integrated, send JPMC. | R |  | 
| merchant.merchantSoftware.productName | The name of the product used for marketing purposes from the consumer's perspective. | R |  | 
| accountOnFile | The value indicates if the merchant maintains the consumer's payment credentials for returning/recurring purchases. Valid values are: - STORED - Indicates the payment is performed using credentials that have previously been stored. - NOT_STORED - This is the default value and indicates the consumer keyed in their payment credentials with no intention to store the credential. - TO_BE_STORED - Indicates the consumer submitted their payment credentials and has given permission to the merchant to store it. | O |  | 
| accountHolder.firstName | The personal name or given name and generally positioned before the last name or family name. | O |  | 
| accountHolder.lastName | The last name of the account holder. | O |  | 
| accountHolder.fullName | The full name of the account holder. | O |  | 
| accountHolder.email | The email address of the account holder. | O |  | 
| accountHolder.billingAddress.line1 | The first line of the street address. | O |  | 
| accountHolder.billingAddress.line2 | The second line of the street address. | O |  | 
| accountHolder.billingAddress.postalCode | The portion of a party’s address that is the encoded representation of a geographic area to facilitate mail delivery services. | O |  | 
| accountHolder.billingAddress.city | The municipality name. | O |  | 
| accountHolder.billingAddress.state | The name of the state or province. | O |  | 
| accountHolder.billingAddress.countryCode | The country code of the address based on Alpha 3 ISO standards. | O |  | 
| accountHolder.nationalId | Identifier of the consumer or business assigned by a government authority. | CR | - If the consumer provides their national ID, you must send it in the payment request. - If this field is entered, countryOfNationality must be provided. | 
| accountHolder.countryOfNationality | The country code of the account holder in the format - ISO 3166-1 alpha-2. | CR | Required field if nationalId is provided. | 
| shipTo.firstName | The part of an individual's full name considered a personal name or given name and generally positioned before the last name or family name. | O |  | 
| shipTo.lastName | The last name or surname. | O |  | 
| shipTo.fullName | The full name of the account holder. | O |  | 
| shipTo.email | The email address of the account holder. | O |  | 
| shipTo.shippingDescription | The description of shipping or delivery method. | O |  | 
| shipTo.shippingCarrierName | The third-party delivery service that ships the merchant’s products to customers. | O |  | 
| shipTo.shippingAddress.line1 | The first line of a street address. | O |  | 
| shipTo.shippingAddress.line2 | The second line of the street address. | O |  | 
| shipTo.shippingAddress.city | The municipality name. | O |  | 
| shipTo.shippingAddress.state | The state or province name. | O |  | 
| shipTo.shippingAddress.postalCode | The portion of a party’s address that is the encoded representation of a geographic area to facilitate mail delivery services. | O |  | 
| shipTo.shippingAddress.countryCode | The country code of the address based on Alpha 3 ISO standards. | O |  | 
| retailAddenda.level3.lineItems.lineItemDescriptionText | The description of the item purchased. | O |  | 
| retailAddenda.level3.lineItems.unitPriceAmount | The monetary value of the per-item cost of a good or service. | O |  | 
| retailAddenda.level3.lineItems.lineItemUnitQuantity | The number of units purchased. | O |  | 
| retailAddenda.level3.lineItems.taxInclusiveLineItemTotalAmount | The monetary value (inclusive of tax) for the price of the product or service multiplied by the quantity of the items purchased, recorded in the transaction addendum data. | O |  | 
| retailAddenda.taxAmount | The monetary value of the tax amount assessed to the payment. | O |  | 
| retailAddenda.isTaxable | Indicates whether tax has been added to the payment. | O |  | 
| merchantOrderNumber | A unique merchant assigned identifier for the confirmation of goods and/or services purchased. | O |  | 
| paymentMetadataList.metadataAttribute | The label or type of the token key attribute when used in a key-value pair. Allowed value is: - Interoperability-token - Enables continuity of the consumer's journey across domains and services. | CR | - Required for using Klarna's Conversion features. - Providing this field increases the probability of approval and seamless transaction processing. | 
| paymentMetadataList.metadataAttributeValue | The textual description of the token value when used in a key-value pair. | CR | - Required for using Klarna's Conversion features. - Providing this field increases the probability of approval and seamless transaction processing. | 
| paymentMethodType.klarna.redirectedPayment.merchantReturnUrl | Information on where the consumer needs to be redirected after payment process completion. Ensure that the URL begins with https. | R |  | 

The following is a sample payload of a Klarna payment request with the interoperability-token.

**HTTP Method: **`POST`
 **Endpoint: **`/payments`
 **Scenario: **Sending a payment request to Klarna with `metadataAttributeValue = Interoperability-token`

```json
{
  "captureMethod": "NOW",
  "amount": 100,
  "currency": "USD",
  "merchant": {
    "merchantSoftware": {
      "companyName": "Payment Company",
      "productName": "Application Name",
      "version": "1.235"
    }
  },
  "initiatorType": "MERCHANT",
  "accountOnFile": "NOT_STORED",
  "paymentMethodType": {
    "klarna": {
      "preferredLanguage": "en_US",
      "redirectedPayment": {
        "merchantReturnUrl": "https://merchantreturnurl.com"
      }
    }
  },
  "merchantOrderNumber": "5450378-030124055633",
  "accountHolder": {
    "billingAddress": {
      "line1": "123 example street",
      "line2": "Apartment 3b",
      "city": "Swansea",
      "state": "MA",
      "postalCode": "33626",
      "countryCode": "USA"
    },
    "firstName": "Nadia",
    "lastName": "Nadja",
    "fullName": "Nadia Nadja",
    "nationalId": "123-45-6789",
    "countryOfNationality": "US",
    "email": "abc.abc@chase.com"
  },
  "shipTo": {
    "shippingAddress": {
      "line1": "123 example street",
      "line2": "Apartment 3b",
      "city": "Swansea",
      "state": "MA",
      "postalCode": "33626",
      "countryCode": "USA"
    },
    "firstName": "Nadia",
    "lastName": "Nadja",
    "fullName": "Nadia Nadja",
    "email": "abc.abc@chase.com",
    "shippingDescription": "TC",
    "shippingCarrierName": "DHL"
  },
  "retailAddenda": {
    "level3": {
      "lineItems": [
        {
          "lineItemDescriptionText": "lineItemDescription",
          "unitPriceAmount": 9000,
          "lineItemUnitQuantity": "1",
          "taxInclusiveLineItemTotalAmount": 9000
        }
      ]
    },
    "taxAmount": 100,
    "isTaxable": true
  },
  "paymentMetadataList": [
    {
      "metadataAttribute": "Interoperability-Token",
      "metadataAttributeValue": "eyadnl565465454kfjkldsj"
    }
  ]
}
```

**Response:**

```json
{
  "transactionId": "07c0e89b-be73-4c32-82eb-a492bd8fd936",
  "requestId": "95fbc223-cbf2-4bd6-ab4e-2c639b570106",
  "transactionState": "CLOSED",
  "responseStatus": "SUCCESS",
  "responseCode": "APPROVED",
  "responseMessage": "Transaction approved",
  "paymentMethodType": {
    "klarna": {
      "preferredLanguage": "en_US",
      "redirectedPayment": {
        "merchantReturnUrl": "https://merchantreturnurl.com"
      }
    }
  },
  "captureMethod": "NOW",
  "captureTime": "2026-03-17T12:25:44.508Z",
  "initiatorType": "MERCHANT",
  "accountOnFile": "NOT_STORED",
  "isVoid": false,
  "transactionDate": "2026-03-17T12:25:44.508Z",
  "isAmountFinal": true,
  "amount": 100,
  "currency": "USD",
  "remainingRefundableAmount": 100,
  "remainingAuthAmount": 10,
  "merchantOrderNumber": "5450378-030124055633",
  "hostReferenceId": "krn:payment:us1:transaction:9c8a8fbb-1c1b-4b2d-a3a4-799bddfe3c93",
  "merchant": {
    "merchantId": "997051471867",
    "merchantSoftware": {
      "companyName": "Payment Company",
      "productName": "Application Name",
      "version": "1.235"
    },
    "merchantCategoryCode": "5047"
  },
  "shipTo": {
    "shippingDescription": "TC"
  },
  "retailAddenda": {
    "taxAmount": 100,
    "isTaxable": true,
    "level3": {
      "lineItems": [
        {
          "lineItemDescriptionText": "test",
          "lineItemUnitQuantity": "1",
          "unitPriceAmount": 9000,
          "taxInclusiveLineItemTotalAmount": 9000
        }
      ]
    }
  },
  "paymentRequest": {
    "paymentRequestId": "07c0e89b-be73-4c32-82eb-a492bd8fd936",
    "paymentRequestStatus": "CLOSED",
    "authorizations": [
      {
        "authorizationId": "07c0e89b-be73-4c32-82eb-a492bd8fd936",
        "amount": 100,
        "transactionStatusCode": "CAPTURED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-03-17T12:25:44.508Z"
      }
    ],
    "captures": [
      {
        "captureId": "07c0e89b-be73-4c32-82eb-a492bd8fd936",
        "amount": 100,
        "transactionStatusCode": "CLOSED",
        "captureRemainingRefundableAmount": 100,
        "referencedAuthorizationIdentifier": "07c0e89b-be73-4c32-82eb-a492bd8fd936"
      }
    ]
  }
}
```

## Related

[Authorize and capture a payment](/docs/commerce/online-payments/capabilities/online-payments/how-to/auth-and-capture-payment)
 [Refund a payment](/docs/commerce/online-payments/capabilities/online-payments/how-to/refund-payment)