Tax Handling

Tax handling is important as Checkout will validate this and throw an error if it's not correct.

Handling tax without shipping in KCO.

Please see the create order API reference for information about tax calculations and fields.

Handling tax when using shipping in KCO.

The business logic for both tax calculations and the selection of shipping options is specific to each merchant:

• Sales tax calculation may depend on (among other things) the shipping address of the customer.
• Shipping options may depend on the customer’s shipping address.

Options

KCO allows the merchant to:

• Update the tax amount of the order when the customer enters or changes their shipping address.
• Present their shipping options within the KCO iframe
• Update the shipping options when the customer enters or changes their shipping address.

If the customer only enters one address in KCO it will serve as both billing and shipping address.

Process

The process of updating tax and shipping consists of three phases:

• Initialization
• Callback to merchant
• Order creation

Initialization

• In order to update the cart when shipping address changes, you need to add a callback URL when initializing the checkout.
• If you want to display shipping options from start you can provide an initial list of shipping options.

Callback

When the shipping address is changed a POST request is sent to the callback URL specified by the merchant.

The body of the request contains:

• shipping_address
• order_amount
• order_tax_amount
• order_lines

The order_amount, order_tax_amount, and order_lines make up the cart object.

The merchant responds to the request. As a merchant you can choose to update:

• The cart
• Shipping options
• Both the cart and the shipping options
• None of them.

The response is handled:

• If a cart object is present the order will be updated with the provided cart
• If a list of shipping options is present the order will be updated with the provided shipping options.
• The purchase will not proceed in any of these cases:
  • the cart object is invalid
  • The shipping options are invalid
  • the response is a status code other than 200
  • There is no response within 10 seconds

If so, a message is displayed to the customer telling them that something went wrong and that they can try again. This will be logged for merchant support.

Order creation

• The customer selects a shipping option.
• The shipping option is added to the order as selected_shipping_option.
• If the selected shipping option has a price, an order line is added to the order:
  • type - shipping_fee
  • name - name of the shipping option
• Price and tax details are copied from the shipping option

Updating the tax amount and shipping cost

If you provide the address_update URL as part of the merchant_urls a POST request will be sent to that URL when the customer enters or edits the shipping address.

The body of the POST request will contain these fields:

• order_amount
• order_tax_amount
• order_lines
• billing_address
• shipping_address
• selected_shipping_option

Shipping options at order creation

The selected shipping option

Dynamically update shipping options

Shipping option selected callback

Using SmartPost with KCO

• If SmartPost is used as shipping alternative, KCO needs to receive the SmartPost address and the phone number to which the SmartPost SMS PIN is sent to.
• Different shipping/billing should be turned off in KCO for these transactions to not confuse the user that otherwise would need to to enter shipping address twice.
• The Phone number entered into KCO needs to be used for sending the SmartPost SMS PIN. The SmartPost address shall be sent to KCO as “shipping option” before the checkout is loaded to enable KCO to do risk assessment on the Address.