Tamara Odoo Integration: Step-by-Step Setup Guide

Published 26 September 202617 min read

Add Tamara to Odoo step by step: merchant account, API token, sandbox testing, go-live, webhooks, Point of Sale, refunds, and fixes for the common errors.

Tamara is one of the two names Saudi shoppers look for at checkout, and for a good share of them it is the one they reach for first. Whether your Odoo store already takes Tabby or you are starting with Tamara, the question is the same: how do you get a Tamara button onto the website checkout, the invoice link and the counter, and how do you trust what Odoo records when a customer pays with it?

Odoo does not ship a Tamara payment provider in any version. A working Tamara Odoo integration needs three things: your own Tamara merchant account, a module that talks to Tamara's API, and a configuration pass inside Odoo. This guide walks the third part in order, based on how Tabby & Tamara for Odoo is actually built, and stops at the places where Tamara behaves differently from Tabby, because that is where most setups stall.

Four things that are different about Tamara

If you have been through the Tabby setup guide, these are the differences that matter:

• One API token, not a key pair. Tamara authenticates with a single merchant API token. There is no public and secret pair to mix up, but there are two environments to mix up.
• The sandbox is a separate server. Tamara runs its sandbox and its live platform on different hosts, and a token only works on the one it was issued for. The module picks the host from the provider's State, so the State and the token must always match.
• A mobile number is mandatory. Tamara identifies the shopper by phone. With no phone number on the customer's address, the module stops before anything reaches Tamara and asks the customer to add one.
• The Point of Sale reads its own settings. The register never looks at the website provider record. Its Tamara token and its sandbox switch live in Settings.

Each of these comes back below, at the step where it bites.

Step 1: open a Tamara merchant account

No module can create this account for you. You apply with Tamara directly, and approval is Tamara's decision on Tamara's timeline. Expect to be asked for a commercial registration or a freelance document and a bank account in the business name. Your fee, your settlement terms and the instalment plans your shoppers see are agreed with Tamara in your merchant agreement. No Odoo module sets those numbers or changes them.

Once you are into Tamara's partner portal, collect:

• The API token. This is the one Odoo cannot work without. Start with the sandbox token; you swap it for the live one at go-live.
• The notification token, if the portal gives you one. It is optional in Odoo, for reasons covered under notifications.
• The public key, if you have one. Also optional.

Run the Tabby application alongside this one, not after it. Shoppers have a preference, and a checkout that offers only one of the two loses part of its traffic in the last second before payment. If you are still deciding whether you need both, Tabby versus Tamara for a Saudi store weighs it honestly.

Step 2: install the module

Buy the build that matches your Odoo version, anything from 14.0 to 19.0, Community or Enterprise. Add it to your addons path and install it from Apps. Two things happen on install that are worth knowing:

1. Odoo gets two new payment providers, Tabby and Tamara, both created Disabled and, from Odoo 16 on, Unpublished. Nothing appears to a customer until you configure one.
2. The module tries to create two Point of Sale payment methods, Tabby and Tamara, on your first bank journal. On a brand new database with no journal yet it skips this quietly and creates them the next time the module is upgraded, or you create them by hand in Step 7.

The module depends on eCommerce and Point of Sale, so both apps are installed with it even if you only plan to use one side. It cannot go on Odoo Online, which accepts no third-party modules at all; Odoo.sh and your own server are both fine. Tabby and Tamara on Odoo Community or Enterprise settles the hosting question in full.

Step 3: fill in the Tamara provider

Open Invoicing (Accounting on Enterprise), Configuration, Payment Providers, and click Tamara. On Odoo 14 and 15 the same screen is called Payment Acquirers. The Website app's configuration menu leads to the same list.

On the Credentials tab:

• Tamara API Token. Paste the sandbox token. The field masks what you paste.
• Tamara Notification Token. Optional.
• Tamara Public Key. Optional.

Under Storefront Promo, on the same tab:

• Show Tamara Promo on Products puts a line such as "3 interest-free payments of 98.33" under the price on product and cart pages, with a Learn more link that opens the breakdown. It is on by default.
• Tamara Installments defaults to 3. This number is not only for display. The module also sends it to Tamara as the instalment count every time it creates a checkout, so set it to a plan your Tamara account actually offers, or checkouts can be refused. Every checkout the module creates is a pay-in-instalments plan with that count; Tamara's other plan types, such as paying the full amount later, are not offered through it.

The badge works the same way for both providers. How its figure follows quantity and variant changes, and the usual reasons it does not show, are in the guide to the instalment message under the product price.

On the Configuration tab, set the Payment Journal. Odoo will not save the provider in any State but Disabled without one. A dedicated Tamara clearing journal makes the monthly reconciliation far easier than posting straight into your main bank account, and reconciling Tabby and Tamara payouts in Odoo shows how to set one up. Save.

Step 4: sandbox first, and prove the token

Set the State to Test Mode and save. In Test Mode the module sends every Tamara call to Tamara's sandbox server; in Enabled it sends them to the live one. Unlike Tabby, there is no API URL field to edit for Tamara. The State decides.

Now press Test Connection under the Tamara credentials. The module makes an authenticated call to whichever Tamara server matches the current State, and tells you the result in a notification:

• Green: the token is accepted on that server.
• Red, starting "Tamara authentication failed": the token is wrong, or it belongs to the other environment. A live token in Test Mode and a sandbox token in Enabled both fail in exactly this way.

Odoo 14 has no Test Connection button on the acquirer form, so on that version a sandbox order is your connection test.

Why you can see Tamara and your customers cannot

From Odoo 16 on, changing the State also flips the Published toggle: Enabled publishes the provider, Test Mode unpublishes it. And Odoo shows unpublished providers only to logged-in internal users. So in Test Mode you see Tamara at checkout while you are logged in as an employee, and a visitor in a private window does not. That is deliberate. It lets you test on the live store without showing a sandbox button to real customers.

One thing is visible to everyone, though. The promo line under the price appears as soon as the provider leaves Disabled, Test Mode included, published or not. If you are testing on a store that is already trading, untick Show Tamara Promo until you go live.

The sandbox order

Stay logged in, put a product in the cart, and check out with an address that carries a mobile number. Choose Tamara, and the browser is sent to Tamara's sandbox checkout. Complete it the way Tamara's sandbox documentation describes, then check four things when you land back on the store:

1. The payment status page shows the payment as confirmed.
2. The payment transaction on the order is Done, and its Provider Reference is Tamara's order id.
3. The sales order is confirmed.
4. The order on Tamara's side carries your Odoo transaction reference, because the module sends it as the order reference. That is what lets you match the two systems line for line later.

Then run the negative test. Start a second order, cancel on Tamara's page, and confirm the order stays unpaid in Odoo.

What happens when a customer picks Tamara

Knowing the sequence makes diagnosis much quicker, because every error message in the last section maps to one of these steps.

1. Odoo creates a Tamara checkout. It sends the amount and currency, the Odoo transaction reference, the customer's name, phone, email and address, the order lines, the instalment count, and two addresses: one Tamara sends the customer back to, and one it sends notifications to. A customer whose language in Odoo is Arabic gets Tamara's checkout in Arabic. When the order lines do not add up exactly to the amount being paid, because of tax, a discount or delivery for example, the module sends a single line for the whole amount instead, so a rounding difference never gets the order refused. KWD, BHD and OMR amounts go with three decimals, the other three currencies with two.
2. The customer approves on Tamara's page.
3. Odoo reads the result from Tamara, never from the browser. The return address carries nothing but the Odoo reference. The module asks Tamara's API for the order's real status. If Tamara reports it approved, the module authorises it and then captures it, and only an explicit capture confirmation from Tamara marks the transaction Done. A decline becomes an error; expired or cancelled becomes cancelled.
4. A finished transaction is never processed twice, whichever of the returning customer and the notification arrives second.

Capture happens straight away. There is no mode that holds the authorisation until you ship. Why reading the status back matters so much, and what goes wrong in modules that trust the redirect, is in why a fake success URL cannot mark an Odoo order paid.

Step 5: notifications (webhooks)

Not every customer comes back to your site. Some approve on their phone and close the tab. For those, Tamara notifies your store, and the module handles the notification exactly as it handles a returning customer: it reads the order from Tamara's API and finishes it.

There is nothing to type into Odoo for this. The module puts your store's notification address, the one ending in /payment/tabby_tamara/webhook, into every checkout it creates. If Tamara's portal asks you to register a webhook address as well, that is the address to give it.

Because each notification is treated only as a prompt to go and check, a forged notification cannot mark anything paid. That is also why the Notification Token field is optional: the safety of an order does not rest on it.

Both addresses are built from the web address your store answers on. If Odoo runs behind a reverse proxy, run it in proxy mode so they come out as your public https domain and not an internal one. Otherwise Tamara sends customers and notifications to an address they cannot reach.

Step 6: go live

When the sandbox run is clean:

1. Replace the sandbox token with the live token.
2. Set the State to Enabled. On Odoo 16 and later that also publishes the provider; check that the indicator at the top of the form now reads Published.
3. Press Test Connection again. It now checks the live token against the live server.
4. Tick Show Tamara Promo back on if you turned it off.
5. Log out, or open a private window, and confirm Tamara appears at checkout for a visitor.
6. Place one small real order yourself and compare the amount in Tamara's portal with Odoo to the halala. Then refund part of it, which proves the refund path before a customer needs it.

Step 7: Tamara at the Point of Sale

The register works differently from the website, starting with where it reads its settings. Open Settings and find the Tabby BNPL section:

• Tamara API Token. Leave it empty and Tamara is simply unavailable at the till.
• Tamara Sandbox. Ticked, counter payments go to Tamara's sandbox server; unticked, to the live one. It is independent of the website provider's State, so switch both at go-live.
• Payment Timeout (seconds). How long the register waits for the customer to approve. It defaults to 300, and the module never waits less than 180, whatever you type.

The test button in that section checks Tabby only. To check a Tamara token, use Test Connection on the Tamara provider, with its State matching the sandbox switch.

Next, the payment method. If the module created a Tamara method on install, open it under Point of Sale, Configuration, Payment Methods; if not, create one there. Tick Enable Tamara (Buy Now, Pay Later) and choose a journal. From Odoo 15 on the module refuses to save a Tamara method without one, and a clearing journal is the right choice. Add the method to each shop in the Point of Sale settings, then close and reopen the session so the register loads it.

At the till, select the customer first, with a mobile number on their contact, because the register sends that number to Tamara. Then pick Tamara as the payment method. A popup shows the amount and a QR code, which Odoo draws from the checkout link Tamara returns. The customer scans it and approves on their own phone. Meanwhile the register asks the server every four seconds; the server reads the order from Tamara, captures it as soon as it is authorised, and only then marks the payment line done. Until that moment the order cannot be validated.

The clip shows it with Tabby; a Tamara payment goes through the same screen and the same lock. Every counter payment is recorded under Point of Sale, Orders, Tabby Payments, which despite its name lists Tamara payments too, with status, amount, references and any error. The rest of the counter flow is in the guide to Tabby and Tamara in the Odoo Point of Sale.

Step 8: refunds

For a payment made on the website, a portal invoice or a portal quotation, open the payment transaction and press Refund (Odoo 15 and later). Odoo's refund wizard lets you refund all of it or part of it. The module sends the refund to Tamara with your Odoo refund reference, and marks it done only when Tamara returns a refund id; anything else is recorded as an error with Tamara's message. Issue the credit note as you normally would. The gateway refund and the accounting document are separate acts.

At the counter there is one difference from Tabby worth knowing now. The automatic refund that follows a cashier's POS refund currently covers Tabby methods only. For a Tamara counter sale, open the payment under Tabby Payments, or open the customer invoice, and use the Refund on Tabby button. Despite the label, it sends a Tamara payment to Tamara's own refund endpoint. The button refunds the whole remaining captured balance, so it fits a full return; a partial return on a Tamara counter sale is not something Odoo can send to Tamara yet, so arrange that one with Tamara directly. Only users given the Tabby Refund access right see the button, and nobody has that right until you grant it. The full picture is in the guide to Tabby and Tamara refunds in Odoo.

Common Tamara errors and how to fix them

From Odoo 15 on, every call the module makes to Tamara from the website side is recorded in the Tabby/Tamara API Log, a menu under Payment Providers (Payment Acquirers on 15): the request, the response and the HTTP status, with tokens and keys masked. Filter it to Tamara and Errors only, and most of the problems below explain themselves. Counter payments keep their status and their error on their own record under Tabby Payments.

"Tamara needs your mobile number. Please add a phone number to your address and try again."

The customer's address has no phone number. Odoo's checkout address form asks for one, so this mostly bites on portal invoices and quotations sent to contacts that were created in the back office without a mobile. Add the number to the contact and send the link again.

"Tamara authentication failed. Check the API key/token and that the API URL matches the key's environment."

The token is wrong, carries a stray space, or belongs to the other environment. Compare the State, Test Mode or Enabled, with where the token came from, then run Test Connection.

"Tamara error: ..." when the customer clicks Pay

Tamara refused to create the checkout, and the text after the colon is Tamara's own explanation. Open the latest Tamara error in the API log to see the exact request and answer, and start with the two inputs you control: the order value and the number in Tamara Installments.

Tamara does not appear at checkout

Check in this order: the State is Test Mode or Enabled; the provider is Published (from Odoo 16 on), or you are testing while logged in; the document currency is SAR, AED, KWD, BHD, QAR or OMR, since the module hides Tamara on any other currency, silently and on purpose; and the customer's country and the order amount pass the provider's Countries and, from Odoo 16 on, its Maximum Amount on the Configuration tab. The fix guide for a provider missing at checkout walks every filter in the order Odoo applies them, pricelists and multi-company included.

"Tamara could not capture this payment. Please contact support."

The customer approved, but Tamara did not confirm the capture. The module reads the order once more before giving up, then leaves the transaction in error and the order unpaid. Do not ship it. Look at the capture call in the API log and at the order in Tamara's portal before you contact Tamara.

"Tamara declined this payment."

A credit decision by Tamara about this shopper, not a fault in your setup. Offer another way to pay.

"Tamara is not configured" at the till

The register reads its token from Settings, not from the provider. Fill in Tamara API Token in the Tabby BNPL section of Settings.

The customer paid, but Odoo still shows the order unpaid

When a customer closes the tab instead of coming back, the order depends on the notification. If that cannot reach your store, typically because Odoo built an internal address as described in Step 5, the order stays unpaid. Fix the proxy setting so future orders are covered, and confirm this payment in Tamara's portal before you ship the order.

What this does not do, stated plainly

It does not get you approved by Tamara, and it is not official. Tabby & Tamara for Odoo is an independent integration by Kerneltics, with no affiliation with or endorsement by Tamara or Tabby. Instalment plans, fees and shopper limits are set by Tamara in your merchant agreement. And it does not replace a full sandbox run on your own database before real customers see the button.

If you are adding Tabby as well, the other half is the Tabby setup guide for Odoo: the same module, the same screens, one more set of credentials.

Frequently asked