Shopify Plugin Installation

​

Installation Steps

No time to read or have questions on any of the steps? Watch video guide on
How to set up Tabby on Shopify:

For setting up Webhooks, open Notifications and open “Webhooks”. At the “Webhooks” page click “Create webhook”.

​

Webhook API Version Update

Here Webhook Update Demonstarion can be reviewed:

Shopify Webhooks are created for the particular API version. Shopify releases several versions per year, so it means your initial API version settings will inevitably expire. Tabby makes the necessary changes to support the latest updated API versions, but this also requires a manual action from the partner’s end.

You need to go to Settings -> Notifications -> Webhooks and choose the latest API version from the dropdown of a particular Tabby Webhook.

​

Add Tabby Snippets

Here you may see a video on How to add Tabby snippet on Shopify:

1. In Shopify Admin panel click “Online Store” -> “Themes”;
2. At the Themes page click ” … ” -> “Edit code”;
3. In the navigation menu on your left click the “Snippets” folder and click “Add a new snippet”;
4. Put the naming “tabby-installments”;
5. Put the following code in the created file and click Save:
   Do not forget to check the variables in the code (such as publicKey, merchantCode, and priceElement if needed)

{%- liquid
  assign sectionId = section.id
  assign lang = localization.language.iso_code
-%}
<div id="TabbyPromo"></div>
<script>
  (function() {
    const script = document.createElement('script');
    script.src = 'https://checkout.tabby.ai/tabby-promo.js';
    script.async = true;
    script.onload = () => {
      const SUPPORTED_CURRENCIES = {
        AED: 'AED',
        KWD: 'KWD',
        SAR: 'SAR',
      };

      // here you can describe currency aliases
      const CURRENCY_NAME_TO_CODE_MAP = {
        AED: SUPPORTED_CURRENCIES.AED,
        KWD: SUPPORTED_CURRENCIES.KWD,
        SAR: SUPPORTED_CURRENCIES.SAR,
        KD: SUPPORTED_CURRENCIES.KWD,
        SR: SUPPORTED_CURRENCIES.SAR,
        Dh: SUPPORTED_CURRENCIES.AED,
        Dhs: SUPPORTED_CURRENCIES.AED,
      };

      // here you can describe count of currency decimals in your store
      const CURRENCY_DIGITS_COUNT = {
        [SUPPORTED_CURRENCIES.AED]: 2,
        [SUPPORTED_CURRENCIES.SAR]: 2,
        [SUPPORTED_CURRENCIES.KWD]: 3,
      };
      
      const priceRegExp = /\b[0-9\.,']+\b/;
      const currencyRegExp = new RegExp(`\\b(${Object.keys(CURRENCY_NAME_TO_CODE_MAP).join('|')})\\b`);
      const installmentsCount = 4;
      const tabbyElementId = '#TabbyPromo';
      const lang = '{{ lang }}';
      const sectionId = '{{ sectionId }}';
      // this works for the default theme, for custom themes sometimes you have to search for a price element manually
      const priceElement = window[`price-${sectionId}`];

      const initializeTabbyPromo = ({ element }) => {
        const [layoutPrice] = element.textContent?.match(priceRegExp) || [];
        const [layoutCurrency] = element.textContent?.match(currencyRegExp) || [];
        const price = layoutPrice.replace(/\D/g, '');
        const currency = CURRENCY_NAME_TO_CODE_MAP[layoutCurrency];
      
        if (price && currency) {
          document.querySelector('#TabbyPromo').style.display = 'block';
      
         new TabbyPromo({
            selector: tabbyElementId,
            currency,
            price: price / Number(1 + '0'.repeat(CURRENCY_DIGITS_COUNT[currency])),
            lang,
            installmentsCount,
            publicKey: 'yourApiKey', // specify your apiKey it should be a string
            merchantCode: 'string', // enter the code of your Store base currency,
            //'ksa' for SAR, 'KW' for KWD, 'default' for AED and others
          });
        } else {
          console.warn('can not recognize currency|price promo will be closed');
      
          document.querySelector(tabbyElementId).style.display = 'none';
        }
      };
      
      initializeTabbyPromo({ element: priceElement });
      
      const observer = new MutationObserver((mutations) => {
        mutations.forEach(mutation => {
          if (mutation.type === 'childList') {
            initializeTabbyPromo({ element: mutation.target });
          }
        });
      });
      
      observer.observe(priceElement, { subtree: true, childList: true });
    };
    document.body.appendChild(script);
  })();
</script>
<style>
  #TabbyPromo div:empty, #TabbyDialogContainer div:empty {
    display: block;
  }
</style>

6. Move back to the “Themes” page and now click “Customize” button;
7. Choose the Products page Theme and in the left navigation menu add “Custom Liquid” (or “HTML”) object and move it under Price or Quantity Selector;
8. In the content of the “Custom Liquid” put the following command and Save:

{% render 'tabby-installments'%}

9. Make sure the snippet appears in the required place at the store front.

​

If snippets don’t appear after completing all the steps

• The snippet code might not work for customized Shopify themes. It happens because of differences in price elements. To address this, locate the price element in your theme and update it on line 50 of our code. You can use the document.querySelector method with a unique selector that targets the price element on your product page — this could be an id, tag, class, etc., depending on your theme.
• If you’re unsure how to adjust the code, you’re welcome to use the non-price snippet which is available at Additional Scripts.
• Please note that “with-price” snippets only work when product page prices are displayed in a supported currency (SAR, AED, or KWD). For stores displaying prices in other currencies, the “non-price” snippet should be used.

​

Tabby is live now!

Tabby orders are captured automatically. Refunds can be initiated from Shopify admin panel and will reflect on Tabby Merchant Dashboard, Customer Portal and Settlements.

​

Limitations and Known Constraints

​

Language Settings

The locale for Tabby Hosted Payment Page and Payment Method will be set based on the store’s language, Tabby supports English and Arabic. If the locale is not supported, English is used by default. You can configure your store’s language in your Shopify admin under Settings -> Languages.

​

Order Number Update

When an order is placed in Shopify, a payment id is set in the Shopify order timeline information under the “payment was processed on tabby.” section, within the “Information from the gateway” subsection. This payment id is set in the Tabby order’s “reference_id” (order number). Shopify does not share the Shopify order number for this payment app integration and Tabby is not able to match the Shopify order number or order number in the Tabby order. The Webhooks allow to update order number or Tabby Merchant Dashboard, Customer Portal and Settlements.

​

Order Editing

Please note that order details editing (as order lines, customer details, etc.) will be reflected in Shopify Dashboard only and will not updated for the payment on Tabby Merchant Dashboard, Customer Portal and Settlements.

​

Order Lines

Shopify doesn’t share order data via the Payment App and Shopify does not share any order line data for non-product order lines, e.g. VAT/taxes, discounts, surcharges, tip, etc. Tabby orders will have necessary Order Lines data after Webhook installation.

​

Order Tagging

Tabby Payment App cannot currently set tags on a Shopify order. You can use the Shopify Flow app (available only for the following subscription plans - Shopify, Advanced and Shopify Plus) which can set order tags within a flow for Tabby orders.

​

Promo Customizations

Customizations of Tabby payment method and (logo, footer text) are currently supported only for Shopify Plus merchants. You can use custom scripts to customize a payment methods presentation in Shopify checkout, based on available cart data. Shopify has example payment script code here. You can request Logo and Snippets implementation by your Tabby account manager.

​

Domain Filterig

Payment App uses a different hosted payment page URL (checkout.tabby.ai/)
Merchants that filter this domain in Google Analytics will need to update their GA configurations accordingly.

​

Market Limitation

Tabby Payment App accept orders only for the billing addresses in the markets of KSA, UAE, Kuwait. Customers for non-supported regions based on the order’s currency are shown an error message on page load that the Tabby order cannot be processed.

​

Multi-Currency Processing and Currency Conversion

Tabby processes payments in the following currencies: SAR (SR), AED (Dhs), and KWD (KD), which must correspond to the customer’s billing address. Tabby Payment App is compatible with all Shopify stores, regardless of their base currency.

If the store’s base currency differs from the customer’s billing currency, currency conversion will be applied, and the converted amount will be displayed at Tabby checkout. Customer transactions and merchant settlements will be processed in the customer’s billing currency.

Currency conversion is also applied between supported currencies if the store’s base currency differs from the customer’s billing currency.

Please note that to enable conversion, the “Enable Multi-Currency Processing” option must be selected in the Tabby settings.

​

Inventory Lock Limitation

When a customer places an order with an alternative payment integration, such as Tabby Payment App, Shopify redirects to the payment method but does not lock the order’s product inventory and thus stock inventory cannot be guaranteed. Shopify will update this functionality in the future.

​

Additional Request of the Phone Number

Even if customers already previously entered their phone number in Shopify checkout, Shopify may not share that phone number with payment integrations when email is required instead of phone at the checkout, thus Tabby will ask the customers to enter the phone number again within our Hosted Payment Page.

​

Payment Method Renaming Limitation

Renaming the payment method is not currently supported by Shopify, as payment providers can now configure translations for the payment method name.
With Tabby Payment App for Shopify, translations are available for English and Arabic.

​

Checkout Error Limitation

“There was an issue processing your payment. Try again or use a different payment method.” – this message can happen for tech/authorization reasons only. The most common reason (for new integrations) is that the API keys haven’t been populated fully. You can check the API credentials at https://merchant.tabby.ai. Also, this message appears if country in shipping or billing address is different from country (countries) that your Tabby account is signed for.

​

Redirection for Pre-Scoring Rejection

Tabby now redirects the customers to our internal rejection screens where we explain the reason and advise how to avoid this rejection if possible. Customers may see the general rejection explanation (can’t be avoided), too high cart total and too low cart total rejections (can be skipped by adjusting the cart total).

​

New Session is Required after Cancellation or Rejection

Customers must start a new session after being rejected or if they decide to cancel the session. For this customers need to change any contact details at the “Contact information” page.

​

The Amount Paid by the Customer to Tabby Doesn’t Match the Shopify Order Total

If customers update a related, but different Shopify session separately from the Shopify session used to place the Tabby order, the order totals between the Shopify and Tabby orders may not match, but the amount “Paid by customer” for the Shopify order should always match the Tabby order total. While not ideal, this is working as expected and designed. Care should be taken to only fulfill order line items paid for by the customer.

​

Safari Browser for Web and Mobile Doesn’t Render the Snippets.

If you can see Tabby promos at all other browsers except for Safari, please know that this is a limitation of iOS and MacOS. There is no available fix for this issue, but we are in the process of researching what components prevent us from proper snippet showing.

​

Feedback and Support

If additional support is needed, email partner@tabby.ai (please include your Shopify store name and add your Account Manager in CC) for specific Tabby support.

Customer Tabby Support available at help@tabby.ai

https://community.shopify.com is a good place for Shopify questions, support, and feedback, in addition to https://help.shopify.com/