Data Types

​​We maintain a consistent format for currencies, amounts, and dates across all Klarna APIs.

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 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).

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.

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

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

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, where:

• IDs: These are unique identifiers generated by Klarna. They are exposed through properties suffixed with _id. IDs are used to uniquely identify resources or entities within Klarna's systems.
• References: These are identifiers generated by partners. They are accepted through properties suffixed with _reference. References are used to link Klarna's systems with the partner's systems, allowing for seamless integration and tracking (1).

1. Source of Generation:#*IDs are generated by Klarna.
   • References are generated by the partner.
2. Purpose:
   • IDs are used internally within Klarna's systems to uniquely identify resources.
   • References are used to map or link Klarna's resources to the partner's systems.
3. Naming Convention:
   • IDs are suffixed with _id.
   • References are suffixed with _reference.
4. Use Cases:
   • IDs are critical for Klarna's internal operations and API functionalities.
   • References are essential for partners to track and manage transactions or resources in their own systems.

This distinction ensures clarity and proper mapping between Klarna's and the partner's systems, facilitating smooth integration and operations.

To ensure accurate correlation, reconciliation, and customer experience, Klarna supports the use of multiple reference types in its APIs. As an Acquiring Partner, correctly handling and mapping these references is essential for integrating with Klarna Payments and ensuring visibility across systems for you, your subpartners, and end-customers.

Klarna provides the following Partner References