Radial offers server-to-server APIs for managing Klarna authorization sessions. These APIs are an alternative to the Javascript implementation and are appropriate for solutions such as mobile apps.

Session Data

Session data is managed with the InitializePaymentAuthorizationRequest message. This message is used both to create the initial session and to update the session details as user or order details change.

URI Summary

Action

URI Template

URI Example

Request Type

Response

POST

/v[M.m]/stores/[StoreID]/payments/authorization/initialize/[TenderCode].[format]

/v1.0/stores/TMSUS/payments/authorization/initialize/KL.xml

XML

200 + XML response

Schema

The schema for InitializePaymentAuthorizationRequest is Payment-Service-InitializePaymentAuthorization-1.0.xsd.

Session Creation

The first call must be made to create a new session.

Request to Create a Session

In the initial request the locale and IP address of the end user must be provided, along with the order ID and current order total.

Request Elements

Element

Required

Description

Type

Restriction

OrderId

Yes

Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service.

String

Max 20 characters

Amount

Yes

Currency amount being authorized on the credit card.

String

Positive decimal, up to two decimal places (for example, 4.75).

Note that an explicit decimal point is used for currency amounts in this API, which differs from the currency formatting in Klarna JSON objects.

Amount/ @currencyCode

Yes

Type of currency used for the order.

String

3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

OriginatorIpAddress

Yes

An IP version 4 or version 6 address.

String

Max 39 characters

LocaleCode

Yes

Locale code for the user's language in combination with a country.

String

Cannot be empty. (Minimum of 1 character). Example: en_US

Session Creation Reply

When the initial session is created a reply will be returned which includes the payment ID as well as configuration required for the Klarna provided widget. The payment ID must be saved for use in subsequent operations. The configuration information must be provided to the klarna widget in the format requried by the widget.

Reply Elements

Element

Description

Type

PaymentContext/OrderId

The order ID passed in the request

String

PaymentContext/TenderType

Always "KL" (Klarna)

String

ResponseCode

One of Success, Failure, or Timeout

String

ResponseCodeDescription

If the response code is Failure this will contain details for the failure.

String

PaymentId

The unique identifier for the created session. This must be used for subsequent calls.

String

KlarnaSessionConfiguration/ClientToken

The token which must be passed to the Klarna provided UI widget.

String

KlarnaSessionConfiguration/ProductCategory/Id

The identifier of the klarna payment product category. Maps to the Klarna javascript object identifier

String

KlarnaSessionConfiguration/ProductCategory/Name

A descriptive name of the payment product category. Maps to the Klarna javascript object name

String

KlarnaSessionConfiguration/ProductCategory/StandardURL

URL for the standard asset of the payment product category. Maps to the Klarna javascript object asset_urls.standard

String

KlarnaSessionConfiguration/ProductCategory/DescriptiveURL

URL for the descriptive asset of the payment product category. Maps to the Klarna javascript object asset_urls.descriptive

String

Amount

The order amount associated with the created session. Will be zero if the response code is Failure or Timeout.

Decimal

Amount@currencyCode

The currency code associated with the created session.

3-character ISO 4217 code

Session Update

Session Update Request

After the end user provides additional details (i.e. billing and shipping information) or the order is updated an additional call must be made to update the session with the most recent information. This call must be made if any information about the order has changed prior to displaying the Klarna widget to the end user. The payment ID returned from the initial call must be passed as the payment id to be corrected.

Additionally the session must be updated after any customer or order information has been updated prior to performing the klarna widget authorization. This includes any changes such as automated address corrections.

Request Elements

Element

Optional/Required

Description

Type

Restriction

OrderId

Required

Unique identifier for an order across all transactions of the same order

String

1-20 characters

Amount

Required

Total value of the authorization. When line items are specified must match the sum of the inidividual line item total amounts

Decimal

Min 0.00
Max 9 digits
Fraction 2 digits

Amount@currencyCode

Required

The currency of the order amount

ISO 4217 currency code

RedirectUrl

Required for final update

URL of the merchant confirmation page. The consumer will be redirected back to the confirmation page if the consumer is sent to the redirect URL after placing the order. Insert {session.id} and/or {order.id} as placeholder to connect either of those IDs

String

1-500 characters

BillingInformation

Required for final update

Represents Billing Information of the order. Contains Customer Information and Address.

ComplexType

BillingInformation/ContactInformation/Person/Name/LastName

Required

The Last Name of the customer placing the order.

String

Min 1 Character

BillingInformation/ContactInformation/Person/Name/FirstName

Required

The First Name of the customer placing the order.

String

Min 1 Character

BillingInformation/ContactInformation/PrimaryPhoneNumber

Required

Customer phone number used for order follow-up.

String

6-16 numbers

BillingInformation
/ContactInformation/PrimaryEmailAddress

Required

Email address of the customer.

String

6-60 characters

BillingInformation/Address/Line1

Required

The Line1 components contain the street address.

String

Min 1 character

BillingInformation/Address/Line2

Optional

Address Line 2 of the Billing Address.

String

Min 1 character

BillingInformation/Address/City

Required

City of the Billing Address.

String

Min 1 character

BillingInformation/Address/MainDivision

Required

Typically, a two- or three-digit postal abbreviation for the state or province.
This does not necessarily conform to the ISO 3166-2 code.

String

Max 30 characters

BillingInformation/Address/CountryCode

Required

Two-digit ISO country code conforming to ISO 3166 alpha 2.
See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

String

Min 2 characters
Max 2 characters

BillingInformation/Address/PostalCode

Required

Postal code of the Billing Address.

String

3-10 characters

ShippingInformation

Optional

Represents Shipping Information of the order. Contains Customer Information and Address.

ComplexType

ShippingInformation/ContactInformation/Person/Name/LastName

Required

Last name of the customer for shipment.

String

Min 1 Character

ShippingInformation/ContactInformation/Person/Name/FirstName

Required

First name of the customer for shipment.

String

Min 1 Character

ShippingInformation/ContactInformation/PrimaryPhoneNumber

Required

Customer phone number used for order follow-up.

String

6-16 numbers

ShippingInformation/ContactInformation/PrimaryEmailAddress

Required

Email address used for sending automated email receipts.

String

6-60 characters

ShippingInformation/Address/Line1

Required

The "Line1" components contain the street address.

String

Min 1 character

ShippingInformation/Address/Line2

Optional

Address Line 2 of the Shipping Address

String

Min 1 character

ShippingInformation/Address/City

Required

City of the Shipping Address.

String

Min 1 character

ShippingInformation/Address/MainDivision

Required

Typically, a two- or three-digit postal abbreviation for the state or province.
This does not necessarily conform to the ISO 3166-2 code.

String

Max 30 characters

ShippingInformation/Address/CountryCode

Required

Two-digit ISO country code conforming to ISO 3166 alpha 2.
See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

String

2 characters

ShippingInformation/Address/PostalCode

Required

Postal code of the Shipping Address.

String

3-10 characters

DeliveryInformation

Optional

Represents Delivery Information of the store order. Contains pickup person information, store address and delivery method

ComplexType

DeliveryInformation/ConsigneeInformation

Optional

Represents details about pickup person information.

ComplexType

DeliveryInformation/ConsigneeInformation/Person/Name/LastName

Required

Last name of the person designated to pick up delivery.

String

Min 1 Character

DeliveryInformation/ConsigneeInformation/Person/Name/FirstName

Required

First name of the person designated to pick up delivery.

String

Min 1 Character

DeliveryInformation/Address/Line1

Required

The "Line1" components contain the street address.

String

Min 1 character

DeliveryInformation/Address/Line2

Optional

Address Line 2 of the store address

String

Min 1 character

DeliveryInformation/Address/City

Required

City of the store address.

String

Min 1 character

DeliveryInformation/Address/MainDivision

Required

Typically, a two- or three-digit postal abbreviation for the state or province.
This does not necessarily conform to the ISO 3166-2 code.

String

Max 30 characters

DeliveryInformation/Address/CountryCode

Required

Two-digit ISO country code conforming to ISO 3166 alpha 2.
See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

String

2 characters

DeliveryInformation/Address/PostalCode

Required

Postal code of the store address.

String

3-10 characters

DeliveryMethod

Optional

Delivery type of the order.

String

Enum values: STANDARD, EXPRESS, SAME_DAY, OVERNIGHT, ELECTRONIC_DELIVERY, SHIP_TO_STORE

OriginatorIpAddress

Required

An IP version 4 or version 6 address.

String

Max 39 characters

LineItems

Required for updates.

Sequence of LineItem.

Complex Type

LineItems/LineItemsTotal

Required

Total amount for all line items. Must be equal to the sum of individual line item total amounts.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/ShippingTotal

Required

Total shipping amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/TaxTotal

Required

Total tax amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount. For NA sessions this must be the amount of the sales_tax type line item. For EU sessions this must be the sum of the line item tax total amounts.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/LineItem/Name

Required

Display name of the product

String

LineItems/LineItem/ProductInformation

Optional

Descriptive information about the product.

String

LineItems/LineItem/ProductInformation/Url

Optional

URL for the product

URL

LineItems/LineItem/ProductInformation/ImageUrl

Optional

URL to an image of the product

URL

LineItems/LineItem/ProductInformation/Type

Optional

The type of the item. For NA sessions this should have a value of "sales_tax" for the tax line item.

sales_tax

LineItems/LineItem/SkuId

Optional

The SKU of the product.

String

LineItems/LineItem/Tax

Required for EU Sessions

Tax information for the line item.

Complex type

LineItems/LineItem/Tax/TotalAmount

Required

The total tax for the line item. This must be equal to (Total Amount * Rate / 100) / (1 + Rate / 100).

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Tax/Rate

Required

The tax rate charged for the item as a percentage e.g. 12.6.

decimal

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Discount/TotalAmount

Optional

The discount applied to the total cost of the item. Includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/TotalAmount

Required

The total amount for the line item. Must equal (unit amount * quantity) - discount. Includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Quantity

Required

The number of units of product.

integer

LineItems/LineItem/QuantityUnit

Optional

The units of product.

string

1-8 characters

LineItems/LineItem/UnitAmount

Required

The value of a single unit of product, includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LocaleCode

Required

The locale of the end user in RFC 1766 format e.g. en-US.

string

PaymentIdToBeCorrected

Required for updates

The payment id from the initial call to create the session which will be updated.

string

Timeouts

If a timeout occurs while waiting for a response or the response code is "Timeout" the request should be retried.

Failure

If a response code of failure is returned an error message should be displayed to the user stating that Klarna payments are currently unavailable.

Canceling an authorization

If for any reason an order is changed after the Klarna widget authorization is performed, that authorization must be cancelled and the session must be updated and reauthorized.

It is strongly recommended that Klarna widget authorization is not performed until after the customer has performed all review and accepted the order so that canceling an authorization is not required.

If the authorization needs to be canceled for any reason, then please send PaymentAuthCancelRequest message including the authorization token obtained as a reference transaction ID. See the documentation for the Authorization Cancel API.