Validating the Order Before it is Completed

For a number of different reasons there could be a need to validate the order before it is completed. You can register a callback on the order create (where you can do the final merchant validation) that Klarna will call when the customer clicks the buy button. Find out more in the Order validation API.

Use cases

  • Out of stock validation - for high turnaround businesses this functionality enables you to verify that an item added to a cart is indeed still in stock before the consumer completes the purchase.
  • Delivery limitations - some products cannot be shipped to certain geographies. This functionality enables you to verify that the products can be shipped to the address the consumer has provided.
  • Order number generation - certain systems have flows that require the creation of an internal order ID when order has been created, such as for tracking purposes. This functionality allows you to create an order ID upon receiving the validation callback and displaying it on the confirmation page.

1. Create a checkout order

Create a Checkout order exactly as you learned in the render the checkout snippet tutorial , and make sure to include the optional property merchant_urls.validation.

Note: All communication with the validation URI will be encrypted. For that reason you must use the HTTPS protocol for this URI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
Accept: application/json
Authorization: Basic a2xhcm5hOnVuaWNvcm5z
Content-Type: application/json

{
    "purchase_country": "gb",
    "purchase_currency": "gbp",
    "locale": "en-gb",
    "order_amount": 10000,
    "order_tax_amount": 2000,
    "order_lines": [
    {
        "type": "physical",
        "reference": "123050",
        "name": "Tomatoes",
        "quantity": 10,
        "quantity_unit": "kg",
        "unit_price": 600,
        "tax_rate": 2500,
        "total_amount": 6000,
        "total_tax_amount": 1200
    }, 
    {
        "type": "physical",
        "reference": "543670",
        "name": "Bananas",
        "quantity": 1,
        "quantity_unit": "bag",
        "unit_price": 5000,
        "tax_rate": 2500,
        "total_amount": 4000,
        "total_discount_amount": 1000,
        "total_tax_amount": 800
    }
    ],
    "merchant_urls": {
    "terms": "http://toc",
    "checkout": "http://checkout?klarna_order_id={checkout.order.id}",
    "confirmation": "http://confirmation?klarna_order_id={checkout.order.id}",
    "push": "http://push?klarna_order_id={checkout.order.id}",
    "validation": "http://validation?klarna_order_id={checkout.order.id}"
    }
}

2. Respond to Klarna’s POST request

When the consumer clicks “buy now” a POST request will be sent to the merchant_urls.validation. The body of the request will contain the current order information. The structure of the order information is identical to the result of fetching the order, as you saw in render the checkout.

Note: There is no need to fetch the order from Klarna since all the order information is included in the POST request body.

Once you receive the POST request, our system will expect a response within 3 seconds. If Klarna does not receive a response, we will approve the purchase. The response you provide Klarna will determine whether or not the purchase will be completed:

  • To approve the purchase, reply with a HTTP status 200 OK. The consumer will then be redirected as normal to the checkout confirmation page.
  • To deny the purchase, reply with a HTTP status 303 See Other. This needs to include a Location header pointing to a page which informs the consumer why the purchase was not completed. The consumer will be redirected to this page.

Note: The rejection page needs to be hosted by you, and we highly recommend that you give the consumer detailed information as to why you rejected the order.

2.1 Cards and 3D Secure

Responding to the validation callback with HTTP status 200 OK will not always guarantee that the order is completed, for example if the consumer is paying using card and triggering 3D Secure authentication. When authentication is completed then a reservation is made on the customer’s card, in case a validation callback is fired after the authentication event and is responded to with an HTTP 303 (in this context: deny purchase) response status, Klarna will still retain the reservation on the customer’s card.

Hence, whenever Klarna reserves money this happens as the last part of the purchase flow. Therefore an HTTP 200 OK response status followed by failed 3D Secure authentication does not allow for completing the order and does not redirect the customer to the confirmation page.