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_feename
- 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.