Kustom Checkout for WooCommerce is a plugin that extends WooCommerce, allowing you to take payments via Kustom. The checkout is embedded in your WooCommerce checkout page, and one plugin gives you every payment method on your Kustom account.
The plugin is built and maintained by Krokedil. You need a Kustom merchant account, and API credentials from the Kustom Portal, to use it.
- See Kustom’s market coverage for the markets Kustom Checkout is available in, with the payment methods, currencies and languages offered in each. You need a Kustom agreement for each country you sell to, and your store must be able to take payment in that country’s local currency. Read more about selling in multiple markets.
- You need an agreement with Kustom to be able to use this plugin.
- WordPress 5.0 or newer is required.
- WooCommerce 9.7.0 or newer is required.
- PHP 7.4 or higher is required. PHP 8.x is supported.
- A valid SSL Certificate is required.
When the customer clicks Place order in Kustom Checkout, the WooCommerce order is created first (in Pending status), then Kustom finalizes the purchase, and finally the customer is redirected to the order received page and the WooCommerce order is updated to Processing status.
This means that Pending orders can be visible in WooCommerce, where the payment has not been finalized in Kustom (for example card payment where there was not enough funds on the card). This is part of the general WooCommerce checkout flow, and it does not imply that something is wrong. Don’t change these orders to Processing or Completed manually. If an order isn’t yet available in Kustom when the customer returns, it is set to On hold until Kustom’s push notification confirms it, usually within a couple of minutes. Read more about the checkout flow here.
Related Documentation
↑ Back to top- Order management
Read more about how to manage Kustom orders directly from WooCommerce. Order management is built into the plugin from version 2.19.0. - Kustom Checkout Hooks: Actions & Filters
Read more about available hooks in the Kustom Checkout plugin. - Recurring payments
Kustom Checkout supports recurring payments via the WooCommerce Subscriptions plugin. Here is a guide to help you get started. - Kustom Shipping Assistant
Show carrier options and pickup points from your transport management system (TMS) inside the checkout. Built into the plugin from version 2.23.0.
Installation
↑ Back to topTo start using a product from WooCommerce.com, you can use the “Add to store” functionality on the order confirmation page or the My subscriptions section in your account.
- Navigate to My subscriptions.
- Find the Add to store button next to the product you’re planning to install.
- Follow the instructions on the screen, and the product will be automatically added to your store.
Alternative options and more information at:
Managing WooCommerce.com subscriptions.
Required WooCommerce Settings
↑ Back to top- Make sure that you have enabled pretty permalinks in your WordPress installation (any option other than Plain under Settings > Permalinks). Otherwise callbacks from Kustom back to your store won’t work and orders will not be updated with the correct order status/information.
- It is recommended to enable guest checkout (WooCommerce > Settings > Accounts & Privacy).
- To get the order total to match between WooCommerce and Kustom you need to configure WooCommerce to display prices with 2 decimals (WooCommerce > Settings > General > Currency options). More information about displaying of prices and how it can cause rounding issues can be found in this article.
- Create and publish a Terms and Conditions page and assign it under WooCommerce > Settings > Advanced > Page setup. The checkout links to it.
- If you sell physical products, add at least one shipping method for every country you deliver to under WooCommerce > Settings > Shipping. The checkout only offers the shipping options configured there.
- Do not cache the cart and checkout pages. They are dynamic pages, and caching them can show wrong prices, mix up order numbers or show one customer another customer’s information. Read more about caching and optimization.
- Keep all WooCommerce checkout fields available. They can be visually hidden, but themes or plugins that remove checkout fields entirely stop the customer details from Kustom Checkout being saved on the WooCommerce order. Don’t alter or add to the
[woocommerce_checkout]shortcode. - To sell to customers outside your store’s base country, Kustom Checkout Global must be activated on your Kustom account. Otherwise those customers see a Bad value: purchase_currency error instead of the checkout.
Configuration
↑ Back to top- Go to: WooCommerce > Settings > Payments > Kustom Checkout > Manage.
- Enable Kustom Checkout by checking the Enable Kustom Checkout checkbox.
- Title – Enter the title for the payment method displayed in the checkout and order confirmation emails.
- Description – Enter the description of the payment method displayed in the checkout page.
- Other payment method button text – Customize the Select another payment method button text that is displayed in checkout if using other payment methods than Kustom Checkout. Leave blank to use the default (and translatable) text.
- Test mode – Check Enable Test Mode to use your test (Playground) API credentials for test purchases. This is the plugin’s own setting and is not related to WooCommerce’s Site Visibility setting.
- Logging – Check Log debug messages to save debug messages to the log, found under WooCommerce → Status → Logs. Recommended: support will ask for the log, and it has to be on before an issue happens.
- Checkout layout – Choose between One column checkout, Two column checkout with Kustom Checkout in the right or the left column, and Two column checkout (Kustom Checkout in left column) – Storefront light.
API credentials
↑ Back to topKustom has two separate environments, each with its own login and its own credentials: Playground (test) and Production (live). In the Kustom Portal for the environment you want, go to Developers → API and click Generate new. Copy the Key ID (the API Username in the plugin) and the Password (the API Password in the plugin). The password is only shown once. These credentials are not your Merchant ID (MID) or your Kustom Portal login.
- Production Kustom API Username – The Key ID from the production Kustom Portal.
- Production Kustom API Password – The Password from the production Kustom Portal.
- Test Kustom API Username – The Key ID from the Playground Kustom Portal (create a Playground account if you don’t have one).
- Test Kustom API Password – The Password from the Playground Kustom Portal.
If you previously entered credentials for both Europe and the United States, the plugin now uses your European credentials.
Shipping settings
↑ Back to top- Separate shipping address – Tick this checkbox if you want to allow customers to use a shipping address that is not the same as their billing address.
- Shipping methods in iframe – If checked, the shipping method is selected in the Kustom Checkout iframe. Must be checked if you use Kustom Shipping Assistant, and should not be checked if you use a shipping plugin with additional shipping options for the customer.
- Shipping details – Additional shipping information that will be displayed to customers in the Kustom Checkout iframe after they have placed an order.
Checkout settings
↑ Back to top- Product URLs – Tick the checkbox if you want to send product and product image URLs to Kustom.
- Date of birth mandatory – Tick this checkbox if you want to make it mandatory for customers to enter their date of birth during checkout.
- National identification number mandatory – If checked, the customer has to complete a validation of their national identification number (SE, NO, FI and DK only).
- Checkout privacy policy text – Choose if, or where, the checkout privacy policy text is displayed.
- Terms and conditions checkbox – Add a terms and conditions checkbox inside the Kustom Checkout iframe.
- Allowed Customer Types – Choose whether you sell to consumers (B2C), to businesses (B2B), or both.
- Title mandatory (GB) – Check this to make customer’s title mandatory, only works for customers based in GB.
- Show prefill consent notice – Check this to prevent logged-in customers’ data from being sent to Kustom, only applicable for customers from Germany and Austria.
- Display quantity fields – Let customers change product quantities on the checkout page, the same way as in the cart.
- Display subtotal details – Show subtotal details in the WooCommerce order review, in the Kustom Checkout iframe, or in both.
Color settings
↑ Back to topWith the Color settings section, you have the possibility to alter the appearance of the Kustom Checkout iframe displayed in the checkout. Here you can change things like background colors, button colors and text colors.
Kustom Order Management
↑ Back to top- Enable order management – Checked by default. Lets WooCommerce capture, cancel, update and refund Kustom orders. Uncheck it if you manage orders in the Kustom Portal; refunds must then be registered in WooCommerce with Refund manually.
- On order completion – Captures the Kustom order when the WooCommerce order is set to Completed. The plugin does not support partial captures.
- On order cancel – Cancels the Kustom order when the WooCommerce order is set to Cancelled.
- On order update – Updates the Kustom order when the WooCommerce order is changed before it has been captured or cancelled.
- On order creation (manual) – Fetches the customer’s details for a manually created admin order that has a Kustom order ID as its transaction ID.
- Force capture full order – Captures any remaining amount on the Kustom order instead of each order line separately. Useful if the Kustom order has been updated by an ERP system.
Kustom Shipping Assistant
↑ Back to topYour Kustom account must be activated for Kustom Shipping Assistant (KSA) with a transport management system (TMS) before you use these settings. Contact Kustom merchant support if you’re unsure. KSA works on top of WooCommerce shipping, so every zone you use it in still needs at least one ordinary WooCommerce shipping method.
- Enable Kustom Shipping Assistant – Check this box to activate KSA.
- Enable shipping option update callback – Optional. Check this if your TMS sends the wrong tax rate, to let WooCommerce calculate the tax on shipping instead.
Elements
↑ Back to topKustom Elements display Kustom payment methods, delivery options and express buttons on your store pages. They use public API keys, which are separate from the API credentials above. Find them in the Kustom Portal under Apps → On-site elements → Installation script (the value of data-public-api-key).
- Production public API key and Test public API key – Used when test mode is disabled and enabled respectively.
- Payment Method Display – Where the available Kustom payment methods are shown on product and cart pages.
- Delivery Method Display – Where the available delivery options are shown on product and cart pages. Requires Kustom Shipping Assistant.
- Express buttons – One-click Apple Pay, Google Pay and Klarna purchases on product, cart and checkout pages. Requires Kustom Shipping Assistant. Paste the Express merchant URLs shown here into the Kustom Portal under Apps → On-site elements → Express buttons. Read more about Kustom Express Checkout.
Subscription support
↑ Back to topKustom Checkout is compatible with the WooCommerce Subscriptions extension and supports automatic recurring payments. Recurring payments must be enabled on your Kustom account, so contact Kustom merchant support before you start. Recurring orders show a smaller set of payment methods, as financing options are not available for them.
Read more about recurring payments with Kustom here.
Customizations
↑ Back to topIn some cases you might need to change how Kustom Checkout is displayed in the checkout or modify the data sent from WooCommerce to Kustom. Here are a couple of articles describing how to modify your Kustom Checkout setup:
- Modify the display of the checkout via Hooks (actions and filters).
- External Payment Methods.
- Extra Merchant Data.
Before you Go Live
↑ Back to top- Test first with Enable Test Mode checked and your Playground credentials. Complete a purchase using test data, then check that the order appears in WooCommerce and in the Playground Kustom Portal with the same amount. A Processing order in WooCommerce should be Authorized in Kustom, and a Completed order should be Captured.
- To go live, enter your production credentials in the Production fields, uncheck Enable Test Mode and save. Place a real, low-value purchase, confirm it in the Kustom Portal with a total that matches WooCommerce, and refund it afterwards.
- Kustom Checkout should be the first/default payment method (if multiple payment methods are active), since the Kustom Checkout iframe is only shown when it is the selected payment method. This can be adjusted in → WooCommerce → Settings → Payments.
Compatibility with themes & plugins
↑ Back to top- Kustom Checkout uses its own template file for displaying the checkout page and should work with most themes. However, the plugin is only regularly tested with the Storefront theme and we do not guarantee that it will work with other themes. Common situations when errors occur are:
– Themes/plugins with customized template files for WooCommerce checkout page.
– Themes/plugins that modify the checkout into a multi step checkout. - The plugin supports both the classic checkout shortcode and the WooCommerce Checkout block (from version 2.16.0), as well as High-Performance Order Storage (HPOS).
- The plugin and Kustom only handle product quantity that is specified as an integer. For instance you can’t send 1.5 as the product quantity to Kustom. If you sell products where you charge by length or dimension we recommend that you use the Measurement Price Calculator plugin.
- WooCommerce does not offer multi currency support on its own. This can be handled via several different plugins. Confirmed compatible plugins include Aelia Currency Switcher for WooCommerce, WOOCS – WooCommerce Currency Switcher and WooCommerce Multilingual (WPML). See the full list of compatible plugins. We do not guarantee that other multi currency plugins will work together with the Kustom plugin.
Krokedil and Kustom do not offer help with adapting your theme or plugin within regular support. For plugin and integration questions, contact Krokedil support. For questions about your Kustom account, a specific purchase or a payout, contact Kustom merchant support at support@kustom.co.
