Skip to content

Klarna

Offer Klarna pay now, pay later and direct debit: set up your platform with Klarna once, then connect each merchant and test.

Ginger connects directly to Klarna, so your merchants can offer three Klarna payment methods:

Payment methodWhat the customer doesCapture
klarna-pay-nowPays straight awayAutomatic: the transaction is a sale
klarna-pay-laterPays later, after the goods arriveManual: the merchant captures when it ships
klarna-direct-debitPays by direct debit from a bank accountAutomatic: the transaction is a sale

This page shows how you set up your platform with Klarna once, how you connect a merchant, and how you test.

How it works

The customer chooses Klarna and goes to Klarna's payment page, where Klarna offers the option of the payment method and approves the customer. Klarna then informs Ginger of the result, and the transaction gets its final status.

  • Currency: Klarna on Ginger accepts EUR only.
  • Order lines: an order that offers klarna-pay-later needs order_lines, and the hosted payment page only shows pay later for an order with order lines. For pay now and direct debit, Ginger makes one order line from the description and amount of the order when it has none.
  • Capture: the merchant captures a pay later payment, in full or in parts. Pay now and direct debit can also run as a pre-authorisation. See Pre-authorizations in the payment acceptance docs.
  • Expiry: a pay now or pay later transaction expires after 48 hours when the customer doesn't finish it.

Set up your platform

You do this once, with Klarna and your Ginger contact.

Choose who has the agreement with Klarna

  • Your platform: you sign a commercial agreement with Klarna for your merchants. You need a licence to collect funds for your merchants.
  • Each merchant: the merchant signs its own agreement with Klarna, and Klarna pays the merchant directly.

Ask Klarna which agreement fits your business. Payment service providers can start from Klarna's introduction for acquiring partners.

Open your Klarna account

Open a Klarna account for your platform, also when your merchants have their own agreements: Ginger uses it to test Klarna on your platform. In the Klarna Merchant Portal, create API credentials, a username and a password, for live and for the playground, Klarna's test environment. See Authentication and Before you test in Klarna's docs.

Hand the credentials to Ginger

Pass the live and playground credentials to your Ginger contact through a secure channel. Ginger configures them for your platform and switches Klarna on: it's off unless you asked for it.

Ginger uses the playground credentials for test payments of projects that have none in their contract.

Connect a merchant

Allow the payment methods

Allow each Klarna payment method the merchant offers, in the base permissions of the merchant and in the permissions of the project: /payment-methods/klarna-pay-now/, /payment-methods/klarna-pay-later/ and /payment-methods/klarna-direct-debit/, with POST. Refunds use the same permission.

In the Admin portal, open the project, go to the Payment Methods tab and switch on Klarna Pay Now, Klarna Pay Later or Klarna Direct Debit.

Fill in the contract

Open Klarna on the Payment Method Contracts tab and fill in the merchant's Klarna API username and password. With its own agreement, the merchant creates them in the Klarna Merchant Portal. One contract covers the three payment methods.

With the Boarding API, set them as klarna_username and klarna_password in the klarna contract of the project. See Update a project contract in the API reference:

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/klarna/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{ "klarna_username": "<the merchant'\''s Klarna username>", "klarna_password": "<its Klarna password>" }'

A live project without the username or password refuses Klarna payments.

Test

A project in test mode (status active-testing) sends Klarna payments to the Klarna playground, Klarna's test environment. Without credentials in the contract, it uses your platform's playground account, so you can test before the merchant has its Klarna credentials.

Create an order with a Klarna transaction and order lines, and open its payment_url:

curl https://api.example.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 2500,
    "order_lines": [{
      "type": "physical",
      "name": "T-shirt",
      "quantity": 1,
      "amount": 2500,
      "vat_percentage": 2100,
      "currency": "EUR",
      "merchant_order_line_id": "1"
    }],
    "transactions": [{ "payment_method": "klarna-pay-later" }]
  }'

See Create an order in the payment acceptance docs. On Klarna's page, pay with Klarna's test data.

Refunds

The merchant refunds a Klarna payment with the standard refund request, in full or in parts: see Refunds.

Fees

With an agreement of your platform, Ginger imports Klarna's payouts to your platform and charges Klarna's fees to the merchant. The fees come in after the payment, so they can show up later than the transaction in the Admin portal.

Next steps