Documentation

Shopify

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

Considerations Before You Begin

Our Koalafi Shopify plugin uses an older version of the Shopify payment gateway. That is because for lease-to-own, we require sku level (item level) information and newer versions of Shopify’s gateway do not provide sku level data. The Shopify payment gateway version has the following limitations you should consider before integrating:

  1. Some manual reconciliation is required for the merchant in regards to taxes.
    1. There is no way to remove tax from the order total after the system recognizes that a customer paid with Koalafi. This means that an order that is paid for by Koalafi will show up in the merchant’s order list as {order total + tax} however, Koalafi will only fund the merchant for the order total since Koalafi pays the tax for these purchases.
  2. This Shopify payment gateway version also records a payment capture error if the customer closes out of the modal before they complete their financing application. The customer can still reopen and finish applying, but the Shopify error messaging can be a point of confusion.
  3. The Shopify one page/streamlined checkout experience is not supported by this version of the payment gateway.

Installation

Integrating with Koalafi's Shopify plugin requires installing two software components:

  1. ChargeAfter Payment Gateway
  2. Koalafi Financing App

ChargeAfter Payment Gateway

  1. Provide your Koalafi contact your store name, Shopify URL, and a .png file of your company's logo
  2. After creating the necessary credentials, your Koalafi contact will send you an email with the following details:
    1. The link to install the ChargeAfter Payment Gateway (both sandbox and production installations)
    2. The link to install the Koalafi Financing App
    3. Public API keys (both sandbox and production keys)
    4. Private API keys (both sandbox and production)
    5. provide you with links where you can download the ChargeAfter Payment Gateway as well as the . There will be one link for the sandbox gateway, and another for the production gateway.
  3. When you click the link, you will be prompted to login to your Shopify store and you will see a prompt asking you to install the ChargeAfter Payment Gateway.

👍

Tip for Success!

We recommend installing the ChargeAfter sandbox gateway on an unpublished theme where your customers will not see it, allowing you to test before going live.

  1. Click Install payment provider.
  2. From your store’s admin site navigate to Settings > Payment providers.
  3. Scroll down to the Alternative payments section and click Select additional payment method.
  4. Select ChargeAfter from the list.
  5. Under Public Key and Private Key enter your corresponding credentials
    1. For sandbox installation, make sure to use the sandbox keys
    2. For production installation, make sure to use production keys

👍

Tip for Success!

If you're using the ChargeAfter Sandbox Gateway to test, check the Use test mode box to ensure that no orders are tracked in your Shopify store.

  1. Click Save. ChargeAfter Payment Gateway is now installed.

Install the Koalafi App

  1. Navigate to the Koalafi App link that your Koalafi contact provided
  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.
    1. Note that by installing this application, you are granting Koalafi permission to view and modify orders. This permission allows us to get the product and payment from your orders into the eCommerce application.
  5. In the side panel click Apps. The Koalafi app should now be in your list of Apps.
  6. Once installation is complete, reach back out to your Koalafi contact to have the ChargeAfter Payment Gateway activated before moving on to the next step.

Adding Promotional Tools

Koalafi provides the following promotional tools:

  1. Product Page Widgets - A widget to be displayed on the product page, near the product price. It serves two purposes:
  • First, if a customer selects 'See How' they can read more about Koalafi and see an example payment schedule before applying for a prequalification.
  • Second, if customers select 'Prequalify Now' they have the option to get prequalified without leaving the product page.

Apply Now Buttons - A button to be displayed on your financing page that allows customers to enter the prequalify first flow (where they will receive a prequalification amount they can later use at checkout)

👍

Tip for Success!

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. Name your widget koalafi-widget.liquid and click Create snippet. You should now see koalafi-widget.liquid in the Snippets folder.
  6. In the koalafi-widget.liquid file you just created, 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 Production Public Key.
  2. Save the file.

📘

Sandbox Testing

  • Use this code block instead of the one above to test in your sandbox environment
  • Make sure to use your sandbox public-api-key in place of the prod key for sandbox installation
<script type="text/javascript">
var caConfig = {
apiKey: 'sandbox-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-sandbox.ca-dev.co/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. Scroll up to the Layout folder and open your theme layout file, which by default is theme.liquid.
  2. Insert the following line of code above the closing head tag :{% include 'koalafi-widget' %}

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>

👍

Tip for Success!

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 Apply Buttons

The Koalafi Apply button is intended to be displayed on a Financing Page allowing the customer to apply first before they get to the checkout flow.
Follow these steps to add the Koalafi apply button.

  1. On the Themes page, find the theme where your financing page exists.
  2. Next to the theme name, click Actions > Edit code. The code editor page opens.
  3. On your Financing Page (must be within Shopify site) create a button that says "Apply Now" and give it a unique id. An example Apply Now button is shown in the HTML code below.

👍

You can have as many Apply Now buttons as you like, but give them all unique ids!

<div class="apply-button-container">
   //This button and all subsequent  should have a unique ids
   <button id="koalafi-apply-button" class="apply-now-button">APPLY NOW</button>
</div>
  1. Create an event listener to listen for clicks of your buttons. Within this event listener, you will call ChargeAfter.apply.present() function. See example code below.
  //Remember to replace this id with the id you chose for your button
  document.getElementById('koalafi-apply-button').addEventListener('click', () => {
      ChargeAfter.apply.present();
   })

Product Configuration

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:

Giving a product a SKU

All products are required to have a SKU for the Koalafi App to work correctly.

Follow these steps to add a SKU to a product:

  1. From the admin site go to the product details page.
  2. In the Inventory section you will see an input for SKU. Add a SKU to this field.
  3. Repeat for all products in e-commerce store.

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:

Troubleshooting

If you're running into errors during installation verify you have the following configurations set up correctly.

App and API keys mismatch

If you installed the ChargeAfter gateway sandbox version, make sure you are using your sandbox API keys. The prod keys will not work with the sandbox app and vice versa.

  • Check your API keys in the app settings
  • Check your API key in the koalafi-widget.liquid file

Missing SKU on products

If you are unable to launch Koalafi at checkout, verify that you have SKU numbers on your products. This is a required field to be compatible with the Koalafi Shopify app.

Waiting for ChargeAfter activation

After you install the Payment Gateway, ChargeAfter will need to activate you store on their end. Once you've done this step, please reach out to us and we will ask them to activate your store so that you can proceed with the rest of the installation.

Updated 11 months ago