Best practices for Kustom Checkout

Follow our best practices to make your integration robust, fast, and secure.

KCO Iframe Handling

Use case

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.

Best practices

• 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 be at minimum 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 handled by the Checkout iframe. Ensure no merchant CSS is applied to the elements.
• There can be hidden elements inside the container. The elements mustn't be styled, as the Checkout iframe is responsible for showing and hiding them.

Creating a checkout session

Use case

Merchant creates a KCO order (session) and needs to know best practices for new and existing orders.

Best Practices

For a new order:

• Assign the merchant_url's collection for callbacks.
• Assign locale properties (Country, Currency, Locale).
• Assign the order_line object properties for cart items.
• Sales tax may not be computed initially; a default tax line item or 0 can be assigned.
• Assign checkout options to customize the KCO snippet (defaults to False if not supplied).
• Assign optional shipping properties to the shipping_options collection. If dependent on shipping address, add these later.
• Create the Order Resource object and assign properties.
• Convert the order object to JSON.
• Perform a POST request to create the order.

For an existing order:

• Fetch the order using the order location URI from the saved session variable.
• Add/update cart items.
• Update order amounts (tax and total).
• Perform a POST request to update cart items and properties.
• Do not change the location stored in the session variable.
• Display the HTML snippet returned from the POST (status will be checkout_incomplete in KCO).

Re-entering the checkout

Use case

When the customer closes the browser or navigates away from the checkout page and later returns to complete the order.

Best Practices

Store the KCO order location URI in a session variable during the initial order creation.

• Check for a stored KCO order session before creating a new order.
• If a session exists, perform a GET request using the location URI.
• A JSON object with the current order is returned, which can be updated.
• Deserialize the JSON to a CheckoutOrder object.
• This includes the snippet used to render the checkout.
• If a 4xx, 5xx, or other error occurs, create a new order.
• KCO orders expire after 48 hours of merchant update/client interaction.
• Handle potential order expiration due to internal system issues.

Handling order changes outside the checkout snippet

Use case

After the checkout page is rendered, the customer may change shipping options, enter promo codes, or update cart items. The KCO widget doesn't reflect these changes, requiring a refresh.

Best Practice

Suspend and Resume

• Suspend the checkout process using the JavaScript API.
• Update the merchant's cart.
• Perform a POST request to KCO to update the order (do not create a new order).
• Resume the checkout process. This refreshes the KCO with the updated data.

Handling changes inside the checkout snippet

Use case

The merchant relies on KCO for billing and shipping addresses. Address changes require recalculating tax and shipping.

Best Practice

Server-side

Receiving address update from KCO:

• KCO sends a callback to the address_update URL in merchant_url. This URL must be HTTPS.
• The POST request contains updated order details (JSON format).
• Deserialize JSON to extract addresses, recompute sales tax, update order_lines, and update the order.
• Determine shipping cost and update the shipping_fee line item.
• Return the updated order details to KCO as JSON in the response.
• Handle 2xx responses; handle errors and timeouts (10 seconds).

Updating the order

• Add shipping options (if not supplied).
• Add discount codes (if address-dependent).
• Optionally update shipping_fee in order_lines.
• Send updated order details back to KCO.

Client-side

• KCO updates to reflect billing address, new total, and option to change shipping.
• If shipping options are sent, they are pre-selected.
• Merchant panel updates to reflect changes (e.g., tax, total).
• Wire JavaScript events to the form elements for tax and total amounts.
• Wire events to the merchant panel for changes (e.g., email, zip, name, shipping address, order total, shipping option).

DO NOT

• Refresh the entire page.
• Create a new KCO order.
• Perform KCO POST/GET requests to create or update the order; use the returned order from KCO's POST.

Render checkout

The checkout page should include:

• Merchant's order summary panel showing order items, costs, quantities, tax, total, discounts, and shipping options (above or beside the KCO panel).
• KCO panel (HTML snippet div tag).

Modify Merchant Cart Panel from checkout page - optional

If the customer updates the merchant cart (e.g., shipping, promo), the KCO panel needs refreshing to reflect changes. Suspend and resume the checkout process.

Address updated

• Customer changes shipping or selects a different option or adds a discount; KCO events update the merchant panel without full page refreshes.

Complete Checkout & Validation

• KCO completes checkout; merchant validates order details (stock, cart matching).
• If no validate URL exists in merchant_url, the order status becomes checkout_complete in KCO. Changes can only be made via KCO Order Management API.
• Validation (must complete within 3 seconds):
  • If a validate URL is provided (HTTPS), KCO POSTs the order.
  • Status is checkout_incomplete—changes can still be made. Typical validation issues:
    • Out-of-stock.
    • Delivery restrictions.
    • Order number generation.
    • Cart/KCO order details mismatch.
  • No KCO PUT/GETs or merchant cart updates.

Confirmation

• Confirmation URL in merchant_url is called by KCO.
• KCO updates order status to checkout_complete.
• Final GET request returns the order.
• Merchant commits the order to their system.
• If commit fails, order queues in KCO's Order Management; acknowledged every 4 hours for 48 hours.

Push

• Once in Order Management, KCO POSTs to push URL in merchant_url every 4 hours for 48 hours.
• Merchant acknowledges in Order Management.
• Merchant updates merchant_reference1 (external order ID) in KCO Order Management.
• Cancel order if not created in merchant system.
• Shipping and capture using KCO Order Management API.

Address limitations

• Handles address line truncation exceeding character limits, splitting lines based on abbreviations.
• Truncates street addresses and handles limited name character counts.
• Validates and formats phone numbers (E.164 format).
• Supports 5-digit and 5-4-digit US zip codes.