menu

Payment API

What's on this page

Online Payments / Payment Methods / Klarna

Klarna

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Selected few ✓ ✓

Klarna is limited to the following countries: Germany, United Kingdom, Canada, Spain, Australia, Romenia, Czech Republic, Greece, Italy, Finland, France, Poland, Sweden, United States, Norway, Austria, Netherlands, Switserland, Belgium, Denmark, Portugal, Ireland

Introduction

Klarna is a payment method available in Belgium and the Netherlands. It’s a payment method where the customer buys now and can pay later. Klarna allows customers to buy items with different types of payment options. Payments options include buy now, pay later or split payments in which the customer can pay for the item in future periods. Meanwhile, the merchants receives their/her money for the item once they ship it to the customer, regardless of the payment option chosen by the customer.

Guidelines

Once a customer selects to pay for their item with Klarna, an order in the Klarna system will be created by the CCV processing host. Once the order has been placed, the merchant will need to (partially) capture this order in order to receive money for that order.

Klarna indicates that a merchant is only allowed to capture an order after some or all the items are shipped to the customer.

Klarna requires order lines so that they know what the contents of an order are for their risk analysis and better customer experience. For merchants implementing the Klarna method with CCV, they will have to include order lines in their payment request, see Order Line.

Supported Transaction Types

Klarna defines two types of transactions:

  • Transactions for digital goods that can be delivered instantly to the customer. For these transactions, an order can be automatically captured once placed.
  • Transactions for physical goods that cannot be delivered instantly to the customer. When the transaction is finished, the merchant needs to process the order and ship some physical goods to the customer. Usually, there is a delay between the order of the item and the actual shipment of the item. For instance, if the item ordered is back-ordered, or it needs to be processed by a warehouse, etc. For these transactions, the merchant has to manually capture the order once the items are shipped to the customer.

CCV has implemented these different kind of transactions using different transaction types in the payment request.

Transactions for goods that can be delivered instantly

When a merchant creates a payment for a transaction with goods that can be delivered instantly, they must use the transaction type sale. When the transaction is completed successfully, the Klarna order is automatically captured.

Transactions for goods that cannot be delivered instantly

When a merchant creates a payment for a transaction with goods that cannot be delivered instantly, they must use the transaction type authorise. When the transaction is completed successfully, the Klarna order is created but not captured. The merchant must send a capture request to CCV, to initiate a capture with Klarna. The merchant is allowed to send (multiple) partial captures for the same order as long as the initial order amount isn’t exceeded. The merchant can optionally send a list of order lines with the capture to indicate which items (if not all) have been shipped to the customer.

If the merchant needs to cancel the order from Klarna a Reversal request must be sent. CCV will then cancel the outstanding Klarna order.

Method API details

Authorise an order

A Klarna payment may contain order lines per purchase item. A payment is not complete until it is captured. You must send a capture request to complete they payment and receive your money.

Klarna advices to include the billing and shipping information for their risk assessment.

Request

The following request will send an authorise request for 99.80 EUR, including 4 pieces of Wine Glass Large at 24,95/glass.

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/payment \
--user X: \
--header 'Content-Type: application/json' \
-d '{
  "transactionType": "authorise",
  "currency": "eur",
  "amount": 99.80,
  "method": "klarna",
   "returnUrl": "http://shop/return?order=123456",
   "merchantOrderReference": "1234567890",
   "description": "Order 123456",
   "language": "nld",
   "billingState" : "Gelderland",
   "billingAddress": "Westervoortsedijk",
   "billingCity": "Arnhem",
   "billingPostalCode" : "6827AT",
   "billingCountry" : "NLD",
   "billingEmail": "dirk.teur@ccvlab.eu",
   "billingPhoneNumber" : "0882289849",
   "billingFirstName": "Dirk",
   "billingLastName" : "Teur",
   "billingHouseNumber" : "55",
   "billingHouseExtension" : "A",
   "shippingState" : "Overijssel",
   "shippingAddress": "Diamantstraat",
   "shippingCity": "Hengelo",
   "shippingPostalCode" : "7554TA",
   "shippingCountry" : "NLD",
   "shippingEmail": "ccv.shop@ccvlab.eu",
   "shippingPhoneNumber" : "0889907700",
   "shippingFirstName": "CCV",
   "shippingLastName" : "Shop",
   "shippingHouseNumber" : "3",
   "shippingHouseExtension" : "B",
   "orderLines": [
   {
           "type":"PHYSICAL",
            "name": "Wine Glass Large",
            "quantity": 4,
            "unit": "pcs",
            "totalPrice": 99.80,
            "unitPrice": 24.95
    }]
 }'

Response

Klarna provides the ability to show a QR code to the customer. The content of the QR code can be found in the response field details.qrCode.

{
    "currency": "eur",
    "details": {
        "qrCode": "https://pay.playground.klarna.com/eu/payments/e03495fa-2b33-9e15-981b-b6ba4b6e80e4/qr",
        "transactionId": "e03495fa-2b33-9e15-981b-b6ba4b6e80e4"
    },
    "paidout": "no",
    "lastUpdate": 1621427446205,
    "amount": 99.80,
    "returnUrl": "http://shop/return?order=123456",
    "reference": "K210519143046189CB87E190.1",
    "billingFirstName": "Dirk",
    "billingLastName": "Teur",
    "billingHouseNumber": "55",
    "billingHouseExtension": "A",
    "billingAddress": "Westervoortsedijk",
    "billingCity": "Arnhem",
    "billingState": "Gelderland",
    "billingPostalCode": "6827AT",
    "billingCountry": "NLD",
    "billingEmail": "dirk.teur@ccvlab.eu",
    "billingPhoneNumber": "0882289849",
    "shippingFirstName": "CCV",
    "shippingLastName": "Shop",
    "shippingHouseNumber": "3",
    "shippingHouseExtension": "B",
    "shippingAddress": "Diamantstraat",
    "shippingCity": "Hengelo",
    "shippingState": "Overijssel",
    "shippingPostalCode": "7554TA",
    "shippingCountry": "NLD",
    "shippingEmail": "ccv.shop@ccvlab.eu",
    "shippingPhoneNumber": "0889907700",
    "payUrl": "https://pay.playground.klarna.com/eu/9TBoO16",
    "cancelUrl": "https://api.psp.ccv.eu/api/v1/cancel?reference=K210519143046189CB87E190.1",
    "merchantOrderReference": "1234567890",
    "created": 1621427446205,
    "language": "nld",
    "method": "klarna",
    "type": "authorise",
    "description": "Order 123456",
    "status": "pending"
}

Klarna Payment Details

Name Description
transactionId The ID of the Hosted Payment Page Session of Klarna.
qrCode Contains the QR code that should be shown to the customer.

Capture an order

Request

If you decide to partially ship to order, you’ll need to send will send a partial capture request. Otherwise you may omit the field orderLines.

Note that in the following example the amount, 49.90, does not match the amount of the initial payment, 99.80. It is exactly the amount of the sum of all order lines and per order line the total of the quantity multiplied by the total price.

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/capture \
--user X: \
--header 'Content-Type: application/json' \
-d '{
   "reference": "Reference of Auth",
   "amount" : 49.90,
   "orderLines": [
       {
           "type":"PHYSICAL",
            "name": "Wine Glass Large",
            "quantity": 2,
            "unit": "pcs",
            "totalPrice": 49.90,
            "unitPrice": 24.95
       }
   ]
}'

Response

{
  "currency": "eur",
  "details": {
    "expiryDate": 1623542400000,
    "orderId": "c3b799da-1704-30f1-95e5-e7a263bcd300"
  },
  "methodTransactionId": "c3b799da-1704-30f1-95e5-e7a263bcd300",
  "lastUpdate": 1621427752154,
  "amount": 49.90,
  "reference": "K210519143552140CB87E191.1",
  "merchantOrderReference": "1234567890",
  "created": 1621427752154,
  "language": "nld",
  "method": "klarna",
  "type": "capture",
  "status": "pending"
}

Klarna Capture Details

Name Description
orderId The ID of the order of Klarna. This matches the order available at Klarna.
expiryDate The date when the order expires at Klarna. All captures should be done before this date

Refund a captured order

Request

If the customer requested a refund, you will need send a (partial/full) refund request for the capture.

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/refund \
--user X: \
--header 'Content-Type: application/json' \
-d '{
   "reference": "Reference of capture",
   "amount" : 49.90,
   "orderLines": [
       {
           "type":"PHYSICAL",
            "name": "Wine Glass Large",
            "quantity": 2,
            "unit": "pcs",
            "totalPrice": 49.90,
            "unitPrice": 24.95
       }
   ]
}'

Response

{
    "currency": "eur",
    "details": {
        "expiryDate": 1623542400000,
        "orderId": "c3b799da-1704-30f1-95e5-e7a263bcd300"
    },
    "methodTransactionId": "c3b799da-1704-30f1-95e5-e7a263bcd300",
    "lastUpdate": 1621427869660,
    "amount": 49.90,
    "reference": "K210519143749627CB87E196.1",
    "merchantOrderReference": "1234567890",
    "created": 1621427869660,
    "language": "nld",
    "method": "klarna",
    "type": "refund",
    "status": "pending"
}

Cancel / Reverse an open Klarna order

Request

If the merchant needs to cancel an open Klarna order a reversal request for the authorisation must be sent.

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/reversal \
--user X: \
--header 'Content-Type: application/json' \
-d '{
   "reference": "Reference of auth"
}'

Response

{
  "currency": "eur",
  "details": {
    "expiryDate": 1623542400000,
    "orderId": "23bd73b0-a695-3648-a498-4c5607d7f968"
  },
  "methodTransactionId": "23bd73b0-a695-3648-a498-4c5607d7f968",
  "lastUpdate": 1621428125106,
  "amount": 99.80,
  "reference": "K210519144205088CB87E194.1",
  "merchantOrderReference": "1234567890",
  "created": 1621428125106,
  "language": "nld",
  "method": "klarna",
  "type": "reversal",
  "status": "pending"
}

Cancel a pending authorise payment

Request

When the customer is still in the middle of processing the payment with Klarna, you have the option to cancel the transaction before the order is created at Klarna. You will need to send a cancel request for the pending authorisation using the cancelUrl returned in the authorisation response.

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/cancel?reference=ReferenceOfAuth \
--user X:

Response

An empty HTTP 200 OK.