Shopify

BETA version

This guide describes how to integrate Koalafi's ChargeAfter financing solution to your Shopify store. It covers
the following topics:


Installation

Integrating ChargeAfter’s financing solution requires installing two software components:

  1. ChargeAfter Payment Gateway
  2. Koalafi Financing App

Install ChargeAfter Payment Gateway

  1. Request a link to download the ChargeAfter Payment Gateway from your contact at Koalafi
  2. After logging into your store, a prompt will pop up, asking you to install ChargeAfter Payment
    Gateway.
  3. Click Install payment provider.
  4. From your store’s admin site navigate to Settings > Payment providers.
  5. Scroll down to the Alternative payments section and click Select additional payment method.
  6. Select ChargeAfter from the list.
  7. Check the Use test mode box to connect to the Gateway’s Sandbox environment. Leave the box unchecked to connect to the production environment.
  8. Under Public Key and Private Key enter your Sandbox or Production merchant keys, based on
    your selection in the previous step.
  9. Click Save. ChargeAfter payment method will now be activated.

Install the Koalafi App

There are two separate ChargeAfter apps:

  • One connects your store to Koalafi production
    environment, and
  • The other to the sandbox (test) environment.

If you are using separate stores for test and production, you only need to install the relevant Koalafi app for each store.

Follow these steps to install either app:

  1. From your browser, request the following URLs from Koalafi
    1.1. Koalafi - Production app:

    1.2. Koalafi - Sandbox app:

  2. If you are not already logged in to your store’s admin, you will be asked to log in.

  3. Once you are logged in, the Koalafi Installation page will be loaded in your admin site.

  4. Click Install unlisted app to install the Koalafi app.

  5. In the side panel click Apps. The Koalafi- Production or Koalafi-Sandbox app should
    now be in your list of Apps.


Adding Promotional Tools

Koalafi provides the following promotional tools:

  1. Promotional Banners - An advertising message within a box that makes your store visitors aware of the availability of promotional financing. It is written in a large font and it includes Koalafi's logo.
  2. Promotional Widgets - A widget to be displayed next to the product price. It serves two purposes:
  • First, it informs shoppers that they can select Koalafi financing as a payment method.
  • Second, it can be configured to show the lowest possible monthly payment, given the promotional financing that is available.

This section of the guide explains how to add the promotional tools to your Shopify Store. For more detailed information about the tools, please view the Promotional Widget section.

🚧

Adding promotional tools involves making changes to your store’s Theme code. The steps outlined in the next subsections need to be repeated for each theme where you want the promotional tools to be included.

Configuring your theme for adding Koalafi promotional tools

From your Shopify Admin Site click Online Store, follow the below steps:

  1. Click Themes to go to the Themes page.
  2. On the Themes page, find the theme where you want to add Koalafi promotional tools.
  3. Next to the theme name, click Actions > Edit code. The code editor page opens.
  4. From the code editor directory scroll down to the Snippets folder and click Add a new snippet. The Add a new snippet dialog pops up.
  5. Enter XXX-widget and click Create snippet. A new file with the name XXX-widget.liquid will be added to the Snippets folder.
  6. Open the file XXX-widget.liquid you just created.
  7. In the code section copy and paste the following code:
<script type="text/javascript">
var caConfig = {
apiKey: 'public-api-key'
};
!function(e,t,c,a,n){var r,o=t.getElementsByTagName(c)[0];
t.getElementById(a)||(e.ChargeAfter={cfg:n},(r=t.createElement(c)).id=a,
r.src="https://cdn.chargeafter.com/promotional-widget/v2/widget.min.js?t="+
1*new Date,r.async=!0,o.parentNode.insertBefore(r,o))}
(window,document,"script","chargeafter-promotional-widget",caConfig);
</script>
  1. In the line apiKey: 'public-api-key' replace ‘public-api-key’ with your merchant Production Public Key.
  2. Save the file.
  3. Scroll up to the Layout folder and open your theme layout file, which by default is theme.liquid.
  4. Insert the following line of code above the closing head tag :{% include 'XXX-widget' %}

Adding Promotional Banners

  1. Adding the Promotional Banner to your Shopify home page
    The steps to add Koalafi promotional banner to the home page vary between Sectioned and Non-sectioned themes.

Instructions for Non-sectioned Themes

  1. On the Themes page, find the theme where you want to add Koalafi promotional banner.
  2. Next to the theme name, click Actions > Edit code. The code editor page opens.
  3. From the code editor directory, open the file index.liquid located under the Templates folder.
  4. Insert the following code wherever you want to display Koalafi promotional banner:
<div class="ca-widget" style="height:100%;width:100%">
<div class="ca-promotional-widget" data-widget-type="banner-type">
</div>
</div>
  1. In the code above, replace “banner-type” with the type of banner you wish to display. Please refer to the section Adding Promotional Widgets to a Page of our Documentation for a list of banner type names and the corresponding images.
  2. In the code above, change the height and width percentages to adjust the size of the banner to as needed.
  3. Click Save to keep your changes.

Instructions for Sectioned Themes

  1. On the Themes page, find the theme where you want to add Koalafi promotional banner
  2. Next to the theme name, click Customize. This will take you to the Theme Editor.
  3. In the top bar of the Theme Editor, select Home page from the page selection list
  4. In the Theme Editor sidebar, go to the Sections tab
  5. Click Add section
  6. Scroll to the bottom and under ADVANCED LAYOUT select Custom content and click Add
  7. Delete the placeholder text under Heading
  8. Under CONTENT click Custom HTML to expand it
  9. Insert the following code in the HTML text box:
<div class="ca-widget" style="height:100%;width:100%">
<div class="ca-promotional-widget" data-widget-type="banner-type">
</div>
</div>
  1. In the code above, replace “banner-type” with the type of banner you wish to display. Please
    refer to the section Adding Promotional Widgets to a Page of Koalafi Documentation for a
    list of banner type names and the corresponding images.
  2. In the code above, change the height and width percentages to adjust the size of the banner to
    your liking
  3. Click Save

Adding Promotional Banner to other Shopify pages.

We recommend adding a promotional banner to the following Shopify pages:

  • Collection List
  • Collection
  • Product
  • Cart

The steps below apply to all of your Shopify store pages aside from the home, password and checkout
pages.

  1. On the Themes page, find the theme to which you want to add Koalafi promotional
    banner
  2. Next to the theme name, click Actions > Edit code. The code editor page opens.
  3. From the code editor directory, open the Template file corresponding to the page where you are adding the banner. For sectioned themes this file will be located under the Sections folder. For non-sectioned themes, it will be located under the Templates folder.
  4. Insert the following code wherever you want to display Koalafi promotional banner:
<div class="ca-widget" style="height:100%;width:100%">
<div class="ca-promotional-widget" data-widget-type="banner-type">
</div>
</div>
  1. In the code above, replace “banner-type” with the type of banner you wish to display. Please
    refer to Adding Promotional Widgets to a Page for a list of banner type names and the corresponding images.
  2. In the code above, change the height and width percentages to adjust the size of the banner to your liking

Adding Promotional Widgets

The promotional widget is intended to be displayed in the Product page, next to the product’s price.
Follow these steps to add the Koalafi promotional widget.

  1. On the Themes page, find the theme to which you want to add Koalafi promotional tools.
  2. Next to the theme name, click Actions > Edit code. The code editor page opens.
  3. From the code editor directory, open the Template file for your product page content. For non-sectioned themes this file will be located under the Sections folder. For Non-sectioned themes,
    it will be located under the Templates folder.
  4. Insert the following HMTL code wherever you want to display Koalafi promotional widget. It is strongly recommended to add the widget close the product’s price:
<div class="ca-promotional-widget" data-widget-type="widget-type"
data-widget-item-sku="{{ product.selected_or_first_available_variant.sku
}}" data-widget-item-price="{{
product.selected_or_first_available_variant.price | money_without_currency
| remove: ',' }}">
</div>

🚧

It is strongly recommended to add the widget in close proximity to the product’s price

  1. In the code above, replace “widget-type” with the type of widget you wish to display. Please
    refer to the Adding Promotional Widgets to a Page section for a list of widgets types available.

Adding Block Promos for Themes Online 2.0

The manual below is for merchants with Themes Online 2.0 and includes Line of Credit Promo only.
Merchants with legacy theme structures may use the Adding Promotional Tools guide.

Installation

  1. In the store’s admin site, navigate to the Online Store > Themes > Customize:

  1. On the Customize page, click the Home page list > Products template:

  1. In the workspace, hover over the price and click the small plus sign icon:

  1. Add a Line of Credit Promo Block from the app list:

  1. Go to the Financing Page in the far right column (from the list of Shopify pages) > Save:

  1. You're done!


Tagging a Product as Non-Leasable

Specifying whether a product is leasable is required when offering a lease-to-own financing option with Koalafi. Non-leasable products generally include weapons and non-physical goods such as gift cards, service fees, warranties or installation fees. The Koalafi app treats all products as leasable by default, so you'll need to update any product that falls into the non-leasable category.

Follow these steps to tag a product as non-leasable:

  1. From the admin site go to the product details page.
  2. In the Organization section, under Tags, enter the words “no leasable” and press Enter.

The product should now be tagged as no leasable, as shown below:


Post Order Operations

A charge is created after a consumer completes an order using Koalafi as a payment option. The charge will be in AUTHORIZED status initially. An entry with information about the charge will be added to the Timeline in the Order page of the store’s admin site. The entry title will say $XXX.XX was authorized on XXX, as shown below:

Click the entry title to expand the entry. Click again to expand the Information from the gateway. Under X message you can find the name of the Lender and the charge ID, as shown below

The following post-order transactions can be performed on a charge from your Shopify store’s admin site.

Settling a charge

A charge can only be settled (captured) once and in full.

Follow these steps to settle a charge:

  1. In the store’s admin site, go to the order’s page.
  2. Click Capture Payment. The Capture Payment dialog pops up. The amount on the text box is the charge total. For orders made through a lender that provided an open line of credit, the charge total will be equal to the order total. For lease-to-own orders, the charge total will exclude sales tax.
  3. Click Accept $XXX.XX

Two new entries will be recorded in the Order’s Timeline:

  1. The first entry will say A $XXX.XX USD capture is pending on Koalafi
  2. The second entry will say $XXX.XX USD was captured on Koalafi

📘

Note that it may take several minutes for the second entry to be added to the timeline.

Once the two entries are added, the Timeline should look as follows:

The settle transaction ID will appear in the second entry (the one on top). You can find it in the Information from the gateway under X message as shown below:

Refunding a charge

A charge can be refunded either partially or fully. Multiple partial refunds can be issued.

Follow these steps to refund a charge:

  1. In the store’s admin site, go to the order’s page
  2. At the top of the page click Refund items
  3. Select the items you wish to refund
  4. Under Refund shipping enter the shipping amount you wish to refund
  5. Go to the Summary section. The REFUND AMOUNT should be updated accordingly.
  6. Click Refund $XXX.XX

Two new entries will be recorded in the Order’s Timeline.

  1. The first entry will say A $XXX.XX USD refund is pending.
  2. The second entry will say You refunded $XXX.XX USD on ChargeAfter.

📘

Note that it may take several minutes for the second entry to be added to the timeline.

Once the two entries are added, the Timeline should look as follows:

The refund transaction ID will appear in the second entry. You can find it in the Information from the gateway X Messages as shown below:

Voiding a charge

Cancelling an order that was placed through Koalafi has the effect of voiding a charge.

Follow these steps to void a charge:

  1. In the store’s admin site, go to the order’s page.
  2. At the top of the page click More actions and select Cancel order. The Cancel order dialog pops up. Please do not change the Shipping amount.
  3. Click Cancel order.

Two new entries will be recorded in the Order’s Timeline.

  1. The first entry will say Void of a $0.00 USD authorization is pending.
  2. The second entry will say You voided the authorization on Koalafi.

📘

Note that it may take several minutes for the second entry to be added to the timeline.

Once the two entries are added, the Timeline should look as follows:

The refund transaction ID will appear in the second entry. You can find it in the Information from the gateway X Messages as shown below: