How to Add Tabby to Odoo: Full Setup Guide

Published 13 September 2026Updated 31 October 202615 min read

A practical guide to accepting Tabby in Odoo: merchant account, API keys, test mode, supported currencies, publishing the provider, and verifying an order.

Tabby splits a purchase into four payments for the shopper and pays you the full amount up front, less the fee you agreed with Tabby. It is now close to a default expectation in Saudi retail, which is why so many Odoo store owners go looking for an odoo tabby payment integration module within a week of going live.

Odoo ships no native Tabby provider in any version, so switching it on means three separate things: a merchant account with Tabby, a module that speaks the Tabby API, and a configuration pass inside Odoo. The configuration pass is where most people lose an afternoon, because two of its steps fail silently. On Odoo 16 and later, a provider in Test Mode is shown only to staff who are logged in, so it looks perfect to you and is simply not there for a customer. And an order priced in a currency the module does not accept hides the provider by design, with no error anywhere in the log.

This guide walks the whole path, in order, with the traps called out where they actually bite.

Step 1: get your own Tabby merchant account

No module can issue this for you, and any listing that hints otherwise is selling you something it cannot deliver. You apply directly at merchant.tabby.ai.

What Tabby asks for

Expect to supply your commercial registration or a freelance document, a bank account in the business name, your store URL, and details about what you sell and your average order value. Tabby underwrites the merchant, so approval is a commercial decision on their side and the timeline is theirs, not your integrator's.

Once approved you get access to the merchant dashboard, and inside it the two things Odoo needs: a public key and a secret key, in both a test and a live pair. You also agree your fee rate and the instalment plan offered to your shoppers with Tabby directly. A module does not set those numbers and cannot change them.

A note on Tamara

Tamara is a separate company with a separate application and separate keys. Most Saudi merchants end up wanting both, because shoppers have a preference and the checkout that only offers one loses the other half. Plan the two applications in parallel rather than in sequence. If you are still weighing one against the other, read Tabby versus Tamara for a Saudi store first. The Odoo side of Tamara differs in a few places, one API token instead of a key pair, a sandbox that runs on its own server, a mobile number the shopper cannot skip, so it has its own step by step Tamara setup guide.

Step 2: pick a module that matches your Odoo version and edition

Odoo prices and packages per major version, so a module bought for 17.0 is not the same product as the 18.0 build. Before you buy, confirm three things: the exact version of your database, whether the module supports Community as well as Enterprise, and whether it covers the surfaces you actually collect money on. A fuller version of that checklist, with the current Apps Store listings priced side by side, is in which Tabby and Tamara module to buy for Odoo. And if you are not sure whether the edition matters at all, or which hosting can block the install outright, Tabby on Odoo Community or Enterprise settles both before you spend anything.

That third point is worth a minute. A lot of merchants only think about the website checkout, then discover after go live that the portal invoice link they email to a customer has no Tabby button on it, and that the counter in the branch has none either. Tabby & Tamara for Odoo exists because of that gap: one install covers the eCommerce checkout, portal invoices, portal quotations and the Point of Sale, for both providers, on Odoo 14.0 through 19.0, Community and Enterprise. The Point of Sale side works differently enough from checkout that it has its own guide to BNPL at the counter. Quotations and invoices you send by chat have a few traps of their own, covered in sending quotations and invoices customers can pay in instalments.

Step 3: install and enter your keys

Install the module from Apps, then open Invoicing, Configuration, Payment Providers. In Odoo 15.0 and earlier the same screen is called Payment Acquirers. If Apps does not list the module, or the install stops with an error, the cause is usually not the module itself but a folder copied one level too deep, or the default Apps filter, which hides payment modules. Why the module will not show or install, and the fix for each cause takes them in the order you meet them.

Open the Tabby record and fill in the credentials:

• Tabby Public Key and Tabby Secret Key from the Tabby dashboard, test pair first. Paste them with nothing before or after: the module sends the secret key exactly as it is stored, and one stray space is enough for Tabby to refuse it.
• Tabby Merchant Code, which arrives filled in with default. Change it only if Tabby gave you a different code for this store.
• Tabby API URL, which arrives filled in with https://api.tabby.ai. The module's own help text on the field says that address suits most accounts and that keys issued in Saudi Arabia may need https://api.tabby.sa instead. If Tabby's onboarding pointed you at the Saudi address, put it here.

Then check the Payment Journal on the Configuration tab. From Odoo 16 the form will not save a Tabby provider in Test Mode or Enabled without one, and Odoo usually fills in your first bank journal on its own. Point it at a clearing journal kept for Tabby instead, so each payout can be matched to its orders later; the payout reconciliation guide sets that journal up.

What the Test Connection result tells you

Save, then press Test Connection under the credentials. It does one thing: it asks Tabby for a one-line list of your payments, using the saved secret key, at whatever address is in Tabby API URL. The notification that comes back tells you which of these happened.

• Green, connection succeeded. That secret key is valid at that address. The merchant code plays no part in this check. It is sent only when a real checkout is created, so your first sandbox order is what tests it.
• "Enter and save the Tabby secret key first." The button reads the saved record, not the form in front of you. Save, then press it again.
• "Tabby authentication failed. Check the API key/token and that the API URL matches the key's environment." Tabby answered and turned the key down. Either the key itself is wrong, a character short or carrying a space, or it is a perfectly good key sent to the wrong address, such as a Saudi-issued key on api.tabby.ai. Check the API URL field before you ask Tabby for new keys.
• "We could not reach Tabby. Please check your internet connection and try again." The request never got an answer, so your keys were not tested at all. The usual causes are a firewall or proxy that stops the Odoo server calling out, or a typing mistake in the API URL field.
• "Tabby returned an error (HTTP ...)" with a status code. Tabby answered with an error that was not about the key and sent nothing readable back. On Odoo 15 and later, open the Tabby/Tamara API Log under Payment Providers and read the row; the guide to install errors and the API log decodes each status.

Odoo 14 is the exception. Its acquirer form has no Test Connection button, and the Test Tabby connection button in Settings checks the keys the Point of Sale uses, which are stored separately from this form. On 14, your first sandbox order is the connection test.

Step 4: test mode first, and know what test mode really means

Set the provider State to Test Mode and use the test key pair. On Odoo 16 and later, Test Mode also unpublishes the provider, so you will see Tabby at checkout while logged in and a private browser window will not; Step 5 explains why that is deliberate. Tabby's sandbox gives you deterministic test identities, so you can drive an approval and a rejection on demand instead of hoping.

Two things people forget. First, test transactions never settle, so do not use them to prove the accounting entries. Check those on the first live payout instead, the way reconciling Tabby and Tamara payouts in Odoo walks through. Second, when you flip to live, the secret key is the one that counts: every call the module makes to Tabby carries it, and nothing in the module reads the public key. Replace both anyway, so the form does not mislead whoever opens it next, and re-run Test Connection if your version has the button. For a full pre-launch test plan, and why Test Mode alone does not make a Tabby payment fake, see testing Tabby and Tamara before go-live.

Step 5: make sure customers see it, not just you

Whether a shopper is offered Tabby depends on your Odoo version.

Odoo 16 to 19. A provider has two controls. The State field, Disabled, Test Mode or Enabled, decides whether it can take payments at all. The Published indicator at the top of the form decides whether visitors are shown it. Odoo ties the two together when you change the State on the form: Enabled publishes the provider, Test Mode unpublishes it. And an unpublished provider is still offered to anyone logged in as an internal user. So in Test Mode you, logged in as staff, see Tabby at checkout, while a customer does not, and neither do you in a private window. Nothing is broken. It lets you rehearse on the live store without putting a sandbox button in front of real customers.

The same rule explains the rarer case of a provider that is Enabled and still missing for customers: someone pressed Unpublish after enabling it. When you go live, check that the indicator reads Published, then open the shop in a private window and look at it the way a customer does.

Odoo 14 and 15. There is no Published control. The State alone decides, and a provider in Test Mode is offered to every visitor, real customers included. On those versions leave Tabby Disabled until you are ready to test, then test out of hours or on a copy of the database; testing on a copy of your database has its own section in the go-live test plan.

Step 6: check the currency before you debug anything else

The module accepts six Gulf currencies: SAR, AED, KWD, BHD, QAR and OMR. That is the module's list, not Tabby's. At the time of writing Tabby's merchant help centre names only SAR, AED and KWD, and your own account is approved for particular markets, possibly fewer still. A currency that passes the module but not your contract shows the button and is then refused by Tabby. The guide to GCC currencies for Tabby and Tamara in Odoo sets the three lists side by side and shows how to narrow the provider to what your account takes.

If the sales order or invoice is priced in USD or EUR, a correctly built module hides the provider rather than sending the gateway a request that will fail. That is the right behaviour, but it looks identical to a broken install from the outside.

So when Tabby does not appear, check in this order:

1. The State is Test Mode or Enabled, not Disabled.
2. On Odoo 16 and later, the provider is Published, or you are checking while logged in as staff.
3. The document currency is one of the six.
4. On Odoo 16 and later, the order total is not above the provider's Maximum Amount, which Odoo compares in your company currency. Leave that field empty unless you need it.
5. The provider's Countries list, if you set one, includes the customer's country.

Limits that Tabby sets on your account are a different matter. Odoo does not know them, so they never hide the button. Tabby makes its decision when the shopper clicks, and if it turns the order down at that point, the module stops before the hand-off and shows the shopper: "Tabby could not approve this order. Please choose a different payment method." That is Tabby's call, not a fault in your setup, which is one more reason to keep a card or transfer option next to it.

That list resolves the large majority of cases before anyone needs to open a log file. If it does not, the full fix guide for a provider that is not showing at checkout walks every filter Odoo applies, including pricelist currency and multi company.

Step 7: verify with a real order

Switch to live keys, keep the state at Enabled, and place one small real order yourself. Then confirm four things, not one:

• The promo badge appears under the product price and updates when you change the quantity or pick a different variant. Tabby expects that on site message to be visible as part of go live QA, so a static image of the logo is not enough. What the badge shows, how it recalculates and the checklist Tabby reviews against are in the Tabby 4 payments message under the price in Odoo.
• The redirect to Tabby carries the correct total and customer details.
• After approval, the Odoo transaction moves to Done, the sales order confirms, and the payment is linked to the invoice.
• The amount in the Tabby dashboard matches the amount in Odoo to the halala.

Then do the negative test. Abandon the payment on the Tabby page and confirm the order stays unpaid in Odoo. And try the shopper who approves and closes the tab before your store loads: on Tabby that order completes on its own only through a webhook you register yourself, which the go-live test plan walks through.

Why a forged success page must not confirm an order

This matters more than it sounds. The browser comes back to your site with a URL, and a URL can be typed by anyone. If a module trusts a success parameter in that redirect, a customer can mark their own order paid.

The correct pattern is that the return URL carries only a reference, and Odoo then calls the provider back, reading the real state from GET /api/v2/payments/{id} before touching the order. Webhooks are verified the same way rather than trusted on arrival, and a transaction already in a final state is never processed twice. That is how it is implemented in Tabby & Tamara for Odoo, and it is a fair question to ask any vendor before you buy. The attack, the code that falls for it and the verification path are laid out in why a fake success URL cannot mark an Odoo order paid.

Step 8: refunds and day two operations

Refunds are the first thing your accountant will ask about, and where one starts depends on where the sale happened.

• A website or portal sale is refunded from its payment record. Open the payment linked to the paid invoice and press Refund. Odoo's wizard takes the full amount or any part of it and sends the refund to Tabby. It does not create a credit note; if the sale itself is being reversed, issue one as you normally would. That button is part of Odoo from version 15, so on Odoo 14 a web sale is refunded in the Tabby dashboard and recorded in Odoo by hand.
• An invoiced counter sale can be refunded from the invoice itself, with the Refund on Tabby button in its header, by anyone holding the Tabby Refund access right.

Whichever path you use, start refunds in Odoo and nowhere else, because a refund made in the Tabby dashboard never reaches Odoo on its own. The paths in full, who may press which button and every refund error message are in the guide to Tabby and Tamara refunds in Odoo.

On Odoo 15 and later, keep an eye on the Tabby/Tamara API Log too. It records every call the website side makes to Tabby, with the keys masked, so when one order behaves strangely you can read the request and the response instead of guessing.

What this does not do, stated plainly

It does not get you approved with Tabby or Tamara. It is not official, endorsed by, or affiliated with either company. The instalment count, the fee rate and the shopper limits are set by Tabby and Tamara in your merchant agreement, not by any Odoo module. And it does not replace your own testing on your own database before you put it in front of customers.

Everything else on the list above, you can now do yourself, and the Tamara half follows the same shape in the Tamara Odoo integration guide. If you would rather not do it twice, once for Tabby and once for Tamara, that is what Tabby & Tamara for Odoo is for.

Frequently asked