Data Types
Klarna API guidelines focus on data types like currencies (ISO 4217), amounts in minor units, strings, dates, locales, encoding, enums, and identifiers.
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.
String properties used for input MAY be validated to conform to the following Unicode groups. More details noted on API operations.
Control characters are always excluded from allowed input. Punctuations included in the allowed unicode block are permitted. Printable whitespace like space (U+0020) is allowed.
- Printable unicode
U+0000..U+10FFFF, excluding control characters (U+0000..U+001F, U+007F), line breaks/new lines (CR U+000D , LF U+000A), line separators (U+2028, U+2029) and TAB (U+0009).
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
| Feature | Open Enum | Closed Enum |
| Allowed Values | Predefined values plus other, potentially unknown, values. | Only the predefined, named values are allowed. |
| Adding New Values | 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. | Adding a new value is a breaking change and requires a specification update and client modifications. |
| Error Handling | Unknown 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:00Zrepresenting the 10th of August 2015 at 07:45:00 and the UTC timezone.2015-08-10T07:45:00.098Zrepresenting 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.