Data Types

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.

{
  "purchase_currency": "USD"
}

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.

{
  "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

colspan="undefined" Feature	colspan="undefined" Open Enum	colspan="undefined" Closed Enum
colspan="undefined" Allowed Values	colspan="undefined" Predefined values plus other, potentially unknown, values.	colspan="undefined" Only the predefined, named values are allowed.
colspan="undefined" Adding New Values	colspan="undefined" Adding a new value is a non-breaking change; it only requires an out-of-band agreement by the endpoints that need to use it.	colspan="undefined" Adding a new value is a breaking change and requires a specification update and client modifications.
colspan="undefined" Error Handling	colspan="undefined" Unknown values are parsed and typically stored as their raw value (e.g., as an integer or string).	colspan="undefined" 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.

{
  "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.