Klarna

Klarna

Test Data

For testing Klarna, you do not need test data in the traditional sense. However, you do need an account with Klarna.

As a merchant, you must create an account with Klarna (and their test system – “Playground”) (see Klarna - Before you test). In the portal, you must then generate your Klarna API key via the corresponding section under “Settings”. The API username and password obtained there must be provided to GiroCheckout support, as this information is stored in our data center and is required for communication with Klarna.

All test transactions can be viewed in the Playground, where you can also generate test settlement files if needed.

During testing itself, you do not need any additional data.

Transaction Types

Detailed information on the transaction types.

Klarna allows:

Bookings (SALE), meaning direct payments without prior reservation.
Reservations (AUTH), also known as pre-authorization, to reserve an amount in advance and later book all or part of it.
Captures, meaning bookings on a previous reservation. Klarna allows multiple partial captures, but the total sum must not exceed the reserved amount. \ Example: Reservation for 20.00 EUR, 1 capture of 5.00 EUR, 1 further capture of 15.00 EUR. \ It is not necessary to book the full reserved amount. If there is a remaining balance, it can be released via a void.
Void or Reversal (also cancellation), allows releasing a reserved amount or remaining balance, making it available to the customer again. As shown in the Capture example, partial release of a reservation is possible.
Refund, allows refunding a booked amount or a partial amount to the customer. The total sum of partial refunds must not exceed the original booking amount. Reservations cannot be refunded, only canceled (= Void).

Reservation (AUTH)

A reservation is to be used when the actual fulfillment of an order takes place at a later time, but the order amount for the presented card (for credit card transactions) or the given account information (for Paydirekt payments and others) needs to be authorized beforehand at the time of the order. Once the reservation period has expired, the reservation is either booked or voided.

initial Transaction

SVG | PNG | TXT

Sale (SALE)

Use sale when the business case is complete, e.g. a shopping cart was offered, ordered and delivered to the customer. The customer's payment method is debited with the amount of the sale.

initial Transaction

SVG | PNG | TXT

Initialization of a Klarna Payment

A successful initialization generates a reference number and provides a redirect link to the merchant. The provided link leads to the payment form. The customer must be redirected to this URL, either via an HTTP redirect header, an HTML page with a corresponding meta tag, or JavaScript.

Provided by: GiroCheckout\ Called by: Merchant\

Workflow

SVG | PNG | TXT

Buyer selects Klarna payment method
Shop initiates Klarna transaction (Initialization)
GiroCheckout initializes the transaction at the processing center
Processing center transmits result to GiroCheckout
Shop receives feedback on initialization outcome (if error, transaction is terminated)
Shop sends redirect URL to customer browser
Customer browser redirects to the processing center
Processing center displays payment form
Customer authorizes transaction
Processing center processes transaction
Processing center transmits result to GiroCheckout
Notification: GiroCheckout notifies shop about transaction outcome (Notification)
Notification: Shop processes transaction outcome
Notification: Shop sends HTTP status code to GiroCheckout
Customer clicks “Back to Shop” at the processing center or waits for automatic redirection (Redirect)
GiroCheckout redirects customer back to the shop

API Functions

Overview

As seen in the workflow, there are various API calls during a Klarna transaction. The form the buyer fills out after being redirected to the processing center is provided and processed by Klarna and can change in content and flow depending on shop settings or buyer situation.

Initialize transaction
Buyer fills out Klarna forms
Notification of payment result to the merchant
Redirecting the buyer to the merchant’s site (triggered by buyer or automatically)

Reservation/Sale

POST Parameters

URL https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Name	Required	Type	Description
merchantId	Yes	Integer	Merchant ID of a Klarna project
projectId	Yes	Integer	Project ID of a Klarna project
merchantTxId	Yes	String(255)	Unique transaction ID of the merchant. Allowed characters: any letters (including special language characters), 0-9, characters & = + , : ; . _ ! ? # /. This information is transmitted by GiroCheckout to Klarna via the field merchant_information.merchant_data_1.
amount	Yes	Integer	For decimal currencies, specify the amount in the smallest currency unit, e.g., cents, pennies
currency	Yes	String(3)	Transaction currency, according to ISO 4217.\ EUR = Euro
purpose	Yes	String(40)	Purpose of the transaction. Since Klarna does not recognize this field, GiroCheckout stores the information under basket.soft_descriptor if no information is provided from the shop.
type	Optional	String(4)	Transaction type (see Transaction types) \ SALE = Sale is booked immediately (default) \ AUTH = Reservation of the amount
urlRedirect	Yes	String(2048)	URL to which the customer is redirected after payment.
urlNotify	Yes	String(2048)	URL to which the payment result is reported.
locale	Optional	String(4)	Language of the Klarna form \ de = German (default) \ en = English \ es = Spanish \ fr = French \ it = Italian \ ja = Japanese \ pt = Portuguese \ nl = Dutch \ cs = Czech \ sv = Swedish \ da = Danish \ pl = Polish
billingAddress	Optional	JSON-String	Optional field that can contain the buyer's billing address. The individual fields can be found in the list below.
shippingAddress	Optional	JSON-String	Optional field that can contain the buyer's shipping address. If this information is missing, the billing address will be used as the shipping address. The individual fields can be found in the list below.
customerInfo	Optional	JSON-String	Optional field that can contain additional information about the buyer. The individual fields can be found in the list below.
basket	Yes	JSON-String	Mandatory field that describes the shopping cart. The individual fields can be found in the list below.
kassenzeichen	Optional	String(255)	Optional field for passing a cash register identifier. This will be displayed in the GiroCockpit in the transaction details (and soon also exported) and can be searched for there. All UTF-8 characters are allowed.
hash	Yes	String(32)	HMAC MD5 hash over all values of the call. See generate hash.

JSON object for addresses

This object structure applies to both the billing address (`billingAddress`) and the shipping address (`shippingAddress`).

Name	Required	Type	Description
first_name	No	String(50)	First name of the billing recipient. Allowed are at least two characters consisting of letters (all languages), digits (not exclusively), spaces, the normal hyphen (-), apostrophe, period, as well as the symbols °, º, ª and ᵃ.
last_name	No	String(50)	Last name of the billing recipient. Same format rules as `first_name`.
title	No	String(20)	Apple Pay interprets title as the customer’s salutation (e.g., Mr, Ms, etc.). Allowed are titles up to 20 characters, starting with a letter (all languages), containing only letters/diacritics, spaces, the normal hyphen (-), apostrophe ('/’) and period; it must end with a letter or a period (no digits or other special characters, no leading/trailing separators).
email	No	String(254)	Email address of the billing recipient.
phone_contact	No	Object	Phone number of the billing recipient (see below).
company_name	No	String(60)	Company name, if the billing recipient is a company. Same format rules as `first_name`.
address_line_1	Yes	String(60)	Street and house number of the billing address. For all 3 street fields: allowed are at least two characters consisting of letters (all languages), digits, spaces, the normal hyphen, apostrophe and accent marks, quotation marks, comma, period, colon and semicolon, hash (#), ampersand (&), slash (/), parentheses, plus and at sign, as well as the symbols °, º, ᵃ, ª and underscore.
address_line_2	No	String(60)	Additional address line for the billing address (optional). Same format rules as `address_line_1`.
address_line_3	No	String(60)	Further additional address line for the billing address (optional). Same format rules as `address_line_1`.
postal_code	Yes	String(10)	Postal code of the billing address. Allowed are postal values with 2–10 characters that start and end with a letter or digit and in between may contain only letters, digits, spaces, hyphens, periods, or slashes.
city	Yes	String(50)	City of the billing address. Same format rules as the street fields.
state	No	String(50)	State/region of the billing address. Same format rules as the street fields.
country	Yes	String(2)	Two-letter country code (ISO 3166).

phone_contact object:

Name	Required	Type	Description
phone_type	No	String(10)	Type of phone number: `FAX`, `HOME`, `MOBILE`, `OTHER`, `PAGER`, `WORK`.
phone_number	No	String(20)	Phone number of the billing recipient. Allowed are phone numbers with an optional leading plus sign, followed by a digit 1–9 and up to 14 further digits, optionally grouped by spaces, hyphens, or parentheses, and an optional extension with “ext”, “x”, or “ext.” plus up to five digits.

JSON object customerInfo

Name	Required	Type	Description
customer_id	No	String(50)	Unique customer ID.
date_of_birth	No	String(10)	Customer’s date of birth in format `YYYY-MM-DD`.
gender	No	String(10)	Customer’s gender: `MALE`, `FEMALE`, `DIVERSE`.
title	No	String(100)	Apple Pay interprets title as the customer’s salutation (e.g., Mr, Ms, etc.). Format rules see `title` in addresses.
personal_identifications	No	Object	List of identification documents (see below).
contacts	No	Object, see phone_contacts above.	List of the customer’s contact options (see below).

contacts object:

Within the element `phone_contacts`, you can provide an array with multiple `phone_contact` elements (see above).

personal_identifications object:

You can provide an array with multiple elements using the following fields:

Name	Required	Type	Description
type	No	String(20)	Type of identification: `PASSPORT`, `NATIONAL`, `CPF`, `CNPJ`, `CURP`, `SSN`, `DRIVERS_LICENSE`.
id	No	String(26)	Customer’s identification number.
issued_by	No	String(50)	For `DRIVERS_LICENSE`: issuing administrative authority or region; for all others: country (ISO 3166-1 alpha-2 code).

JSON object basket

Name	Required	Type	Description
basket_id	Yes	String(140)	Unique identifier of the basket, e.g., “basket123456”. IDs consist of letters/digits and the separators space, normal hyphen (-), underscore (_), and period (.), must not begin or end with a separator, and must not contain double separators/spaces.
invoice_id	No	String(127)	External invoice number of the API caller. Same format rules as `basket_id`.
soft_descriptor	No	String(27)	Dynamic text shown on the buyer’s statement, e.g., “800-123-1234”. The purpose is stored here if the field is not used otherwise. Formatting rules therefore see purpose.
shipping_costs	see desc.	Object	Shipping costs of the basket (see below). This field is required if the `basket_type` is not “DIGITAL”.
basket_discount	No	Object	Discount on the entire basket (see below).
basket_type	Yes	String(10)	Type of basket: `DIGITAL`, `MIXED`, or `PHYSICAL`.

shipping_costs and basket_discount

Name	Required	Type	Description
amount	Yes	Integer	Amount in the smallest currency unit (e.g., cents).
currency	Yes	String(3)	Currency according to ISO 4217 (e.g., `EUR`).

basket_items list:

An array with the following fields:

Name	Required	Type	Description
name	Yes	String(127)	Item name, e.g., “A fine shirt”. Same format rules as `first_name` in address.
description	No	String(127)	Item description. Same format rules as `first_name` in address.
reference	No	String(64)	Item number, SKU, or another merchant reference. Same format rules as `basket_id`.
quantity	Yes	Object	Quantity and unit of the item (see below).
unit_price	Yes	Object	Price details for the item (see below).
item_discount	No	Object	Discounts for this item (see below).

quantity object:

Name	Required	Type	Description
quantity_amount	Yes	Integer	Number of purchased units.
quantity_unit	Yes	String(8)	Unit of measure of the item (e.g., `pcs`, `kg`).

unit_price object:

Name	Required	Type	Description
net	Yes	Integer	Net price of the item in the smallest currency unit.
gross	Yes	Integer	Gross price of the item in the smallest currency unit.
currency	Yes	String(3)	Currency according to ISO 4217 (e.g., `EUR`).
tax	Yes	Integer	Tax amount in the smallest currency unit or tax rate (with two decimal places).

item_discount object:

Name	Required	Type	Description
net	No	Integer	Discount excluding tax in the smallest currency unit.
gross	No	Integer	Discount including tax in the smallest currency unit.
currency	No	String(3)	Currency according to ISO 4217 (e.g., `EUR`).
tax	No	Integer	Tax amount in the smallest currency unit or tax rate.

Examples of the above structures

  basket:
  {
    "basket_id": "basket123456",
    "basket_type": "DIGITAL",
    "basket_items": [
      {
        "name": "Item 1",
        "quantity": {
          "quantity_amount": 3,
          "quantity_unit": "pcs"
        },
        "unit_price": {
          "net": 500,
          "gross": 600,
          "currency": "EUR",
          "tax": 2000
        }
      }
    ]
  }
  
  billing_address: 
  {
    "title": "Herr",
    "first_name": "Max",
    "last_name": "Mustermann",
    "company_name": "Acme GmbH",
    "email": "maxi.muster@example.com",
    "phone_contact": {
      "phone_type": "MOBILE",
      "phone_number": "+491701234567"
    },
    "address_line_1": "Mustergasse 123",
    "address_line_2": "Haus A",
    "address_line_3": "Wohnung 12",
    "postal_code": "88888",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE"
  }
  
  shipping_address: 
  {
    "title": "Herr",
    "first_name": "Max",
    "last_name": "Mustermann",
    "company_name": "Acme GmbH",
    "email": "maxi.muster@example.com",
    "phone_contact": {
      "phone_type": "HOME",
      "phone_number": "+49755283492987"
    },
    "address_line_1": "Musterstr. 1a",
    "postal_code": "88888",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE"
  }
  
  customer_information: 
  {
    "customer_id": "CUST123456",
    "date_of_birth": "1985-06-15",
    "gender": "MALE",
    "title": "Herr",
    "personal_identifications": [
      {
        "type": "PASSPORT",
        "id": "A1234567",
        "issued_by": "DE"
      },
      {
        "type": "DRIVERS_LICENSE",
        "id": "DL78901234",
        "issued_by": "Bayrisches Verkehrsministerium"
      }
    ],
    "contacts": {
      "phone_contacts": [
        {
          "phone_type": "HOME",
          "phone_number": "+442071838750"
        }
      ]
    }
  }
}

Example of a Transaction Initialization

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=1000" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "basket={\"basket_items\":[{\"name\":\"Item 1\",\"quantity\":{\"quantity_amount\":1,\"quantity_unit\":\"pcs\"},\"unit_price\":{\"net\":1000,\"gross\":1200,\"currency\":\"EUR\",\"tax\":2000}}]}" \
     -d "urlRedirect=http://www.my-domain.de/klarna/redirect" \
     -d "urlNotify=http://www.my-domain.de/klarna/notify" \
     -d "hash=2ddc45c15307201dca8a50a094c70ab9" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Response

The response consists of a JSON object. The field `rc` returns an error code. If `rc = 0` is returned, the transaction was successfully initialized. You will receive a transaction number and the redirectURL to the Klarna form as a response.

Parameters

Name	Mandatory	Type	Description
rc	Yes	Integer	Error number
msg	Yes	String(255)	Additional information in case of an error
reference	Optional	String(36)	Unique GiroCheckout transaction ID
redirect	Optional	String(2048)	Redirect URL to forward the customer to their online banking
HEADER Parameters
hash	Yes	String(32)	HMAC MD5 hash over all values of the response. See hash of the response

Example in Case of Success

{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}

Example in Case of Failure

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Notification of Payment Outcome

The outcome of a payment is transmitted to the URL specified in the urlNotify parameter. This notification serves to inform the merchant of the transaction outcome. This information can be used to update the transaction status on the merchant's side.

The payment outcome of a transaction is stored in the `gcResultPayment` field.

Request

URL: notifyUrl from the transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters

Name	Mandatory	Type	Description
gcReference	Yes	String(36)	GiroCheckout transaction ID
gcMerchantTxId	Yes	String(255)	Merchant transaction ID
gcBackendTxId	Yes	String(22)	Payment processor transaction ID
gcAmount	Yes	Integer	For decimal currencies, specify the amount in the smallest currency unit, e.g., cents, pennies
gcCurrency	Yes	String(3)	Currency
gcResultPayment	Yes	Integer	Payment result codes
gcHash	Yes	String(32)	HMAC MD5 hash over all values of the call. See generate hash

Response

One of the following HTTP status codes is expected as a response to the GET request.

HTTP Statuscode	Description
200 (OK)	The notification was processed correctly.
400 (Bad Request)	The merchant did not process the notification and does not wish to be notified again.
All others	The notification will be repeated up to 10 times every 30 minutes until the merchant returns HTTP status code 200 or 400.

Redirecting the Customer Back to the Merchant

After completing the payment, the customer can return to the merchant via a link. Redirection occurs only when the buyer clicks the “Cancel” or “Back to Shop” button or automatically after a few seconds.

Request

URL: redirectUrl from the transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters

Name	Mandatory	Type	Description
gcReference	Yes	String(36)	GiroCheckout transaction ID
gcMerchantTxId	Yes	String(255)	Merchant transaction ID
gcBackendTxId	Yes	String(22)	Payment processor transaction ID
gcAmount	Yes	Integer	For decimal currencies, specify the amount in the smallest currency unit, e.g., cents, pennies
gcCurrency	Yes	String(3)	Currency
gcResultPayment	Yes	Integer	Payment result
gcHash	Yes	String(32)	HMAC MD5 hash over all values of the call. See generate hash

Additional Transaction Types

These transactions reference a previously completed transaction. The transaction is based on server-to-server communication and does not require customer action (data entry).

Provided by: GiroCheckout
Called by: Merchant

Workflow

SVG | PNG | TXT

Shop sends a request with a referenced Klarna transaction
GiroCheckout forwards the transaction to the data center
Data center transmits the result to GiroCheckout
Shop receives direct feedback on the transaction outcome (no notification)

Booking (CAPTURE)

Beim Buchen (capture) wird das Kundenkonto mit einem Betrag belastet, die Gutschrift erfolgt auf das Händlerkonto. Dieses Modell setzt voraus, dass der zugrundeliegende Geschäftsvorfall abgeschlossen ist, z.B. wurde ein Warenkorb angeboten, bestellt und an den Kunden ausgeliefert.

Bedingung: nur reservierte Transaktionen können gebucht werden
Betrag ⇐ Reservierungsbetrag
Buchung von Teilbeträgen möglich

Refund (REFUND)

Eine Erstattung ist zu verwenden, wenn dem Kunden eine vorangegangene Zahlung komplett oder teilweise erstattet werden soll.

Bedingung: kann nur auf folgende Transaktionstypen angewendet werden:
- Buchung (capture)
- Reservierung + Buchung (sale)
Betrag ⇐ Transaktionsbetrag der vormals gesendeten Transaktion

Cancellation (VOID)

Stornieren ist zu verwenden, wenn eine akzeptierte Transaktion nicht ausgeführt werden soll.

Bedingung: kann nur auf folgende Transaktionstypen angewendet werden:
- Reservierung (solange keine Buchung erfolgte und Reservierung nicht abgelaufen ist)
- Reservierung/Buchung (nur am selben Tag)
- Erstattung (nur am selben Tag)

POST Parameters

URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund
URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Name	Mandatory	Type	Description
merchantId	Yes	Integer	Merchant ID of a Klarna project
projectId	Yes	Integer	Project ID of a Klarna project
merchantTxId	Yes	String(255)	Unique transaction ID of the merchant. Allowed characters: any letters (including language-specific special characters), 0-9, characters & = + , : ; . _ ! ? # /
amount	Yes (optional for Void)	Integer	For decimal currencies, specify the amount in the smallest currency unit, e.g., cents, pennies
currency	Yes (optional for Void)	String(3)	Currency of the transaction, according to ISO 4217. EUR = Euro
purpose	Optional	String(27)	Purpose of the refund or capture. Since Klarna does not know this field, GiroCheckout stores the information under `basket.soft_descriptor` if no information is provided by the shop.
reference	Yes	String(36)	GiroCheckout transaction ID for which a booking or refund is to be performed
kassenzeichen	Optional	String(255)	Optional field for passing a cash register identifier. This will be displayed in the GiroCockpit in the transaction details (and soon also exported) and can be searched for there.
basket	Optional	JSON-String	Optional field that describes the shopping cart. The individual fields can be found in the list above.
shippingInfo	Optional	JSON-String	Optional field that provides shipping information. The individual fields can be found in the list below.
hash	Yes	String(32)	HMAC MD5 hash over all values of the call. See generate hash

JSON Object shippingInfo

Name	Required	Type	Description
shipping_company	No	String	Name of the shipping company (as specific as possible).
shipping_method	No	String	Shipping method (e.g., PickUpStore, Home, Postal).
tracking_number	No	String	Tracking number for the shipment.
tracking_uri	No	String	URL for shipment tracking for the customer.
return_shipping_company	No	String	Name of the shipping company for returns.
return_tracking_number	No	String	Tracking number for the return shipment.
shipping_delay	No	Integer	Delay (in days) before shipping the order.

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

Response

Parameters

Name	Mandatory	Type	Description
rc	Yes	Integer	Error number
msg	Yes	String(255)	Additional information in case of an error
reference	Yes	String(36)	GiroCheckout transaction ID
referenceParent	Yes	String(36)	GiroCheckout transaction ID of the underlying original transaction
merchantTxId	Yes	String(255)	Merchant transaction ID
backendTxId	Yes	String(22)	Payment processor transaction ID
amount	Yes	Integer	For decimal currencies, specify the amount in the smallest currency unit, e.g., cents, pennies
currency	Yes	String(3)	Currency
resultPayment	Yes	Integer	Transaction result
hash	Yes	String(32)	HMAC MD5 hash over all values of the call. See generate hash

Example in Case of Success

{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/de_DE/R.po?n=iNJGcJ4M2LZASZ-swXO5urRQntxOxb92NFiITsP60GcIhP","rc":"0","msg":""}

Example in Case of Failure

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Table of Contents

Klarna

Test Data

Transaction Types

Reservation (AUTH)

Sale (SALE)

Initialization of a Klarna Payment

Workflow

API Functions

Overview

Reservation/Sale

POST Parameters

JSON object for addresses

JSON object customerInfo

JSON object basket

Examples of the above structures

Example of a Transaction Initialization

Response

Parameters

Example in Case of Success

Example in Case of Failure

Notification of Payment Outcome

Request

GET Parameters

Response

Redirecting the Customer Back to the Merchant

Request

GET Parameters

Additional Transaction Types

Workflow

Booking (CAPTURE)

Refund (REFUND)

Cancellation (VOID)

POST Parameters

JSON Object shippingInfo

Example

Response

Parameters

Example in Case of Success

Example in Case of Failure