Klarna API

https://docs.klarna.com/api/
Admin
Klarna API provides payment processing services including Klarna payments, hosted payment pages,...
Tokens:45,431
Snippets:284
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Response Sample

Source: https://docs.klarna.com/api/payments

Example JSON response for a successful payment.

```APIDOC
## Response Sample

### Description
This is an example of a successful response after a payment request.

### Status Code
200 OK

### Content Type
application/json

### Response Body
```json
{
  "authorized_payment_method": {
    "number_of_days": 0,
    "number_of_installments": 0,
    "type": "invoice"
  },
  "fraud_status": "string",
  "order_id": "string",
  "redirect_url": "https://credit.klarna.com/v1/sessions/0b1d9815-165e-42e2-8867-35bc03789e00/redirect"
}
```
```

--------------------------------

### Request Sample

Source: https://docs.klarna.com/api/payments

Example JSON payload for a payment request.

```APIDOC
## Request Sample

### Description
This is an example of a request payload for initiating a payment.

### Content Type
application/json

### Payload
```json
{
  "auto_capture": false,
  "billing_address": {
    "attention": "Attn",
    "city": "New York",
    "country": "US",
    "email": "test.sam@test.com",
    "family_name": "Andersson",
    "given_name": "Adam",
    "organization_name": "string",
    "phone": "+13106683312",
    "postal_code": "10024-3941",
    "region": "US-NY",
    "street_address": "509 Amsterdam Ave",
    "street_address2": "Floor 22 / Flat 2",
    "title": "Mr."
  },
  "custom_payment_method_ids": [
    "string"
  ],
  "customer": {
    "customer_token": "36115bcd-708d-4712-8c06-976ac5817e18",
    "date_of_birth": "1978-12-31",
    "gender": "male",
    "last_four_ssn": "string",
    "national_identification_number": "string",
    "organization_entity_type": "LIMITED_COMPANY",
    "organization_registration_id": "string",
    "title": "Mr.",
    "type": "organization",
    "vat_id": "string"
  },
  "locale": "en-US",
  "merchant_data": "{\"order_specific\":[{\"substore\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  "merchant_reference1": "ON4711",
  "merchant_reference2": "hdt53h-zdgg6-hdaff2",
  "merchant_urls": {
    "confirmation": "https://www.example-url.com/confirmation",
    "notification": "https://www.example-url.com/notification",
    "push": "https://www.example-url.com/push",
    "authorization": "https://www.example-url.com/authorization",
    "app_return_url": "appName://KlarnaPayment"
  },
  "order_amount": 2000,
  "order_lines": [
    {
      "image_url": "https://www.exampleobjects.com/logo.png",
      "merchant_data": "{\"customer_account_info\":[{\"unique_account_identifier\":\"test@gmail.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]}",
      "name": "Running shoe",
      "product_identifiers": {
        "brand": "shoe-brand",
        "category_path": "Shoes > Running",
        "global_trade_item_number": "4912345678904",
        "manufacturer_part_number": "AD6654412-334.22",
        "color": "white",
        "size": "small"
      },
      "product_url": "https://.../AD6654412.html",
      "quantity": 1,
      "quantity_unit": "pcs",
      "reference": "AD6654412",
      "tax_rate": 2000,
      "total_amount": 2000,
      "total_discount_amount": 500,
      "total_tax_amount": 333,
      "type": "physical",
      "unit_price": 2500,
      "subscription": {
        "name": "string",
        "interval": "DAY",
        "interval_count": 1
      }
    }
  ],
  "order_tax_amount": 333,
  "purchase_country": "US",
  "purchase_currency": "USD",
  "shipping_address": {
    "attention": "Attn",
    "city": "New York",
    "country": "US",
    "email": "test.sam@test.com",
    "family_name": "Andersson",
    "given_name": "Adam",
    "organization_name": "string",
    "phone": "+13106683312",
    "postal_code": "10024-3941",
    "region": "US-NY",
    "street_address": "509 Amsterdam Ave",
    "street_address2": "Floor 22 / Flat 2",
    "title": "Mr."
  }
}
```
```

--------------------------------

### Define Locale and Country

Source: https://docs.klarna.com/api-reference/direct-partner/data-types

Example of specifying locale and purchase country in a request body.

```json
{
  "locale": "en-US",
  "purchase_country": "US"
}
```

--------------------------------

### Create Payment Session Response

Source: https://docs.klarna.com/api/payments

Example success response for creating a Klarna Payments session.

```APIDOC
## Create Payment Session Response (200 OK)

### Description
Successful creation of a Klarna Payments session.

### Response
#### Success Response (200)
- **client_token** (string) - The client token for the session.
- **payment_method_categories** (array) - List of available payment method categories.
  - **asset_urls** (object) - URLs for payment method assets.
    - **descriptive** (string) - Descriptive asset URL.
    - **standard** (string) - Standard asset URL.
  - **identifier** (string) - Identifier for the payment method category.
  - **name** (string) - Name of the payment method category.
- **session_id** (string) - The unique session ID.

### Response Example
```json
{
  "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
  "payment_method_categories": [
    {
      "asset_urls": {
        "descriptive": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
        "standard": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"
      },
      "identifier": "klarna",
      "name": "Pay with Klarna"
    }
  ],
  "session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
}
```
```

--------------------------------

### Create Payment Session Request

Source: https://docs.klarna.com/api/payments

Example payload for creating a Klarna Payments session.

```APIDOC
## Create Payment Session

### Description
This endpoint is used to create a Klarna Payments session.

### Method
POST

### Endpoint
/payments/v1/sessions

### Request Body
- **acquiring_channel** (string) - Required - The acquiring channel for the payment.
- **attachment** (object) - Optional - Attachment details for the payment.
  - **body** (string) - Required - The body of the attachment.
  - **content_type** (string) - Required - The content type of the attachment.
- **billing_address** (object) - Required - Billing address details.
  - **attention** (string) - Optional - Attention to.
  - **city** (string) - Required - City.
  - **country** (string) - Required - Country code (ISO 3166-1 alpha-2).
  - **email** (string) - Optional - Email address.
  - **family_name** (string) - Required - Family name.
  - **given_name** (string) - Required - Given name.
  - **organization_name** (string) - Optional - Organization name.
  - **phone** (string) - Optional - Phone number.
  - **postal_code** (string) - Required - Postal code.
  - **region** (string) - Optional - Region or state.
  - **street_address** (string) - Required - Street address.
  - **street_address2** (string) - Optional - Second line of street address.
  - **title** (string) - Optional - Title.
- **custom_payment_method_ids** (array) - Optional - Custom payment method IDs.
- **customer** (object) - Optional - Customer details.
  - **customer_token** (string) - Optional - Customer token.
  - **date_of_birth** (string) - Optional - Date of birth (YYYY-MM-DD).
  - **gender** (string) - Optional - Gender.
  - **last_four_ssn** (string) - Optional - Last four digits of SSN.
  - **national_identification_number** (string) - Optional - National identification number.
  - **organization_entity_type** (string) - Optional - Organization entity type.
  - **organization_registration_id** (string) - Optional - Organization registration ID.
  - **title** (string) - Optional - Title.
  - **type** (string) - Required - Customer type (person or organization).
  - **vat_id** (string) - Optional - VAT ID.
- **design** (string) - Optional - Design identifier.
- **locale** (string) - Required - Locale for the session.
- **merchant_data** (string) - Optional - Merchant-specific data.
- **merchant_reference1** (string) - Optional - Merchant reference 1.
- **merchant_reference2** (string) - Optional - Merchant reference 2.
- **merchant_urls** (object) - Required - URLs for merchant notifications and returns.
  - **confirmation** (string) - Required - Confirmation URL.
  - **notification** (string) - Optional - Notification URL.
  - **push** (string) - Optional - Push notification URL.
  - **authorization** (string) - Optional - Authorization URL.
  - **app_return_url** (string) - Optional - App return URL.
- **options** (object) - Optional - Payment session options.
  - **color_border** (string) - Optional - Border color.
  - **color_border_selected** (string) - Optional - Selected border color.
  - **color_details** (string) - Optional - Details color.
  - **color_text** (string) - Optional - Text color.
  - **radius_border** (string) - Optional - Border radius.
- **order_amount** (integer) - Required - Order amount in the smallest currency unit.
- **order_lines** (array) - Optional - Order lines details.
  - **image_url** (string) - Optional - Image URL for the order line.
  - **merchant_data** (string) - Optional - Merchant-specific data for the order line.
  - **name** (string) - Required - Name of the order line item.
  - **product_identifiers** (object) - Optional - Product identifiers.
    - **brand** (string) - Optional - Brand of the product.
    - **category_path** (string) - Optional - Category path.
    - **global_trade_item_number** (string) - Optional - GTIN.
    - **manufacturer_part_number** (string) - Optional - Manufacturer part number.
    - **color** (string) - Optional - Color.
    - **size** (string) - Optional - Size.
  - **product_url** (string) - Optional - Product URL.
  - **quantity** (integer) - Required - Quantity of the item.
  - **quantity_unit** (string) - Optional - Unit of quantity.
  - **reference** (string) - Required - Merchant's reference for the order line.
  - **tax_rate** (integer) - Required - Tax rate (in basis points).
  - **total_amount** (integer) - Required - Total amount for the order line.
  - **total_discount_amount** (integer) - Optional - Total discount amount for the order line.
  - **total_tax_amount** (integer) - Optional - Total tax amount for the order line.
  - **type** (string) - Required - Type of order line item.
  - **unit_price** (integer) - Required - Unit price of the item.
  - **subscription** (object) - Optional - Subscription details.
    - **name** (string) - Optional - Subscription name.
    - **interval** (string) - Required - Subscription interval (e.g., DAY, WEEK, MONTH, YEAR).
    - **interval_count** (integer) - Required - Number of intervals.
- **order_tax_amount** (integer) - Required - Total tax amount for the order.
- **purchase_country** (string) - Required - Purchase country code (ISO 3166-1 alpha-2).
- **purchase_currency** (string) - Required - Purchase currency code (ISO 4217).
- **shipping_address** (object) - Optional - Shipping address details.
  - **attention** (string) - Optional - Attention to.
  - **city** (string) - Required - City.
  - **country** (string) - Required - Country code (ISO 3166-1 alpha-2).
  - **email** (string) - Optional - Email address.
  - **family_name** (string) - Required - Family name.
  - **given_name** (string) - Required - Given name.
  - **organization_name** (string) - Optional - Organization name.
  - **phone** (string) - Optional - Phone number.
  - **postal_code** (string) - Required - Postal code.
  - **region** (string) - Optional - Region or state.
  - **street_address** (string) - Required - Street address.
  - **street_address2** (string) - Optional - Second line of street address.
  - **title** (string) - Optional - Title.
- **intent** (string) - Required - The intent of the session (e.g., 'buy').
- **step_up_id** (string) - Optional - Step-up authentication ID.

### Request Example
```json
{
  "acquiring_channel": "ECOMMERCE",
  "attachment": {
    "body": "{\"customer_account_info\":[{\"unique_account_identifier\":\"test@gmail.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]નું",
    "content_type": "application/vnd.klarna.internal.emd-v2+json"
  },
  "billing_address": {
    "attention": "Attn",
    "city": "New York",
    "country": "US",
    "email": "test.sam@test.com",
    "family_name": "Andersson",
    "given_name": "Adam",
    "organization_name": "string",
    "phone": "+13106683312",
    "postal_code": "10024-3941",
    "region": "US-NY",
    "street_address": "509 Amsterdam Ave",
    "street_address2": "Floor 22 / Flat 2",
    "title": "Mr."
  },
  "custom_payment_method_ids": [
    "string"
  ],
  "customer": {
    "customer_token": "36115bcd-708d-4712-8c06-976ac5817e18",
    "date_of_birth": "1978-12-31",
    "gender": "male",
    "last_four_ssn": "string",
    "national_identification_number": "string",
    "organization_entity_type": "LIMITED_COMPANY",
    "organization_registration_id": "string",
    "title": "Mr.",
    "type": "organization",
    "vat_id": "string"
  },
  "design": "string",
  "locale": "en-US",
  "merchant_data": "{\"order_specific\":[{\"substore\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  "merchant_reference1": "ON4711",
  "merchant_reference2": "hdt53h-zdgg6-hdaff2",
  "merchant_urls": {
    "confirmation": "https://www.example-url.com/confirmation",
    "notification": "https://www.example-url.com/notification",
    "push": "https://www.example-url.com/push",
    "authorization": "https://www.example-url.com/authorization",
    "app_return_url": "appName://KlarnaPayment"
  },
  "options": {
    "color_border": "#FF9900",
    "color_border_selected": "#FF9900",
    "color_details": "#FF9900",
    "color_text": "#FF9900",
    "radius_border": "5px"
  },
  "order_amount": 2000,
  "order_lines": [
    {
      "image_url": "https://www.exampleobjects.com/logo.png",
      "merchant_data": "{\"customer_account_info\":[{\"unique_account_identifier\":\"test@gmail.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]નું",
      "name": "Running shoe",
      "product_identifiers": {
        "brand": "shoe-brand",
        "category_path": "Shoes > Running",
        "global_trade_item_number": "4912345678904",
        "manufacturer_part_number": "AD6654412-334.22",
        "color": "white",
        "size": "small"
      },
      "product_url": "https://.../AD6654412.html",
      "quantity": 1,
      "quantity_unit": "pcs",
      "reference": "AD6654412",
      "tax_rate": 2000,
      "total_amount": 2000,
      "total_discount_amount": 500,
      "total_tax_amount": 333,
      "type": "physical",
      "unit_price": 2500,
      "subscription": {
        "name": "string",
        "interval": "DAY",
        "interval_count": 1
      }
    }
  ],
  "order_tax_amount": 333,
  "purchase_country": "US",
  "purchase_currency": "USD",
  "shipping_address": {
    "attention": "Attn",
    "city": "New York",
    "country": "US",
    "email": "test.sam@test.com",
    "family_name": "Andersson",
    "given_name": "Adam",
    "organization_name": "string",
    "phone": "+13106683312",
    "postal_code": "10024-3941",
    "region": "US-NY",
    "street_address": "509 Amsterdam Ave",
    "street_address2": "Floor 22 / Flat 2",
    "title": "Mr."
  },
  "intent": "buy",
  "step_up_id": "string"
}
```
```

--------------------------------

### Example rate limit response headers

Source: https://docs.klarna.com/api-reference/direct-partner/rate-limiting

Sample HTTP response headers showing multiple active quota policies and current remaining capacity.

```json
X-Ratelimit-Limit: 40, 40;w=1;name="account_payment-request-capture",100;w=1;name="psp_payment-request-capture"
X-Ratelimit-Remaining: 15
X-Ratelimit-Reset: 1
```

--------------------------------

### Order Management Request Payload Example

Source: https://docs.klarna.com/api/ordermanagement

This is an example of a JSON payload for an order management request, likely for creating or updating an order with shipping details.

```json
{
  "shipping_address": {
    "attention": "John Smith",
    "city": "New York",
    "country": "US",
    "email": "test.sam@test.com",
    "family_name": "Andersson",
    "given_name": "Adam",
    "organization_name": "Klarna",
    "phone": "1-555-555-5555",
    "postal_code": "10024-3941",
    "region": "US-NY",
    "street_address": "509 Amsterdam Ave",
    "street_address2": "Floor 22 / Flat 2",
    "title": "Mr."
}

}
```

--------------------------------

### Handle Authentication Failure Response

Source: https://docs.klarna.com/api-reference/psp/merchant-onboarding-api-authentication-with-oauth

Example JSON response body returned when an authentication request fails due to invalid claims or other errors.

```json
{   "code": "invalidJwt",   "message": "The given jwt is invalid!",   "errors": [     {       "code": "invalidJwt",       "message": "JWT (claims->{\"iss\":\"issuer-name\",\"scope\":\"scope-name\",\"aud\":\"https://auth-bp.klarna.com/oauth2/v1/token\",\"iat\":1439378628,\"exp\":1439383798}) rejected due to invalid claims. Additional details: [The Expiration Time (exp=NumericDate{1439383798 -> Aug 12, 2015 2:49:58 PM CEST}) claim value cannot be more than 10 minutes in the future relative to the evaluation time NumericDate{1439378646 -> Aug 12, 2015 1:24:06 PM CEST} (even when providing 90 seconds of leeway to account for clock skew).]"     }   ] }
```

--------------------------------

### JWT Structure Example

Source: https://docs.klarna.com/api-reference/psp/merchant-onboarding-api-authentication-with-oauth

The final concatenated structure of the JWT components.

```text
{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}
```

--------------------------------

### Pre-encoded JWT Example

Source: https://docs.klarna.com/api-reference/psp/merchant-onboarding-api-authentication-with-oauth

A representation of a JWT before Base64url encoding is applied.

```json
{"alg":"RS256","typ":"JWT"}.
{
  "iss":"{{partner_name}}.moma.playground",
  "scope":"moma.*",
  "aud":"https://auth-bp.klarna.com/oauth2/v1/token",
  "iat":1435052936,
  "exp":1435052996
}.
[signature bytes]
```

--------------------------------

### Klarna Get Refund Details Response Sample

Source: https://docs.klarna.com/api/ordermanagement

This JSON response provides details of a found refund, including order lines, amounts, and timestamps.

```json
{
  "credit_invoice": true,
  "description": "The item was returned and the order refunded.",
  "order_lines": [
    {
      "image_url": "https://yourstore.example/product/headphones.png",
      "merchant_data": "Some metadata",
      "name": "string",
      "product_identifiers": {
        "brand": "Intel",
        "category_path": "Electronics Store > Computers & Tablets > Desktops",
        "color": "Denim blue",
        "global_trade_item_number": "735858293167",
        "manufacturer_part_number": "BOXNUC5CPYH",
        "size": "4"
},
      "product_url": "https://yourstore.example/product/headphones",
      "quantity": 1,
      "quantity_unit": "pcs.",
      "reference": "75001",
      "subscription": {
        "interval": "MONTH",
        "interval_count": 1,
        "name": "string"
},
      "tax_rate": 0,
      "total_amount": 200000000,
      "total_discount_amount": 0,
      "total_tax_amount": 200000000,
      "type": "physical",
      "unit_price": 200000000
}
],
  "reference": "string",
  "refund_id": "b2cb4f2e-2781-4359-80ad-555735ebb8d8",
  "refunded_amount": 0,
  "refunded_at": "2015-12-04T15:17:40Z"
}
```

--------------------------------

### initiateKlarnaWebSdk

Source: https://docs.klarna.com/api-reference/direct-partner/integration-resilience

Initializes the Klarna WebSDK with integrator metadata.

```APIDOC
## initiateKlarnaWebSdk

### Description
Initializes the Klarna WebSDK and registers application metadata via the integrator object.

### Parameters
- **clientId** (string) - Required - The client identifier.
- **integrator** (object) - Required - Metadata object containing name, moduleName, moduleVersion, and sessionReference.
```

--------------------------------

### Get Payment Session Details

Source: https://docs.klarna.com/api/payments

Retrieves all data collected during a Klarna Payments session, including customer and order information. This is useful for getting the latest status and details of an ongoing payment.

```APIDOC
## GET /payments/v1/sessions/{session_id}

### Description
Use this API call to get a Klarna Payments session. You can read the Klarna Payments session at any time after it has been created, to get information about it. This will return all data that has been collected during the session. Read more on **Read an existing payment session**.

### Method
GET

### Endpoint
https://api.klarna.com/payments/v1/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier for the payment session.

### Responses
#### Success Response (200)
- **Details**: Successful operation. Returns all collected session data.

#### Error Responses
- **403**: You were not authorized to execute this operation.
- **404**: The session does not exist.
```

--------------------------------

### Get Klarna Payments Session Details

Source: https://docs.klarna.com/api/payments

Use this GET request to retrieve all data collected during a Klarna Payments session, identified by its unique session ID. This is useful for checking the status and details of an ongoing payment.

```http
GET https://api.klarna.com/payments/v1/sessions/{session_id}
```

--------------------------------

### Create Merchant with Transaction Approval Marker

Source: https://docs.klarna.com/api-reference/psp/merchant-account-status-native-partners

Use this request to trigger the onboarding process up to the TRANSACTIONS_ENABLED state in the playground environment.

```http
POST /accountmanagement/v1/merchant

{
  "email": "john.doe+faketransactionsapproved@example.com"
  ...
}
```

--------------------------------

### Initialize WebSDK with Integrator Context

Source: https://docs.klarna.com/api-reference/direct-partner/integration-resilience

Include the integrator object during WebSDK initialization to register application metadata.

```javascript
const Klarna = await initiateKlarnaWebSdk({
  clientId: 'your_client_id_here',
  integrator: {
    name: 'AcquiringPartner',
    moduleName: 'SubIntegration',
    moduleVersion: '2.0',
    sessionReference: 'xxx',  },
});
```

--------------------------------

### Create Payment Session

Source: https://docs.klarna.com/api/payments

Initiates a payment session with Klarna. This is the first step in the payment process, where you provide order details, customer information, and merchant references.

```APIDOC
## POST /payments/v1/sessions

### Description
Creates a payment session for a customer. This endpoint is used to initialize the payment process by providing all necessary details about the order and the customer.

### Method
POST

### Endpoint
https://api.klarna.com/payments/v1/sessions

### Parameters
#### Request Body
- **session_request** (object) - Required - Contains all details for the session.
  - **acquiring_channel** (string) - Enum: "ECOMMERCE" "IN_STORE" "TELESALES" - The acquiring channel in which the session takes place. Defaults to "ECOMMERCE".
  - **attachment** (object) - Extra Merchant Data required for additional risk check.
  - **billing_address** (object) - The billing address of the customer.
  - **custom_payment_method_ids** (Array of strings) - Promo codes to define specific payment options.
  - **customer** (object) - Object to provide the details of the customer.
  - **design** (string) - Design package to use in the session.
  - **locale** (string) - Used to define the language and region of the customer (e.g., "en-US").
  - **merchant_data** (string) - Pass through field for merchant's reference information (max 6000 characters).
  - **merchant_reference1** (string) - Merchant's internal order number or other reference (max 255 characters).
  - **merchant_reference2** (string) - Merchant's internal order number or other reference, available in settlement files (max 255 characters).
  - **merchant_urls** (object) - URLs for different stages of the Klarna process.
  - **options** (object) - Design customization options for the Klarna Payments iframe.
  - **order_amount** (integer) - Required - Total amount of the order including tax (in minor units, e.g., 2500 for 25 Euros).
  - **order_lines** (Array of objects) - Required - List of line items in the order (1 to 1000 items).
  - **order_tax_amount** (integer) - Total tax amount of the order (in minor units).
  - **purchase_country** (string) - Required - Purchase country of the customer (ISO 3166 alpha-2, e.g., "GB").
  - **purchase_currency** (string) - Required - Purchase currency of the order (ISO 4217, e.g., "USD").
  - **shipping_address** (object) - The shipping address of the consumer.
  - **intent** (string) - Enum: "buy" "tokenize" "buy_and_tokenize" - Intent for the session.
  - **step_up_id** (string) - Step-up recovery identifier.

### Responses
#### Success Response (200)
Successful operation.

#### Error Responses
- **400**: Bad Request - We were unable to create a session with the provided data. Some field constraint was violated.
- **403**: Forbidden - You were not authorized to execute this operation.
```

--------------------------------

### Get Order Details

Source: https://docs.klarna.com/api/ordermanagement

Retrieves the details of a specific order using its unique order ID.

```APIDOC
## GET /ordermanagement/v1/orders/{order_id}

### Description
Retrieves the details of an order that has the given order ID.

### Method
GET

### Endpoint
https://api.klarna.com/ordermanagement/v1/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier for the order.

#### Header Parameters
- **Klarna-Integrator** (string) - Optional - Identifier for the integrator.

### Responses
#### Success Response (200)
- **Order found**: Indicates that the order details were successfully retrieved.

#### Error Response (404)
- **Order not found**: Indicates that no order with the specified ID was found.
```

--------------------------------

### Order Response Sample

Source: https://docs.klarna.com/api/ordermanagement

This snippet shows a successful response (200 OK) for an order, detailing its various components like billing address, captured amount, order lines, and timestamps.

```APIDOC
## GET /orders/{order_id}

### Description
Retrieves the details of a specific order.

### Method
GET

### Endpoint
/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order.

### Response
#### Success Response (200)
- **billing_address** (object) - The billing address associated with the order.
- **captured_amount** (integer) - The total amount that has been captured for the order.
- **captures** (array) - A list of capture objects, each detailing a capture transaction.
- **created_at** (string) - The timestamp when the order was created.
- **customer** (object) - Information about the customer who placed the order.
- **expires_at** (string) - The timestamp when the order will expire.
- **fraud_status** (string) - The fraud status of the order.
- **initial_payment_method** (object) - Details about the initial payment method used for the order.
- **klarna_reference** (string) - Klarna's internal reference for the order.
- **locale** (string) - The locale of the order.
- **merchant_data** (string) - Merchant-specific data associated with the order.
- **merchant_reference1** (string) - Merchant's first reference for the order.
- **merchant_reference2** (string) - Merchant's second reference for the order.
- **order_amount** (integer) - The total amount of the order.
- **order_id** (string) - The unique identifier of the order.
- **order_lines** (array) - A list of order lines, detailing the products or services in the order.

#### Response Example
```json
{
  "billing_address": {
    "attention": "John Smith",
    "city": "New York",
    "country": "US",
    "email": "test.sam@test.com",
    "family_name": "Andersson",
    "given_name": "Adam",
    "organization_name": "Klarna",
    "phone": "1-555-555-5555",
    "postal_code": "10024-3941",
    "region": "US-NY",
    "street_address": "509 Amsterdam Ave",
    "street_address2": "Floor 22 / Flat 2",
    "title": "Mr."
  },
  "captured_amount": 0,
  "captures": [
    {
      "billing_address": {
        "attention": "John Smith",
        "city": "New York",
        "country": "US",
        "email": "test.sam@test.com",
        "family_name": "Andersson",
        "given_name": "Adam",
        "organization_name": "Klarna",
        "phone": "1-555-555-5555",
        "postal_code": "10024-3941",
        "region": "US-NY",
        "street_address": "509 Amsterdam Ave",
        "street_address2": "Floor 22 / Flat 2",
        "title": "Mr."
      },
      "capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
      "captured_amount": 1,
      "captured_at": "2015-11-19T01:51:17Z",
      "description": "Order has been shipped",
      "klarna_reference": "K4MADNY-1",
      "order_lines": [
        {
          "image_url": "https://yourstore.example/product/headphones.png",
          "merchant_data": "Some metadata",
          "name": "string",
          "product_identifiers": {
            "brand": "Intel",
            "category_path": "Electronics Store > Computers & Tablets > Desktops",
            "color": "Denim blue",
            "global_trade_item_number": "735858293167",
            "manufacturer_part_number": "BOXNUC5CPYH",
            "size": "4"
          },
          "product_url": "https://yourstore.example/product/headphones",
          "quantity": 1,
          "quantity_unit": "pcs.",
          "reference": "75001",
          "subscription": {
            "interval": "MONTH",
            "interval_count": 1,
            "name": "string"
          },
          "tax_rate": 0,
          "total_amount": 200000000,
          "total_discount_amount": 0,
          "total_tax_amount": 200000000,
          "type": "physical",
          "unit_price": 200000000
        }
      ],
      "reference": "string",
      "refunded_amount": 0,
      "shipping_address": {
        "attention": "John Smith",
        "city": "New York",
        "country": "US",
        "email": "test.sam@test.com",
        "family_name": "Andersson",
        "given_name": "Adam",
        "organization_name": "Klarna",
        "phone": "1-555-555-5555",
        "postal_code": "10024-3941",
        "region": "US-NY",
        "street_address": "509 Amsterdam Ave",
        "street_address2": "Floor 22 / Flat 2",
        "title": "Mr."
      },
      "shipping_info": [
        {
          "return_shipping_company": "dhl-express",
          "return_tracking_number": "93456415674545679888",
          "return_tracking_uri": "http://shipping.example/findmypackage?93456415674545679888",
          "shipping_company": "dhl-express",
          "shipping_method": "Home",
          "tracking_number": "63456415674545679874",
          "tracking_uri": "http://shipping.example/findmypackage?63456415674545679874"
        }
      ]
    }
  ],
  "created_at": "2015-11-29T10:25:40Z",
  "customer": {
    "date_of_birth": "1981-09-06",
    "national_identification_number": "string"
  },
  "expires_at": "2015-12-04T10:26:06Z",
  "fraud_status": "ACCEPTED",
  "initial_payment_method": {
    "description": "Slice it (Fixed Payments)",
    "number_of_installments": 3,
    "type": "FIXED_AMOUNT"
  },
  "klarna_reference": "K4MADNY",
  "locale": "en-US",
  "merchant_data": "Order metadata",
  "merchant_reference1": "10001",
  "merchant_reference2": "501",
  "order_amount": 0,
  "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  "order_lines": [
    {
      "image_url": "https://yourstore.example/product/headphones.png",
      "merchant_data": "Some metadata",
      "name": "string",
      "product_identifiers": {
        "brand": "Intel",
        "category_path": "Electronics Store > Computers & Tablets > Desktops",
        "color": "Denim blue",
        "global_trade_item_number": "735858293167",
        "manufacturer_part_number": "BOXNUC5CPYH",
        "size": "4"
      },
      "product_url": "https://yourstore.example/product/headphones",
      "quantity": 1,
      "quantity_unit": "pcs.",
      "reference": "75001",
      "subscription": {
        "interval": "MONTH",
        "interval_count": 1,
        "name": "string"
      },
      "tax_rate": 0,
      "total_amount": 200000000,
      "total_discount_amount": 0,
      "total_tax_amount": 200000000,
      "type": "physical"
    }
  ]
}
```
    },
    { 
      "title": "Order Not Found Response Sample",
      "description": "This snippet shows a response when an order is not found (404 Not Found).",
      "language": "APIDOC",
      "codeList": [
        {
          "language": "APIDOC",
          "code": "## GET /orders/{order_id}\n\n### Description\nRetrieves the details of a specific order.\n\n### Method\nGET\n\n### Endpoint\n/orders/{order_id}\n\n### Response\n#### Error Response (404)\n- **error_code** (string) - A machine-readable error code.\n- **message** (string) - A human-readable error message.\n\n#### Response Example\n```json\n{\n  \"error_code\": \"ORDER_NOT_FOUND\",\n  \"message\": \"The requested order could not be found.\"\n}\n```"
        }
      ]
    }
  ]
}
```

--------------------------------

### Create an order

Source: https://docs.klarna.com/api/payments

Use this API call to create a new order. Placing an order towards Klarna means that the Klarna Payments session will be closed and that an order will be created in Klarna's system.

```APIDOC
## POST /payments/v1/authorizations/{authorizationToken}/order

### Description
Creates a new order after a successful authorization. This action closes the Klarna Payments session and creates an order in Klarna's system. You must include the `authorization_token` obtained from a successful authorization.

### Method
POST

### Endpoint
https://api.klarna.com/payments/v1/authorizations/{authorizationToken}/order

### Parameters
#### Path Parameters
- **authorizationToken** (string) - Required - The token obtained from a successful authorization.

#### Request Body schema: application/json
- **auto_capture** (boolean) - Optional - Default: false. Allows the merchant to trigger auto capturing.
- **billing_address** (object) - Optional - Provides the billing address of the customer. If not provided, Klarna will collect details within the iFrame before authorization.
- **custom_payment_method_ids** (Array of strings) - Optional - Used to define specific payment options within a payment category or to provide promotional offers to specific customers.
- **customer** (object) - Optional - Provides details of the customer making the payment.
- **locale** (string) - Optional - Used to define the language and region of the customer (e.g., 'en-US'). Follows RFC 1766 format.
- **merchant_data** (string) - Optional - Max 6000 characters. Pass-through field for order information for later reference.
- **merchant_reference1** (string) - Optional - Max 255 characters. Merchant's internal order number or reference.
- **merchant_reference2** (string) - Optional - Max 255 characters. Merchant's internal order number or reference, available in settlement files.
- **merchant_urls** (object) - Optional - Specifies various merchant URLs needed at different stages of the process.
- **order_amount** (integer) - Required - >= 0. Total amount of the order including tax and discounts, in minor units (e.g., 2500 for 25 Euros).
- **order_lines** (Array of objects) - Required - 1 to 1000 items. Contains the list of line items in the order.
- **order_tax_amount** (integer) - Required - >= 0. Total tax amount of the order, in minor units.
- **purchase_country** (string) - Required - Formatted according to ISO 3166 alpha-2 standard (e.g., 'GB', 'SE').
- **purchase_currency** (string) - Required - Formatted according to ISO 4217 standard (e.g., 'USD', 'EUR').
- **shipping_address** (object) - Optional - The shipping address of the consumer. Only needed if different from the billing address.

### Responses
#### Success Response (200)
Order was successfully created.

#### Error Responses
- **400**: Bad Request - Unable to create an order with the provided data. Field constraint violated.
- **403**: Forbidden - Not authorized to execute this operation.
- **404**: Not Found - The authorization does not exist.
- **409**: Conflict - The data in the request does not match the session for the authorization.
```

--------------------------------

### Acknowledgment Value Calculation

Source: https://docs.klarna.com/api-reference/psp/receive-updates-on-changes-in-merchant-account-native-partners

Example of calculating the SHA512 hash for the acknowledgment value using the request data and shared secret.

```text
acknowledgement_value = sha512("{\"merchant_id\":\"A100001\",\"notification_type\":\"REQUEST_FOR_ACKNOWLEDGEMENT\",\"changed_data\":\"CREDENTIALS\",\"requested_at\":\"2017-05-08T15:24:59.000Z\",\"shared_secret\":\"partner-secret\"}");
```

--------------------------------

### Get Refund Details

Source: https://docs.klarna.com/api/ordermanagement

Retrieves the details of a specific refund associated with an order. Requires the order ID and refund ID.

```APIDOC
## Get refund details 
Get refund. 
##### Authorizations:
_basicAuth_
##### path Parameters
order_idrequired| string Order id  
---|---  
refund_idrequired| string Refund id  
### Responses
**200**
Refund found.
**404**
Order or refund not found.
get/ordermanagement/v1/orders/{order_id}/refunds/{refund_id}
https://api.klarna.com/ordermanagement/v1/orders/{order_id}/refunds/{refund_id}
###  Response samples 
  * 200
  * 404


Content type
application/json
Copy
Expand all  Collapse all 
`{
  * "credit_invoice": true,
  * "description": "The item was returned and the order refunded.",
  * "order_lines": [
    * {
      * "image_url": "https://yourstore.example/product/headphones.png",
      * "merchant_data": "Some metadata",
      * "name": "string",
      * "product_identifiers": {
        * "brand": "Intel",
        * "category_path": "Electronics Store > Computers & Tablets > Desktops",
        * "color": "Denim blue",
        * "global_trade_item_number": "735858293167",
        * "manufacturer_part_number": "BOXNUC5CPYH",
        * "size": "4"
},
      * "product_url": "https://yourstore.example/product/headphones",
      * "quantity": 1,
      * "quantity_unit": "pcs.",
      * "reference": "75001",
      * "subscription": {
        * "interval": "MONTH",
        * "interval_count": 1,
        * "name": "string"
},
      * "tax_rate": 0,
      * "total_amount": 200000000,
      * "total_discount_amount": 0,
      * "total_tax_amount": 200000000,
      * "type": "physical",
      * "unit_price": 200000000
}
],
  * "reference": "string",
  * "refund_id": "b2cb4f2e-2781-4359-80ad-555735ebb8d8",
  * "refunded_amount": 0,
  * "refunded_at": "2015-12-04T15:17:40Z"

}`
```
Tokens:
Raw