When the customer reaches the checkout page, the merchant loads the html snippet provided in the response of the Create Order request, which will then create the checkout iframe.

• The Checkout iFrame lives inside the container #klarna-checkout-container.
• The container is created by the JS snippet retrieved in the order body.
• The container mustn’t be styled. If the Checkout iFrame should have a restricted width, apply that rule to an element wrapping the container.
• The width of the Checkout iFrame should at minimum be 320px.
• The Checkout iFrame must be able to grow and shrink height-wise as the user progresses in the checkout flow.
• Styling of elements inside the container is being taken care of by the Checkout iFrame. Make sure no merchant CSS is applied to the elements.
• There can be hidden elements inside the container. The elements mustn’t be styled, since the Checkout iFrame is responsible for showing and hiding them.

Merchant creates a KCO Order (session) and needs to know the best practices associated with a new order and an existing order.

For a new order,

• Assign the merchant_url’s collection to be used for callbacks.
• Assign the locale properties (Country, Currency, Locale).
• Assign the order_line object properties for the cart items.
• Since sales tax is calculated based on the shipping address, it may not be computed at this time. However, a line item for sales_tax could be loaded for the order with a default tax, or assign 0.
• Assign the checkout options object properties to customize the KCO snippet. Any not sent will default to False
• Assign the optional Shipping option properties and add them to the shipping_options collection. If these are not supplied here, they should be supplied after the shipping address is updated. If these are dependent on the shipping address, do not add them now.
• Create the Order Resource object and assign the properties.
• Convert the order object to a JSON string
• Perform a POST request to Create the order

For an existing order,

• GET (Fetch) the order using the order location uri from the saved session variable.
• Add/Update the cart items collection.
• Update the order amounts (tax and total).
• Perform a POST request to update the cart items and properties.
• The location stored in the session variable should not change.
• Show the html snippet returned from the POST. Status will be ‘checkout_incomplete’ in KCO.

When the customer closes down the browser or goes back to the steps before the checkout page (eg: product page, landing page) and later comes back to the checkout page to complete the order.

When the customer has completed shopping and the checkout page is rendered for the first time, a session variable should be used to store the KCO Order Location URI returned from the initial POST creating the order.

NOTE: This is NOT the snippet, it is the URL for the order

When the customer re-enters the checkout:

• Check if the KCO Order session is stored before creating a new order. I.e: https://api-na.playground.klarna.com/checkout/v3/orders/[KlarnaOrderId] or in EU, use the EU playground site https://api-eu.playground.klarna.com/checkout/v3/orders/[KlarnaOrderId]
• If it exists perform a GET request using this Location.
• A JSON object containing the current KCO order is returned which can be updated instead of creating a new order.
• Deserialize this to a CheckoutOrder object to simplify working with the order.
• This also includes the snippet that is used to render the checkout.
• If you get a 4XX or 5XX or any other type of error, you should create a new order.
• KCO orders are only valid for 48 hours after merchant update or client interaction and expire after that. This expiration is normal.
• Checkout orders could also expire early for other internal system issues, so error handling must also be implemented in this step to create a new Checkout Order if the URI is invalid.
• The KCO order location URI should be retained because when a customer starts filling out their details they will not have to re-enter them if they leave and come back to the checkout.

After the checkout page is rendered, the customer may change shipping options, enter promo codes, or remove line items or update item quantity from the merchant panel. Anytime this occurs, the KCO widget will not reflect these changes and will need to be refreshed. This is done by suspending and resuming the checkout frame.

Suspend and Resume

Used while the checkout page is rendered and the user modifies the cart within the merchant order summary panel.

• Suspend the checkout process using the JavaScript API to the checkout.
• This “locks” the KCO so the user may not interact with it.
• Update the merchant’s cart.
• Perform a POST to KCO to update the order.
• DO NOT create a new order at KCO.
• Resume the checkout process using the KCO JavaScript API to the checkout.
• This causes KCO to refresh with the data that was just updated via the server side POST.

The merchant has not collected the billing or shipping address and is reliant on KCO to provide the shipping address. When the address is supplied in the KCO, it will default the shipping address to this address. Anytime the address changes, the tax or shipping may need to be recomputed by the merchant.

Server side

Receiving the address update from KCO,

• A callback from KCO to the merchant is made to the ‘address_update’ URL defined within the merchant_url’s for the order. The URL MUST be an SSL address (https://).
• Although a self-signed certificate will work here, it would be best to obtain a real certificate since this is required for the final PUSH. The POST from KCO sends the checkout order as JSON with the billing and shipping address info updated by the customer. The body also contains the order_lines, order_amount and order_tax_amount. The merchant should:
• Deserialize the JSON and parse out the addresses.
• Re-compute sales tax.
• Parse out the sales_tax line and update or add it if not already part of the order_lines.
• Update the order internally.
• Determine the shipping cost.
• Update the shipping cost line item.

Updating the order

As the shipping address is known now,

• The shipping options may be added to the order if not already supplied.
• If discount codes are dependent on address, or are not already added to the order, these may be supplied.
• Optionally, add or update the shipping_fee order line to the order_lines if not already present
• The updated order details will be sent back to KCO as the response to the address update POST request, as a JSON.
• If the merchant responds with any status code other than 2XX, or if they do not respond within 10 seconds, the purchase will not complete and an error message will display and instruct the customer to try again. This will be logged for merchant support.

Client side

• When the order is received by KCO with the calculated tax, the KCO is changed to reflect the billing address, new total amount, and an option to change the shipping address.
• If shipping options are supplied they will be displayed with the ‘preselected’ option checked.
• Since the merchant panel initially showed 0 tax, it should be changed to reflect these cost changes. This is done by javascript events fired from the KCO.t
• Optionally, shipping options and discount codes displayed in the KCO panel may change causing the total amount to change.
• Javascript events should be wired to the form elements displaying the Tax and Total amounts.
• Events that may be wired into the merchant panel:
• ‘change’ – event fires anytime the email address, zip, or names supplied are changed or entered.
• ‘shipping_address_change’ – event will fire anytime the shipping address changes.
• ’order_total_change’ – event will fire anytime the order total change
• ‘shipping_option_change’ - fired anytime the user selects a different shipping option

• Refresh the entire page. The javascript events on the form elements will update the merchant panel with the changes.
• Create a new KCO. This would create a new KCO order id
• Perform a POST to create or update the order. The order was updated at KCO with the response sent back from the POST from KCO.
• Perform a GET with the orders location URI. What was sent back with the Response to KCO is the most current order.

The checkout page contains:

• Merchant’s order summary panel showing summary of items purchased, cost, quantity, tax, order total, optional discounts and shipping options. This panel can be shown above or beside the KCO panel.
• KCO panel (html_snippet div tag)
• For a newly created order the html snippet will contain the labels:
• For existing orders the snippet will be pre-filled and contain:

With the checkout page rendered, the user may change shipping options, enter promo codes, or remove line items or update item quantity from the merchant panel. Anytime this occurs, the KCO panel will not reflect these changes and will need to be refreshed. This is done by suspending and resuming the checkout process.

User may change shipping address or select a different shipping option or add a discount

• If any of these occur within the KCO the appropriate events will fire allowing the merchant panel to be re-displayed without performing screen refreshes.
• The 2 panels should always be in sync.

Once the checkout has completed at KCO the merchant may want to validate the order items are in stock, or confirm the order items in the cart are the same as what KCO shows.

If no validate URL is assigned to the merchant_urls the order is updated in KCO (KCO) with a status of ‘checkout_complete’. No other changes may be made to the order through the Checkout API’s. Afterwards, changes may only be made through KCO Order Management API.

Validate – Must complete within 3 seconds else the order is created.

If a ‘validation’ URL (MUST BE SSL ADDRESS) is assigned in the collection of merchant_url’s, then KCO will perform a POST request to this URL. The entire order is passed back here. The status will still be ‘checkout_incomplete’ so changes may still be made. Typical issues:

• 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.
• Another issue here could be that the line items are out of synch because something was added to the cart after the checkout was started. Compare the current cart state to the KCO order state (totals, shipping selection, discounts, and gift cards). If they don’t match there is an issue.
• No KCO PUTS or GETS should be done in this function.
• No updates to the merchant cart done in this function since they should occur on the shopping pages.

Validate OK – Or not completed within 3 seconds

If the validation is not performed within 3 seconds it is considered valid and the confirmation redirect will occur.

• To approve the purchase, reply with a HTTP status 2XX. The consumer will then be redirected as normal to the checkout confirmation page.

Validate Not OK

• To deny the purchase, reply with a HTTP status 303. 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.
• If the rejection is due to line items being out of sync, the easiest way to fix this would be for the customer to click the checkout button again which will open the checkout page and refresh it with the current cart items on the site. This will use the existing Session order URI to GET the order.
• Complete the checkout process again.

• The confirmation URL assigned to the list of merchant_url’s is called from KCO.
• KCO will update the order status to ‘checkout_complete’.
• A final GET is performed returning the order as it exists in KCO.
• This page should have logic that commits the order in the merchant system.
• If the commit of the order succeeds, then another redirect done by the merchant site should be performed to take the customer to the final confirmation page.
• If the commit fails:
• The order is placed into a queue at KCO waiting to load to the Order Management system.

Once the queued order moves to KCO’s Order Management a POST is made to the ‘push’ URL provided in the list of merchant_url’s. This occurs every 4 hours for 48 hours or until it’s acknowledged. The Merchant should have a process that can ‘Acknowledge’ this in Order Management.

If the order isn’t created in the merchant’s system. It should be done here. Once created the internal merchant order id should be updated to the MerchantReference1 field for the order in KCOs order management system. If the order for any reason can’t be created in the merchant’s system the order should be canceled with KCO using the Order Management API.

Acknowledge – through Order Management API

Once the order has been pushed to Order Management it should be ‘Acknowledged’ by the merchant.

• Send a POST request to ‘Acknowledge’ the order.
• This may be a good time to update the merchant_reference1 and merchant_reference2 if not already set.
• Merchant_reference1 is ALWAYS the external customer facing ‘Order Id’ generated by the merchant.
• Merchant_reference2 can be another id associated to the order.
• At this point the items may be shipped.
• Once shipped, the merchant will make capture calls using the KCO Order Management API.

Example if address is limited to X characters:

• If address line 1 is greater than X and address line 2 is empty then search for the first occurrence of these abbreviations (search whole word not just in-string):
• APT
• BSMT
• BLDG
• DEPT
• FL
• FRNT
• HNGR
• LBBY
• LOT
• LOWR
• OFC
• PH
• PIER
• REAR
• RM
• SIDE
• SLIP
• SPC
• STOP
• STE
• TRLR
• UNIT
• UPPR

and if found split to address line 2.

• Optionally, truncate Street Address 1 and 2 at X characters

Name length may be limited on your end.

• Truncate first name at 15 characters
• Truncate last name at XX characters (confirm length)
• Replace any of the following characters @ $ ! % ^ & * ( ) ~ < > + # in the first name with a space
• Confirm the validation for last_name. If needed, should also strip invalid characters from it as well.

Apply a phone number rule. It appears that phone numbers with +1 are being failed for some merchants.

Merchants should support the E.164 number formatting for all phone numbers both in the ‘to’ and ‘from’ fields. This format is the internationally-standardized format for all phone numbers, and it includes all the relevant information to route calls and SMS messages globally. E.164 numbers can have a maximum of fifteen digits and are usually written as follows: [+][country code][subscriber number including area code].

Apply a zip code rule as well that will support both 5 digit zips as well as 5-4 digit zips for the US.