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

  1. You may be required to do manual reconciliation for sales tax on the purchases on your site paid for with Koalafi.
    1. Why? You are not responsible for remitting taxes on purchases paid for using Koalafi; Koalafi remits the tax for these purchases. However, in your Shopify order system, you will still see a sales tax amount associated with the purchase because Shopify does not retroactively zero out the sales tax on Koalafi orders. This means you may have to complete some manual reconciliation for orders paid for with Koalafi to ensure you do not remit sales tax you do not owe.
    2. Note that Koalafi will fund you for the purchase amount not including the sales tax since you are not responsible for paying the sales tax on purchases paid for with Koalafi.
  2. Payment Processing Type
    1. You will need make sure your your payment processing type is set to “Automatically when order is fulfilled”. This captures payment and activates the lease at the time of shipping instead of at successful checkout.
      1. Note that when you change this setting, it will change the payment capture for all of your payment types.
    2. Instructions on how to change your payment processing type can be found at <https://help.shopify.com/en/manual/payments/payment-authorization#set-up-manual-payment-capture>
  3. SKU
    1. Our plugin uses SKU to capture product details such as price needed for financing. Ensure all products have a valid SKU populated before installation.

Credential Generation

We need the following details in order to begin API key generation. Please reach out to your Koalafi contact with the information listed below.

Required information

  1. Your Shopify URL
  2. A PNG of your company logo

Turn around time for API credentials: ~5 business days after you provide your Shopify URL & company logo you can expect to receive a follow up email with credentials required for installation.


Installation

  1. Navigate to the Koalafi App in the Shopify app store
  2. Click the "Install" button and login to your store. You will be redirected to the installation page.
  3. You will be redirected to the payment gateway settings page after installation. If you need to return to this screen, you can do so by going to Settings > Payments > Additional payment methods > Payment Method by Koalafi.
  1. Click on the Manage button.
  2. Enter the public and private API keys in the prod fields in the Settings panel. Ensure "Enable Sandbox Mode" is not checked. Save Changes.
  3. You will be redirected to the Payment Methods screen. Click Activate under the Koalafi app.
  4. Congrats! The Koalafi plugin is now successfully installed on your site!

Adding Promotional Widgets

Promotional widgets help ensure that your customers are aware that your store has financing options available. These promotional widgets are often displayed on your product pages next to the price and on a dedicated financing page that provides more information about the financing options you offer.

Product Page Widgets

Widgets can be added to product pages to inform customers that financing with Koalafi is an option. They are a great way for customers to learn more about Koalafi without even having to leave the product page.

The Product Page Widget has the following 2 features:

  1. If a customer clicks Learn More they can learn more about Koalafi
  2. If a customer clicks Prequalify Now they can choose to get prequalified right on the product page and learn if they have a prequalified amount with Koalafi. Then they can continue shopping and adding items to their cart and look up their prequalified application at Checkout to complete their purchase and pay with Koalafi.

Adding Koalafi Widget to the Product Page

Add Promotional Widgets using Theme Online 2.0
You must use Theme Online 2.0: https://shopify.dev/themes/os20

❗️

Shopify Online Store 2.0

Note this requires Online Store 2.0 for installation. If your site is unable to upgrade to this version, see manual instructions below.

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

  1. Navigate to the Online Store > Themes > Customize
  2. On the Customize page in the Home page drop-down list, select the Products or Cart page template:
  3. In the workspace, hover over the price and click the small plus (+) icon (or click on Add block on left sidebar)
  4. Add Promotional block from the app list
  5. Move this widget to where you'd like it to appear under the product.
  6. Click on the Promotional Block you just created to open the settings on the right hand side of the page.
  7. Choose Promotional Type as Default Template
  8. Click Select on the Financing Page option to link your financing page to the widget.
  9. Save and publish the theme.

Manual Installation

🚧

Configure

You must configure your theme before adding a widget manually.

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. Scroll up to the Layout folder and open your theme layout file, which by default is
    theme.liquid.
  5. Insert the following line of code above the closing head tag :
<script src="{{ 'https://sh.chargeafter.com/1f8616d5edae1b8e4d52cc8b32a0875a
/promo/widget.min.js?shop=' | append: shop.permanent_domain }}" async></script>

Installation of 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 or cart page content.
    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 HTML code wherever you want to display Koalafi promotional widget:
    Widget for product page:
<div class="ca-promotional-widget" data-widget-type="default-template" datawidget-item-sku="{{ product.selected_or_first_available_variant.sku }}" datawidget-item-price="{{ product.selected_or_first_available_variant.price |
money_without_currency | remove: ',' }}" data-widget-financing-pageurl="financing-page"> </div>

👍

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.


Finance Page - Prequalify Now Buttons

This promotional widget is a button that can be displayed on your financing page. This button will allow customers to enter the application flow and receive a prequalification amount they can later use at checkout.

Adding Prequalify Buttons

The Koalafi Prequalify 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 Prequalify 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 "Prequalify Now" and give it a unique id. An example Apply Now button is shown in the HTML code below.

👍

You can have as many Prequalify 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">PREQUALIFY 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.
  1. 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.

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.

Updated 3 days ago