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

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\

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

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)

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

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

phone_contact Object:

contacts Object:

Here, an array with multiple elements can be specified in the phone_contacts object with the following fields:

personal_identifications Object:

Here, an array with multiple elements can be specified with the following fields:

shipping_costs and basket_discount

basket_items List:

An array with the following fields:

quantity Object:

unit_price Object:

item_discount Object:

  basket:
  {
    "basket_id": "basket123456",
    "basket_type": "PHYSICAL",
    "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": "Mr.",
    "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": "Mr.",
    "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": "Mr.",
    "personal_identifications": [
      {
        "type": "PASSPORT",
        "id": "A1234567",
        "issued_by": "DE"
      },
      {
        "type": "DRIVERS_LICENSE",
        "id": "DL78901234",
        "issued_by": "Bavarian Ministry of Transport"
      }
    ],
    "contacts": {
      "phone_contacts": [
        {
          "phone_type": "HOME",
          "phone_number": "+442071838750"
        }
      ]
    }
  }
}

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.

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.

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

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

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.

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

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

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)

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

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.