Hokodo Payments

1. Introduction

Hokodo is a B2B payments platform that lets you offer Buy Now, Pay Later trade payment terms to your customers. Once integrated, customers can opt to pay in instalments as well as choose their preferred payment methods such as Pay on Invoice or Direct Debit. Learn more about Hokodo

2. How it works

The Hokodo integration for SparkLayer is available for all Shopify merchants and enables an additional payment method in the SparkLayer Quick Order Interface that lets customers choose from a range of special B2B payment terms.

The integration works by first asking the customer to search for their Company, validating their Company details, and then determining if payment terms can be offered. If successful, the customer can choose from a variety of instalment options and then complete the checkout process as normal.

Once in the checkout, the customers' order will be processed with a 'zero value' total and payment is then captured via a post-purchase confirmation screen (powered by Hokodo) that asks them to confirm their payment plan and choose their payment method.

Once done, the order is complete and is then processed just like any other order on your website.

3. Configuring on SparkLayer

Before you start To configure Hokodo on SparkLayer, you'll need to have an approved account with Hokodo. Please visit the Hokodo website to learn more.

Once your Hokodo account has been approved, you're ready to activate it on SparkLayer! Within the SparkLayer Dashboard, go to the Configuration section, click Integrations, and then click the Partners tab.

Under Payment providers, click the toggle on the right to activate the Hokodo integration.

You'll then be prompted to enter in the API Key supplied by Hokodo. If you don't have one already, please contact Hokodo directly. If you're testing Hokodo using their Sandbox Environment, you can optionally activate this too.

Once you've added your API Key, the Hokodo integration is now activated. If you need to deactivate the integration or update your API Key, you can do so by clicking the toggle or the Modify button.

4. Configuring on Shopify

4.1. Shopify checkout

When the Hokodo integration for SparkLayer is activated, any customer that logs into your website will then see Hokodo as a payment option in the SparkLayer Quick Order Interface.

Within Shopify, it's necessary to adapt the checkout to enable the post-purchase Hokodo confirmation screen to allow customers to successfully complete their order.

To configure this, within the Shopify admin, go to Settings and click Checkout. Under Order Processing, add the following into the Additional scripts box. This code snippet enables the overlay that loads on the order completion page of the Shopify checkout and also allows you to adjust the styling via CSS should you wish.

Shopify checkout code
Shopify checkout code
{% if checkout.attributes.hokodoPaymentUrl and checkout.attributes.hokodoOfferId %}
<style>
.spark-hokodo__popup {
position: fixed;
top: 12%;
left: 15%;
width: 70%;
height: 70%;
background-color: white;
z-index: 10;
}
.spark-hokodo__popup--iframe {
width: 100%;
height: 100%;
border: 0;
}
.spark-hokodo__bg {
position: fixed;
z-index: 5;
left: 0;
top: 0;
width: 100%;
height: 100%;
overflow: hidden;
background-color: rgba(0, 0, 0, .75);
}
@media only screen and (max-width: 1000px) {
.spark-hokodo__popup {
top: 8%;
left: 0;
width: 100%;
height: 84%;
}
}
</style>
<script>
const hokodoOfferId = {{ checkout.attributes.hokodoOfferId | json }};
async function sparkHokodoCheckHasBeenAccepted() {
const response = await spark.fetch(
'query planAccepted($offerId: String!) {integrationHokodoIsPlanAccepted(offerId: $offerId)}',
{offerId: hokodoOfferId}
);
const responseData = await response.json();
if (responseData.data.integrationHokodoIsPlanAccepted) {
document.getElementById('spark-hokodo').remove();
} else {
window.setTimeout(sparkHokodoCheckHasBeenAccepted, 3000);
}
}
window.setTimeout(sparkHokodoCheckHasBeenAccepted, 3000);
</script>
<div id="spark-hokodo">
<div class="spark-hokodo__popup">
<iframe class="spark-hokodo__popup--iframe" src="{{checkout.attributes.hokodoPaymentUrl}}"></iframe>
</div>
<div class="spark-hokodo__bg"></div>
</div>
{% endif %}

4.2. Shopify Plus: Checkout

In order for Hokodo to show as a payment method for B2B customers, merchants using Shopify Plus need to action the following steps.

First, Hokodo needs to be added as a Manual payment method within the Shopify payment options. When a customer reaches the checkout, the checkout will automatically assign this payment method.

Secondly, to activate this payment method in the checkout, it's necessary to adjust the code in checkout.liquid to correctly display this as an option. Within the checkout.liquid file, the following code needs to be added.

checkout.liquid
checkout.liquid
{% comment %}SparkLayer B2B - Checkout Payment Start{% endcomment %}
{% if customer.tags contains 'b2b' %}
<script>
const sparkPaymentMethod = {{ checkout.attributes.sparkPaymentType | json }};
const mapSparkPaymentMethodToShopify = {
paymentByInvoice: 'Payment By Invoice',
hokodoPayment : 'Buy Now, Pay Later with Hokodo',
paymentOnAccount: 'Payment On Account',
// upfrontPayment is handled seperately and all manual methods are removed
};
if (sparkPaymentMethod === 'upfrontPayment') {
// For upfrontPayment remove all other payment methods!
document.querySelectorAll("[data-payment-subform=required] fieldset>div[data-gateway-group=manual]").forEach(method => method.remove());
} else {
document.querySelectorAll("[data-payment-subform=required] fieldset>div").forEach((method) => {
methodName = method.querySelector('.radio__label label')?.textContent?.trim() || '';
if (mapSparkPaymentMethodToShopify[sparkPaymentMethod] !== methodName) {
// Remove Payment Method
method.remove();
}
});
// Now preselect the an option
document.querySelector('div[data-gateway-group=manual] input').setAttribute('checked', 'checked')
}
</script>
{%endif%}
{% comment %}SparkLayer B2B - Checkout Payment End{% endcomment %}

For merchants using Shopify Plus, it's possible to apply more extensive customisations to the checkout process such as adjusting messaging, layout, and styling. You can learn more about how this works with our full guide here.

For customers paying via Hokodo, it's also possible to toggle content by using special tags that can be added at the different steps of the checkout process in the checkout.liquid file.

Sample checkout.liquid code
Sample checkout.liquid code
{% if checkout.attributes.hokodoPaymentUrl and checkout.attributes.hokodoOfferId %}
<!-- Do specific Hokodo actions here -->
{% endif %}

4.3 Shopify Plus: Shopify Flow

Shopify Plus merchants also get access to a feature called Shopify Flow that lets you apply actions based on certain rules (see our guide here). For customers paying via Hokodo, it's possible to add tags to an order that allow easier filtering and reporting within the Shopify admin.

Within Shopify Flow, you can configure the work flow based on 'Custom Attributes' that get added to any order placed via Hokodo. In the screenshot below, the flow is mapped by using a custom attribute key of sparkPaymentType and a custom attribute value of hokodoPayment.

Once you've configured this criteria, you can then apply actions such as tagging an order, sending an email, or any other action Shopify Flow supports.

4.4. Custom URLS

When the Hokodo widget is loaded, there are a number of links that allow customers to learn more about the service. These will go to predefined URLs so it's necessary to create redirects within Shopify to ensure they direct customers to the correct page on your website.

Within Shopify, go to Online Store, Navigation and click View URL redirects. You'll need to set up redirects for the following:

URL

Destination URL

/spark-redirect/hokodo-terms

Custom page on your site that details the Hokodo terms and conditions, e.g. /pages/hokodo-terms

/spark-redirect/hokodo-bnpl

Custom page on your site that explains how Hokodo works, e.g. /pages/hokodo-bnpl

5. Managing orders

When a customer places an order using Hokodo as a payment method, it will funnel through to your Orders admin just like any other. If you're using Shopify, you'll see extra data included within the 'Additional Details' section when viewing an order. This data can be sent through to your backend system and allow you to see specific Hokodo information on a per-order basis.

If you're using Shopify Plus, you can customise orders with tags and order notes using Shopify Flow. Please refer to our guide here.

Hokodo may flag orders as high risk and you will be notified via Hokodo regarding any affected orders. These will continue in the order flow as normal.

If your backend system (e.g. ERP, CRM) already integrates with SparkLayer, you may need to make some small adjustments to ensure Hokodo-related data is passed through correctly. Please contact us and we'll be happy to advice.

6. Known limitations

Please note the following:

  • The Hokodo integration only supports UK / France companies with more coming soon

  • For the UK only Registered Companies can use Hokodo (i.e. those listed on Companies House)

  • Payment by card is not supported at this point.

  • Hokodo is not Payment Type option within Customer Groups and is enabled by default for all customers (this will be supported in future releases)

7. Requirements

Item

Notes

eCommerce Platform

Merchants must be using Shopify or Shopify Plus (all Plans)

Payment Methods

Support for Pay on Invoice and Pay by Direct Debit (Pay by Card coming soon)