The Instant Finance Authorization API is called for orders paid by Klarna credit. The webstore makes this auth API call after the webstore has received credit approval from Klarna. For more information on the Klarna payment workflow, see Klarna Integration.

URI Summary

Action

URI Template

URI Example

Non-URI Request

Response

POST

/v[M.m]/stores/[StoreID]/ payments/instantfinance/auth/ [TenderCode].[format]

/v1.0/stores/store123/ payments/instantfinance/auth/KL.xml

XML

200 + XML response

Schema

The schema for Instant Finance Authorization is Payment-Service-InstantFinanceAuth-1.0.xsd.

Request Examples

The request is an InstantFinanceAuthRequest message. Click each header below to view the example XML.

 

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.

TaxAmount

Yes

Total tax amount on the order

String

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

TaxAmount/ @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.

BillingPersonName

Yes

Billing Name of customer

ComplexType

 

BillingPersonName/FirstName

Yes

First name of the person on the billing address

String

Max 64 characters

BillingPersonName/LastName

Yes

Last name of the person on the billing address

String

Max 64 characters

BillingAddress

Yes

Billing address of customer

ComplexType

 

BillingAddress/ Line1

Yes

Line# components of the street address and, if necessary, suite and building identifiers for the physical address. Line1 is required.

Line2, Line3, and Line4 are optional. Include them only if the data exists. A blank AddressLine element will fail validation.

String

1 to 70 characters.

BillingAddress/ Line2

No

String

1 to 70 characters.

BillingAddress/ Line3

No

String

1 to 70 characters.

BillingAddress/ Line4

No

String

1 to 70 characters.

BillingAddress/ City

Yes

Name of the city

String

Max 40 characters

BillingAddress/ MainDivision

Yes

Two- or three-digit postal abbreviation for the state or province. The ISO 3166-2 code is recommended, but not required. See http://en.wikipedia.org/wiki/ISO_3166-2.

String

Max 30 characters

BillingAddress/ CountryCode

Yes

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

String

2 characters

BillingAddress/  PostalCode

Depends on country. Yes for US and Canada

String of letters and/or numbers that specifies the delivery area more closely than the city alone (for example, US ZIP code)

String

Max 30 characters

ShippingPersonName

No

 

ComplexType

 

ShippingPersonName /FirstName

Yes

First name of the person on the first/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors.

String

64 characters.

ShippingPersonName /LastName

Yes

Last name of the person on the first/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors.

String

Max 64 characters.

ShippingAddress

No

First/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors.

ComplexType

 

ShippingAddress/ Line1

Yes

Line# components of the street address and, if necessary, suite and building identifiers for the physical address. Line1 is required.

Line2, Line3, and Line4 are optional. Include them only if the data exists. A blank AddressLine element will fail validation.

String

1 to 70 characters.

ShippingAddress/ Line2

No

String

1 to 70 characters.

ShippingAddress/ Line3

No

String

1 to 70 characters.

ShippingAddress/ Line4

No

String

1 to 70 characters.

ShippingAddress/ City

Yes

Name of the city

String

Max 40 characters

ShippingAddress/ MainDivision

Yes

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

String

Max 30 characters

ShippingAddress/ CountryCode

Yes

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

String

2 characters

ShippingAddress/ PostalCode

Varies based on country. Yes for US/Canada

String of letters and/or numbers that specifies the delivery area more closely than the city alone (for example, U.S. ZIP code)

String

Max 30 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

AuthorizationToken

Yes

String of letters and/or numbers which is used for authorizing transaction. This is the authorization token returned from the Radial.klarnaAuthorize() javascript call in the webstore.

String

Max 36 Characters

CustomerEmailAddress

Yes

Email address of the customer who is making the purchase. Used for realtime fraud checking by our API and payment processors.

String

Max 70 characters

CustomerPhoneNumber

Yes

Phone number of the person on the first/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors.

String

Max 15 characters.

LocaleCode

Yes

Locale code used to identify specific language & geographic region

String

 

OrderLines

Yes

 

ComplexType

 

OrderLines/LineItem

No

Represents Single line item in the order

Complex Type

Includes:item level details. 

OrderLines/LineItem/ ImageUrl

Yes

Image URL of the product that is added to bag

String

 

OrderLines/LineItem/ ProductCategory No Name of the category from which the user navigated to the product page String  

OrderLines/LineItem/ ProductName

Yes

Product name

String

 

OrderLines/LineItem/ ProductUrl

Yes

Webstore URL of Product Detail Page

String

 

OrderLines/LineItem/ ItemIdentifier

Yes

Stock keeping unit (SKU) of the item added to cart

String

 

OrderLines/LineItem/ LineItemName

Yes

Name associated with the SKU

String

 

OrderLines/LineItem/ Quantity

Yes

Line item quantity

Integer

OrderLines/LineItem/ QuantityUnit

Yes

Unit used to describe the quantity. Example: KG, PCS

String

1-8 characters

OrderLines/LineItem/ TaxRate

Yes

Non-negative. In percent, two implicit decimals. Example: 2500 = 25%.

Integer

 

OrderLines/LineItem/ TotalAmount

Yes

Includes tax and discount. Must match (quantity unit_price) - total_discount_amount within �quantity. (max value: 100000000)

Integer

 

OrderLines/LineItem/ TotalDiscountAmount

Yes

Non-negative minor units. Includes tax.

Integer

 

OrderLines/LineItem/ TotalTaxAmount

Yes

Must be within �1 of total_amount - total_amount 10000 / (10000 + tax_rate). Negative when type is discount.

Integer

 

OrderLines/LineItem/ UnitPrice

Yes

Minor units. Includes tax, excludes discount. (max value: 100000000)

Integer

 

OrderLines/LineItem/ DeliveryType

Yes

Order line Delivery type.

String

 

SchemaVersion

Yes

 

 

String

pattern = "([0-9]+\.)*[0-9]+". Value Example: 1.1, 1.2

requestId

Yes

RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout.

String

Up to 40 Characters.

Response Examples

The response is a InstantFinanceAuthReply message. Click each header below to view the example XML.

Response Elements

Element

Required

Description

Type

Restriction

Element

Required

Description

Type

Restriction

PaymentContext

Yes

Unique identifier of the payment transaction for the order

ComplexType

PaymentContext/ 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

PaymentContext/ TenderType

Yes

Payment mode tender used to place the transaction

String

 

ExtendedResponseCode

Yes (Failure scenario)

Detailed description of transaction failure. See table below for examples of failure scenarios and the corresponding ExtendedResponseCode values.

String

 

ResponseCode

Yes

Response code of the Klarna authorization. Contains ‘Success’ or ‘Fail’ or 'Timeout’.

 

String

 

In case of failure or timeout

Failure can happen because of order data mismatch or because the session timed out. Timeouts can happen because of connectivity issues. In both cases, the webstore must message the customer about the error (error detail will be available in the ExtendedResponseCode field) and redirect the customer to the payment page to complete the checkout. The checkout will be considered a fresh one at this point, with the webstore getting a fresh nonce, invoking the Radial.klarnaSetup() js method again, and following the regular checkout flow from there on forward.

Extended Response Code values

Scenario

Extended Response Code

Action to be taken

Order amount was updated, but no Radial.klarnaReauthorize call was made.  Instance Finance Auth request was attempted with original authorization token.

BAD_VALUE Not matching fields: [order_amount, order_lines[0].total_amount]

Webstore needs to code for calling Radial.klarnaReauthorize() whenever order is updated after initial authorization.

Wrong authorization token passed in InstantFinanceAuthRequest call

NOT_FOUND Invalid authorization token

Webstore needs to ensure that the authorization token provided in the Radial.klarnaAuthorize() or Radial.klarnaReauthorize() call are used in the InstantFinanceAuthRequest.  If any other stray value is used or if the token is altered in anyway, then this error will be returned.

Klarna server has an internal issue

INTERNAL_SERVER_ERROR

Webstore can retry the auth request again.  Retries can be attempted a configured number of times prior to requesting user to choose an alternate payment method.

Klarna Service is unavailable

SERVICE_UNAVAILABLE Purchase failed because of a temporary internal Klarna error.

Webstore can retry the auth request again.  Retries can be attempted a configured number of times prior to requesting user to choose an alternate payment method.