Girocheckout API

User Tools

Site Tools

Trace: • Klarna

Sidebar

Introduction

Integration

Basics

Apple Pay
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
WERO

Tools

Error codes
Result codes
Test data

SDK

PHP SDK
Java SDK
.NET SDK

Others

API Change log
Plugins Changelog

Imprint
Privacy policy
S-Public Services GmbH

Translations of this page:
en:girocheckout:klarna:start

Table of Contents

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

AUTHCAPTUREVOIDREFUND

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

SALEREFUND

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

CustomerShopGiroCheckoutProcessing CenterCustomerShopGiroCheckoutProcessing Center1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2025 by S-Management Service GmbH

  1. Buyer selects Klarna payment method
  2. Shop initiates Klarna transaction (Initialization)
  3. GiroCheckout initializes the transaction at the processing center
  4. Processing center transmits result to GiroCheckout
  5. Shop receives feedback on initialization outcome (if error, transaction is terminated)
  6. Shop sends redirect URL to customer browser
  7. Customer browser redirects to the processing center
  8. Processing center displays payment form
  9. Customer authorizes transaction
  10. Processing center processes transaction
  11. Processing center transmits result to GiroCheckout
  12. Notification: GiroCheckout notifies shop about transaction outcome (Notification)
  13. Notification: Shop processes transaction outcome
  14. Notification: Shop sends HTTP status code to GiroCheckout
  15. Customer clicks “Back to Shop” at the processing center or waits for automatic redirection (Redirect)
  16. 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.

  1. Initialize transaction
  2. Buyer fills out Klarna forms
  3. Notification of payment result to the merchant
  4. 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

ShopGiroCheckoutData CenterShopGiroCheckoutData Center1 2 3 4 (c)2025 by S-Management Service GmbH

  1. Shop sends a request with a referenced Klarna transaction
  2. GiroCheckout forwards the transaction to the data center
  3. Data center transmits the result to GiroCheckout
  4. 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

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 further information 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 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"}
en/girocheckout/klarna/start.txt · Last modified: 2025/10/08 02:11

Page Tools