How to send Klarna Network Data
How Partners share purchase data with Klarna through their Acquiring Partner — via the klarna_network_data passthrough or structured API fields — including the required data structure for line items, purchase reference, customer details, and shipping.
Partners integrating Klarna through an Acquiring Partner do not call Klarna's APIs directly. The Acquiring Partner acts as the transmission layer between Partners and Klarna. This page explains how purchase data reaches Klarna through that layer, what data to share, and when.
Providing complete purchase data — including line items, purchase reference, customer details, and shipping information — is a contractual requirement under the Klarna Network Rules. The Acquiring Partner must ensure Partners can share this data across all integration patterns, including plugins and hosted payment pages.
How to share data
There are two ways through which purchase data flows between Partners, the Acquiring Partner, and Klarna.
Option 1: klarna_network_data passthrough (recommended)
klarna_network_data is a serialized JSON string that Partners include directly in the Payment Request to the Acquiring Partner. The Acquiring Partner forwards it to Klarna exactly as received, without interpreting or modifying it.This is the recommended channel for sharing purchase data. Because Partners control the format directly using Klarna's own schema, there is no risk of data loss from intermediate mapping. Partners starting a new integration should use this approach from the start.
klarna_network_data supports the full range of purchase data:- Line items with name, quantity, amounts, tax, images, URLs, and product identifiers
- Purchase reference
- Customer details — name, email, phone, address
- Shipping information — delivery address, carrier, method, recipient
- Industry-specific data such as travel reservations, lodging details, and car rental
- Customer account purchase history
For the full schema definition, refer to the Klarna Network Data Schema
documentation.
documentation.Klarna also returns data to Partners through a reverse passthrough field called
klarna_network_response_data. The Acquiring Partner forwards this field back to Partners without alteration. Common use cases include:- Receiving a
payment_request_urlto launch the Klarna Purchase Journey - Receiving Payment Request or Payment Transaction identifiers
Partners should validate that their
klarna_network_data JSON includes "operation": "payment_request" and nests the data inside "request". Omitting these fields causes Klarna to silently reject the data without returning an error.Option 2: Structured fields in the Acquiring Partner's API
Some Acquiring Partners expose fields for line items, customer details, shipping information, and purchase reference directly in their payment API.
If the Acquiring Partner does not support certain fields that Klarna requires, Partners must share those fields using
klarna_network_data instead. Both channels can be used together — structured fields for the data the Acquiring Partner supports, and klarna_network_data for everything else.How data flows from Partners to Klarna
The following diagram summarizes what Partners provide, what the Acquiring Partner does, and what Klarna receives:
sequenceDiagram
participant Partner
participant AP as Acquiring Partner
participant Klarna
alt Passthrough (recommended)
Partner->>AP: klarna_network_data
AP->>Klarna: klarna_network_data (forwarded unchanged)
else Structured fields (if supported)
Partner->>AP: Structured fields in Acquiring Partner's API
AP->>Klarna: Mapped to Klarna schema
end
Note over Partner,Klarna: Session context
Partner->>AP: klarna_network_session_token
AP->>Klarna: Klarna-Network-Session-Token header
Note over Partner,Klarna: Response (outbound from Klarna)
Klarna-->>AP: Klarna response
AP-->>Partner: klarna_network_response_data
The Acquiring Partner is responsible for:
- Forwarding
klarna_network_data— Passing the data Partners provide to Klarna without modification - Returning
klarna_network_response_data— Delivering Klarna's response data to Partners without alteration - Mapping structured fields (when applicable) — Translating Partner API fields to Klarna's schema at Payment Authorization
- Maintaining data across the lifecycle — Ensuring data is transmitted at Payment Authorization, capture, refund, and other post-purchase operations
When to send data in the payment lifecycle
Payment Authorization
This is the most critical point. Partners should send all available data when initiating a payment through the Acquiring Partner:
- Complete line items with name, quantity, amounts, tax, images, URLs, and product identifiers
- Purchase reference — the customer-facing order identifier
- Customer — name, email, phone, address
- Shipping — delivery address, recipient
This data powers Klarna's real-time fraud assessment and underwriting. Missing data at this stage directly impacts approval rates.
Capture
When capturing a Payment Transaction, Partners should send the same line item data again. This ensures:
- Klarna can verify the captured items match the authorized items
- Customer-facing displays remain consistent
- Partial captures are correctly attributed to specific items
If line items change between Payment Authorization and capture (for example, out-of-stock items removed), Partners should update them accurately — but keep
name and product_identifier consistent for items that remain.Refund
When processing refunds, Partners should include the line items being refunded with the same
name and product_identifier used at Payment Authorization and capture. This enables:- Accurate refund mapping to original items
- Clear customer communication about what was refunded
- Proper dispute evidence if the refund is later contested
Post-purchase operations
klarna_network_data is supported in capture and refund calls. When available, Partners should forward it in all API interactions related to post-purchase operations to help Klarna maintain a complete picture of the transaction throughout its lifecycle.Required data structure
Line items
Each line item should include the following fields.
Required:
| Parameter | Description | Operations |
|---|---|---|
name | A clear, customer-facing description of the item. Avoid internal codes or technical terms. Klarna displays this in receipts, the Klarna app, and refund confirmations. | Authorization, Capture, Refund |
quantity | The number of identical items. Must be a positive integer. | Authorization, Capture, Refund |
total_amount | The total amount for this line item in minor currency units, including surcharges and deductions. | Authorization, Capture, Refund |
Highly recommended:
| Parameter | Description | Operations |
|---|---|---|
total_tax_amount | How much of total_amount is tax. Set to 0 if no tax applies — do not omit this field. | Authorization, Capture, Refund |
unit_price | Price per individual item in minor currency units. Important when it differs from total_amount / quantity. | Authorization, Capture, Refund |
product_url | Full HTTPS URL to the product page. Enables linking from Klarna surfaces. | Authorization, Capture, Refund |
image_url | HTTPS URL to a high-quality product image (minimum 400×400px). Displayed in the Klarna app and emails. | Authorization, Capture, Refund |
Optional for enhanced experience:
| Parameter | Description | Operations |
|---|---|---|
product_identifier | Unique identifier such as GTIN, UPC, ISBN, or SKU. Supports fraud assessment, product matching, and dispute evidence. | Authorization, Capture, Refund |
line_item_reference | Partner's internal reference for this line item, used for reconciliation. | Authorization, Capture, Refund |
shipping_reference | Links this item to a specific shipping object in the same request. | Authorization, Capture, Refund |
line_item_metadata.categories | Ordered list of category names from general to specific (up to 10). Improves product classification and fraud assessment. | Authorization, Capture, Refund |
subscription_reference | Links this item to a subscription object within the same payload. | Authorization, Capture, Refund |
Purchase reference
The purchase reference is the customer-facing order identifier. It should be unique per order, stable across all operations, and meaningful to the customer.
| Parameter | Description | Operations |
|---|---|---|
purchase_reference | Customer-facing order number displayed in the Klarna app and communications. Also included in settlement reports for reconciliation. If the Partner is a direct merchant, this can match the payment transaction reference. If the Partner uses an Acquiring Partner, this is the reference the merchant generated for their customer order. Max 255 characters. | Authorization, Capture |
Customer details
Partners should provide as much customer information as available. Klarna uses these data points for fraud assessment, underwriting, and to simplify the sign-up experience for returning customers.
Required:
| Parameter | Description | Operations |
|---|---|---|
given_name | First name of the customer. | Authorization |
family_name | Last name of the customer. | Authorization |
email | Customer's email address. | Authorization |
Highly recommended:
| Parameter | Description | Operations |
|---|---|---|
phone | Customer's phone number in local format (for example, +49017614284340). | Authorization |
address | Customer's billing address. Used as an indicator for fraud assessment and to simplify sign-up. Not used for underwriting and not persisted on Payment Transactions. | Authorization |
address.street_address | Primary street address including street name and number. | Authorization |
address.street_address2 | Additional address details such as apartment, suite, or unit number. | Authorization |
address.postal_code | Postal code formatted according to country rules. | Authorization |
address.city | City or town name. | Authorization |
address.region | State, county, province, or region. Mandatory for US and AU markets. ISO 3166-2 format (for example, US-OH). | Authorization |
address.country | Two-letter country code in ISO 3166-1 alpha-2 format (for example, US, DE, SE). | Authorization |
Optional:
| Parameter | Description | Operations |
|---|---|---|
date_of_birth | Customer's date of birth in YYYY-MM-DD format (for example, 1990-01-01). | Authorization |
national_identification | National identification details. Requires country and number. Supported for US, DK, ES, FI, IT, NO, and SE. | Authorization |
email_last_verified_at | Date of the most recent email verification in ISO 8601 UTC format (for example, 2024-01-01T12:00:00Z). | Authorization |
phone_last_verified_at | Date of the most recent phone verification in ISO 8601 UTC format (for example, 2024-01-01T12:00:00Z). | Authorization |
customer_account.account_identifier | Unique identifier for the customer's account with the Partner (for example, a customer number or loyalty program number). | Authorization |
customer_account.loyalty_level | Level of loyalty within the Partner's loyalty program. Allowed values: LOW, MEDIUM, HIGH. | Authorization |
customer_account.created_at | Date when the customer's account with the Partner was created. ISO 8601 UTC format. | Authorization |
customer_account.updated_at | Date when the customer's account with the Partner was last updated. ISO 8601 UTC format. | Authorization |
customer_device.user_agent | User agent string of the customer's device at the time of the session. | Authorization |
customer_device.ip_address | IP address of the customer's device at the time of the session. Supports IPv4 and IPv6. | Authorization |
customer_device.app_identifier | Identifier for the app the session was browsed on (for example, com.example.merchant). | Authorization |
customer_device.device_identifier | Identifier for the device the session was browsed on. | Authorization |
Shipping information
Each shipping object provides delivery details for the purchase. If the purchase contains multiple shipments with different recipients, provide one shipping object per shipment.
Required:
| Parameter | Description | Operations |
|---|---|---|
recipient.given_name | First name of the delivery recipient. | Authorization |
recipient.family_name | Last name of the delivery recipient. | Authorization |
address.street_address | Primary delivery street address. | Authorization |
address.city | Delivery city or town. | Authorization |
address.country | Two-letter country code in ISO 3166-1 alpha-2 format. | Authorization |
Highly recommended:
| Parameter | Description | Operations |
|---|---|---|
recipient.email | Email address of the delivery recipient. | Authorization |
recipient.phone | Phone number of the delivery recipient in local format. | Authorization |
address.postal_code | Delivery postal code. | Authorization |
address.region | Delivery state, county, province, or region. Mandatory for US and AU markets. ISO 3166-2 format. | Authorization |
shipping_option.shipping_type | Type of shipping selected by the customer. Allowed values: TO_DOOR, TO_CURB, TO_MAILBOX, PICKUP_BOX, PICKUP_POINT, PICKUP_STORE, PICKUP_WAREHOUSE, DIGITAL_EMAIL, DIGITAL_DOWNLOAD, DIGITAL_OTHER, PHYSICAL_OTHER. | Authorization |
shipping_option.shipping_carrier | Name of the company responsible for the delivery (for example, DHL). | Authorization |
Optional:
| Parameter | Description | Operations |
|---|---|---|
address.street_address2 | Additional delivery address details. | Authorization |
recipient.attention | Attention string for the delivery recipient. | Authorization |
shipping_option.shipping_type_attributes | Additional attributes for the shipping type: SIGNATURE_REQUIRED, IDENTIFICATION_REQUIRED, CONTACTLESS_DELIVERY, LEAVE_AT_DOOR, LEAVE_AT_CURB, LEAVE_WITH_NEIGHBOUR, EXPRESS, TRACKED, UNTRACKED. | Authorization |
shipping_reference | Unique reference linking this shipping object to specific line items. Required when the payment request contains multiple shipping objects. | Authorization |
Using klarna_network_data
Structure
The
klarna_network_data field is a serialized JSON string.Sample request
JSON
1
2
3
4
5
6
7
8
9
10
{
"content_type": "vnd.klarna.network-data.v2+json",
"content": {
"operation": "payment_request",
"request": {
"payment_request": {
"purchase_reference": "TRAIN-BKG-3321098",
"line_items": [
{
"name": "ICE Amsterdam-Frankfurt 1st Class",The JSON must include
"operation": "payment_request" and nest the data inside "request". Omitting these fields causes Klarna to silently reject the data without returning an error.For the full schema reference, including all supported fields and operations, see the Klarna Network Data Schema documentation.
documentation.Common klarna_network_data issues
| Issue | How to address it |
|---|---|
| Wrong content type | Use vnd.klarna.network-data.v2+json as the content type. An incorrect content type causes Klarna to silently ignore the data. |
| Missing operation field | The klarna_network_data JSON must include "operation": "payment_request" and nest data inside "request". Omitting these causes silent rejection. |
| Data not included in post-purchase calls | Include klarna_network_data in all API interactions (Payment Authorization, capture, refund) when using the passthrough mechanism. |
| Data not reaching Klarna | Test the full flow end-to-end — verify that data Partners submit through the Acquiring Partner actually reaches Klarna. Audit the data flow from the order management system → checkout → Acquiring Partner API to ensure no fields are dropped or truncated. |
API & SDK references