Validate a checkout order

This checkout function will allow you to validate the information provided by the consumer in the Klarna Checkout iframe before the purchase is completed.

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.

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.


Business to Business

Sometime an order is placed on behalf of an organization, not an individual. We refer to this as the Business to Business flow, or B2B flow, for Klarna Checkout. The B2B flow comes with some differences in the user experience and integration compared to the Business to Consumer flow (B2C).

Klarna Checkout can be configured to support B2B in Sweden, Norway and Finland.

Prerequisities

  • You have implemented Klarna Checkout
  • Your e-store ID has been enabled for B2B by Klarna (available in Sweden, Norway and Finland)

How it works

From an implementation point of view, B2B for Klarna Checkout is utilizing the same logic and API as the regular Klarna Checkout for B2C (Business to Consumer). This means you will re-use your existing Klarna Checkout integration and just make the changes described in the Implementation flow below.

When enabling support for B2B you introduce a new user flow, meaning there will visually be one option for business customers and a separate option for a regular consumer in the Klarna Checkout. The B2C flow is loaded as default, but you can optionally render the B2B flow by default to a known business customer.

  • The customer can toggle between the B2C and B2B flows in the checkout.
  • The B2B flow asks for details pertaining to an organization, such as Organization number.
  • It is possible to configure the checkout for separate shipping and billing address in the B2B flow.
  • The available payment methods in the B2B flow are Invoice and Card payments.
  • Recurring orders are not supported in the B2B flow.
  • It is possible to use a separate link for the terms presented in the B2B flow, which you pass along when creating the order. If such a link is not provided, the B2C terms will be presented by default.

The B2B flow for Klarna Checkout will be configured by Klarna on the same e-store ID as the regular B2C Klarna Checkout.

Implementation flow

Follow these steps to enable the B2B flow in your existing Klarna checkout integration.

 

Step 1 - Configure the checkout

Before loading the checkout, you will set the relevant options to indicate that B2B should be included.

1a. Enable the option to choose between the B2C or B2B flows

When configuring the checkout order, set the options for allowed_customer_types to both person and organization.

"options": { "allowed_customer_types": ["person", “organization"] }

 

1b. (Optional) - If desired, render the B2B flow instead of B2C

By default, the regular B2C user flow will be rendered when the checkout loads. If you instead want to render the B2B flow when it loads, you can optionally set the customer.typefield to organization

"customer": { "type": "organization" }

 

1c. (Optional) - Prefill the organization number

If you have the organization number available for this business, you can optionally prefill it in the checkout by setting it in the organization_registration_id field. That way the customer will not have to enter them again in the checkout, but still has the option to change it if it is incorrect.

"customer": { "type": "organization", "organization_registration_id": "556036-0793" }

 

1d. (Optional) - Set specific T&Cs to be presented in the B2B flow

In order for a merchant to display their b2b and b2c terms differently it is possible to have a separate links. The terms are displayed in the same place as the b2c terms. In addition to the existing field that can be used for adding legal terms for B2C (merchant.terms_uri), a separate field called merchant.organization_terms_uri is also available. If set, the terms from that field will be presented when the customer is in the b2b flow. If not set then the terms from merchant_uri will be used.

"merchant.organization_terms_uri": { "your URI string" }

 

 

Step 2 - Load the checkout

Create the order and render the checkout as usual. The customer should now be able to switch between the B2C and the B2B flows.

 

Step 3 (Optional) - Listen to customer interaction events from the checkout

The customer starts entering the required fields in the B2B flow. The additional fields will be the organization id and an optional "Reference" field where they may for example add their name or department.

If you need to know which flow the customer is in before the order is placed, in order to for example always show the correct shipping options on your page, you may do so using our JavaScript API.

Start by subscribing to the load signal.

_klarnaCheckout(function(api){
  api.on({
    load: function(data){
      console.info(data)
    }
  })
})

You will now be notified about customer data including the flow type and partial shipping address before the order is placed. When the customer switches the flow, the checkout reloads and callback is triggered again.

Here is a sample of the notification from the callback

{
  "customer": {
    "type": "person"
  },
  "shipping_address": {
    "country": "SE",
    "email": "klara.joyce@klarna.com",
    "postal_code": "12345"
  }
}

 

In order to listen shipping address change events before the order is placed, the relevant shipping_address_change signal must be used in the same way.

 

Step 4 - Parse the organization's address details from the completed order

The B2B customer places the order when they press the buy button. When you retrieve the completed order placed in the B2B flow, the customer object contains a type which identifies if this was an organization or a consumer (person).

"customer": {
      "type": "organization", // optionally, this could be set to "person"
      "organization_registration_id": "556036-0793"
},

 

If the customer.type is organization, the billing address includes potentially two additional fields called organization_name and reference. Note that empty fields are not returned, so if the reference was not entered by the customer, it will not be available in the response.

"billing_address": {
     "country": "{{<country}}",
      "given_name": "{{<given_name}}",
      "family_name": "{{<family_name}}",
      "organization_name": "{{<organization_name}}",
      "street_address": "{{<street_address}}",
      "city": "{{<city}}",
      "phone": "{{<phone}}",
      "reference": "{{<reference}}"   
},

 

This was the final step.

Please note: You need to contact Klarna to enable B2B for any applicable e-store ID before going live.