Klarna Pay Later

Besides basic order data, for a Klarna Pay Later order the following extra details are required:

  • Order lines data – will indicate quantities, type of article and prices of distinct articles of an order.

The order line type must be one of physical, discount, shipping_fee, sales_tax, digital, gift_card, store_credit or surcharge.

Example with customer data:

{
    "amount": 10000,
    "currency": "EUR",
    "customer": {
        "additional_addresses": [
            {
                "address": "Example 10\n1000AA Amsterdam",
                "address_type": "billing",
                "country": "NL"
            }
        ],
        "address": "Example 8\n1000AA Amsterdam",
        "address_type": "customer",
        "birthdate": "1970-07-10",
        "country": "NL",
        "email_address": "email@example.com",
        "first_name": "First",
        "gender": "male",
        "ip_address": "127.0.0.1",
        "last_name": "Last",
        "phone_numbers": [
            "0612345678"
        ]
    },
    "description": "Example Klarna order",
    "order_lines": [
        {
            "amount": 5000,
            "currency": "EUR",
            "merchant_order_line_id": "0001",
            "name": "Example article",
            "quantity": 2,
            "type": "physical",
            "vat_percentage": 2100
        }
    ],
    "payment_methods": ["klarna-pay-later"]
}

Example of a minimally required payload:

{
    "amount": 10000,
    "currency": "EUR",
    "description": "Example Klarna order",
    "order_lines": [
        {
            "type": "gift_card",
            "amount": 5000,
            "currency": "EUR",
            "merchant_order_line_id": "0001",
            "name": "Example article",
            "quantity": 2,
            "vat_percentage": 2100
        }
    ],
    "payment_methods": ["klarna-pay-later"]
}

Example of transaction that is automatically captured in 1 day:

{
    "amount": 10000,
    "currency": "EUR",
    "description": "Example Klarna order",
    "order_lines": [
        {
            "type": "physical",
            "amount": 5000,
            "currency": "EUR",
            "merchant_order_line_id": "0001",
            "name": "Example article",
            "quantity": 2,
            "vat_percentage": 2100
        }
    ],
    "transactions" : [{
        "payment_method": "klarna-pay-later",
        "expiration_period": "P1D",
        "capture_mode": "delayed"
    }],
}

Example of transaction that requires manual capturing in 7 days:

{
    "amount": 10000,
    "currency": "EUR",
    "description": "Example Klarna order",
    "order_lines": [
        {
            "type": "physical",
            "amount": 5000,
            "currency": "EUR",
            "merchant_order_line_id": "0001",
            "name": "Example article",
            "quantity": 2,
            "vat_percentage": 2100
        }
    ],
    "transactions" : [{
        "payment_method": "klarna-pay-later",
        "expiration_period": "P7D",
        "capture_mode": "manual"
    }],
}

Klarna screening and order statuses

Klarna will use the basic customer data to decide if an order could be created. If Klarna will decline certain customer payment, then created order will get status cancelled. In some cases, additional time is required for Klarna to take a decision about the customer, then created order will get status processing. Later you can request actual status of an order.

Klarna’s customer facing errors

When a customer provides incorrect personal data, for example his phone number does not match his country – then Klarna will provide an error description, which should be shown to the customer on your website. Order creation response will contain status error and you’ll be able to find text for human readable error in the reason key of the response.

Klarna transactions capturing

It is possible to use API to capture Klarna orders. You need to send a request after you have shipped the goods to the customer.

1. Full capture

Request example:

POST /v1/orders/<order_id>/transactions/<transaction_id>/captures/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=

When you create a new Klarna order, in the response you have list of transactions, which contains one transaction. You need to use ID of this transaction to send the capture request.

Body for this request should be left empty.

2. Capture based on amount

POST /v1/orders/{id}/transactions/{transactions_id}/captures/amount/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
If-Match: only-update-when-the-ETag-value-matches

{
	"description": "Let's capture it",
	"amount": 123
}

3. Capture based on order lines

POST /v1/orders/{id}/transactions/{transactions_id}/captures/orderlines/
Authorization: Basic aHVudGVyMjo=
If-Match: only-update-when-the-ETag-value-matches

{
	"description": "Let's capture it",
	"order_lines": [
		{
			"merchant_order_line_id": "0001",
			"quantity": 2
		}
	]
}