API

With KCO Global, the Checkout API supports presenting the checkout in the customer's language, and using the currency in the country of purchase.

Integration overview

The KCO Global integration is handled through these key aspects:

  • Setting allowed shipping/billing countries on Order Create in Checkout API

  • A country_change callback on Checkout API

  • Suspend/Resume on Checkout JavaScript API

 

Set shipping countries on Checkout API

Allowed shipping countries can be set in every order through shipping_countries field

 

Set billing country on Checkout API

The country to render the checkout in can be set with either purchase_country or billing_address.country when creating the order.

Update billing country

By default, the available billing country* list will match the list of shipping_countries.

Updating billing country in the checkout will trigger the new country_change callback, and when billing_address.country changes, the checkout will change to reflect the new billing country.

Country change Callback on Chekcout API

The country_change callback allows for the checkout in the customer's language, and display of the currency for the purchase country.

Suspend and Resume on Checkout JavaScript API

This functionality is documented in the Suspend and Resume section and will force the Checkout Client to fetch an updated state from the server side.

Integration Approaches

There are two possible KCO Global integrations. The first only relies on callbacks and updates against the Merchant API. The second is a combined integration making use of both the Checkout JavaScript API and the Checkout API.

Checkout API driven approach

This approach is the easiest from an implementation perspective. The downside is unfortunately that it is a, from the customer perspective and perception, slightly slower integration. This integration is also slightly less resilient than the Checkout JavaScript API driven approach.

  1. Whenever a customer switches their country a country_change will be triggered.
  2. A suspend should be performed against the Checkout JavaScript API.
  3. An Order Update should be performed with data that makes sense for the new customer country.
  4. After successful Order Update a resume should be performed against the Checkout JavaScript API.

Checkout JavaScript API driven approach

This approach is slightly more demanding depending on the merchants setup. From a customer perspective this will be perceived as a smoother integration. This integration is also more resilient than the Checkout API approach.

  1. Whenever a customer switches their country a change event is triggered on the Checkout JavaScript API.
  2. When the country has changed from previous change events; a suspend should be performed against the Checkout JavaScript API.
  3. The new country should be sent to the Merchant Server, which in turn should perform an Order Update with data that makes sense for the new country should be performed against the Checkout API.
  4. A resume should be performed against the Checkout JavaScript API.