For PartnersFor Acquiring Partners
Klarna

Data Types

Explore Klarna's approach to ensuring consistency in data representation. Our guide covers standards for currencies, amounts, dates, and more, tailored for seamless integration.
We maintain a consistent format for currencies, amounts, and dates across all Klarna APIs.

Currency
We use the ISO 4217 standard for defining currencies. Examples are USD, GBP, EUR or SEK.
JSON
1 2 3 4
{ "purchase_currency": "USD" }

Amount
We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.
JSON
1 2 3 4
{ "order_amount": 1000 }

Strings
Strings may be up to 255 characters, unless otherwise noted in the field description.
Strings must not contain HTML, CSS or JavaScript. Requests containing such elements MAY be rejected.

Enums
Enums are expressed with two ways, as open- or closed-enums.

Open Enums
An open enum is an enumeration type that allows for values beyond the explicitly defined, named options. This contrasts with a traditional "closed" enum, where a variable is strictly limited to one of the predefined values. Open enums are designed to handle future changes without requiring immediate updates to all systems that use them.
This means integrations must expect more values to be added to the enum over time. Such changes are categorized as non-breaking changes.
Open enums are always in lower_snake_case unless otherwise stated.

Open vs. Closed Enums
FeatureOpen EnumClosed Enum
Allowed ValuesPredefined values plus other, potentially unknown, values.Only the predefined, named values are allowed.
Adding New ValuesAdding a new value is a non-breaking change; it only requires an out-of-band agreement by the endpoints that need to use it.Adding a new value is a breaking change and requires a specification update and client modifications.
Error HandlingUnknown values are parsed and typically stored as their raw value (e.g., as an integer or string).Unknown values often result in a parsing error or are stored in an "unknown field" set.

Closed Enums
Closed Enums are actual OpenAPI Enums that are called Closed Enums to differentiate from Open enums.
Closed enums are always in UPPER_SNAKE_CASE unless otherwise stated.
Closed enums are final. Adding, removing or renaming enum-values are identified as breaking changes, and can not happen within same version.

Dates
Dates are expressed according to the ISO 8601 standard with combined date, time and timezone. The exception to this are date_of_birth fields where we accept values in the YYYY-MM-DD format.
Examples
  • 2015-08-10T07:45:00Z representing the 10th of August 2015 at 07:45:00 and the UTC timezone.
  • 2015-08-10T07:45:00.098Z representing the 10th of August 2015 at 07:45:00, with fractional seconds 98 (98 milliseconds) and the UTC timezone.

Locale and Country
Locales should be formatted as a language tag consisting of a two-letter language code combined with a two-letter country code according to RFC 5646. Examples are en-us for US English, en-gb for British English and sv-se for Swedish (in Sweden).
Countries are handled as two-letter country codes according to ISO 3166 alpha-2. Examples are us for the United States, gb for Great Britain and se for Sweden.
JSON
1 2 3 4 5
{ "locale": "en-US", "purchase_country": "US" }

Encoding
We expect all data that is sent to Klarna’s APIs to be UTF-8 encoded.

Identifiers
Only identifiers generated by Klarna will be exposed through properties suffixed with _id. Identifiers generated by Partners will be accepted through properties suffixed with _reference.