Tabby & Tamara BNPL (GCC)

The ECOSIRE Tabby & Tamara BNPL module adds both leading GCC Buy-Now-Pay-Later gateways to Odoo's native payment framework under a single installation. Buyers are redirected to a Tabby or Tamara hosted checkout page where they choose their instalment plan (Pay in 4, Split in 3, Pay Later), then returned to your store. Inbound webhooks are signature-verified before any transaction state is changed.

Compatibility: Odoo 17 / 18 / 19 Price: $299 (one-time) License: Up to 3 domain activations

Key Features

• Two provider codes — tabby and tamara — wired into Odoo's standard payment.provider framework; configure one record per active gateway
• Hosted redirect checkout: buyer lands on Tabby or Tamara's own payment page and is returned to /payment/status
• Region-aware Tabby base-URL routing: api.tabby.ai for UAE / Kuwait, api.tabby.sa for Saudi Arabia
• Tamara sandbox / production switching via the provider state (Test vs Enabled)
• Signature-verified webhooks: Tabby uses HMAC-SHA256 over the raw body (X-Tabby-Signature header); Tamara uses JWT HS256 (tamaraToken query param and Authorization: Bearer header)
• Full and partial refunds against captured BNPL payments
• Currency guard: Tabby and Tamara are hidden at checkout when the order currency is not SAR, AED, or KWD
• All API secrets stored on the payment.provider record, restricted to base.group_system; nothing hard-coded

Prerequisites

• Odoo 17, 18, or 19 (Community or Enterprise edition)
• An active ECOSIRE license for this module (ecosire_payment_tabby_tamara)
• A live merchant account with Tabby and/or Tamara (required for real transactions; sandbox testing is available for Tamara via the Test mode; Tabby sandbox is key-prefix-based using sk_test_ keys)
• Python library PyJWT installed in your Odoo environment (required for Tamara webhook JWT verification)
• Your Odoo instance must be publicly reachable so the gateways can POST to your webhook URLs

Pakistan wallets out of scope

JazzCash and Easypaisa (PK mobile wallets) are integrator-gated and are not covered by this module. They require a separate direct integration with each provider.

Installation

1. Download the module ZIP from your ECOSIRE Dashboard
2. Extract to your Odoo addons directory:

   unzip ecosire-payment-tabby-tamara-*.zip -d /opt/odoo/addons/

3. Ensure PyJWT is installed in the Odoo Python environment:

   pip install PyJWT

4. Restart the Odoo service:

   sudo systemctl restart odoo

5. Navigate to Apps, click Update Apps List
6. Search for "ECOSIRE Payment Tabby Tamara BNPL" and click Install
7. Activate your ECOSIRE license when prompted (go to Settings > ECOSIRE License if the prompt does not appear)

Configuration

Step 1: Activate the ECOSIRE License

1. Go to Settings > ECOSIRE License
2. Enter the license key you received after purchase
3. Click Activate License
4. Confirm the status shows Active before proceeding

Step 2: Open the Payment Provider Records

1. Navigate to Invoicing (or Accounting) > Configuration > Payment Providers
2. You will see two pre-seeded records: Tabby (BNPL) and Tamara (BNPL)
3. Open the provider you want to configure

Step 3: Configure Tabby

Set the State to Test (sandbox) or Enabled (live), then fill the credential fields:

Field	Where to find it	Notes
tabby_secret_key — Tabby Secret Key	Tabby merchant dashboard > API Keys	Use sk_test_... for sandbox, sk_... for production. The key prefix decides test vs live; there is no separate sandbox domain.
tabby_public_key — Tabby Public Key	Tabby merchant dashboard > API Keys	Client-side widget key (pk_test_... / pk_...). Not sensitive.
tabby_webhook_secret — Tabby Webhook Secret	Tabby merchant dashboard > Webhooks	Set this to the HMAC secret shown when you register a webhook endpoint.
tabby_merchant_code — Tabby Merchant Code	Tabby merchant dashboard	Passed in the checkout session payload as merchant_code.
tabby_region — Tabby Region	Select from dropdown	UAE / Kuwait routes to api.tabby.ai; Saudi Arabia (KSA) routes to api.tabby.sa.

After saving, register the webhook URL in the Tabby merchant dashboard:

https://<your-odoo-domain>/payment/tabby/webhook

The return URL is handled automatically (/payment/tabby/return); you do not need to register it separately.

Step 4: Configure Tamara

Set the State to Test (sandbox) or Enabled (live), then fill the credential fields:

Field	Where to find it	Notes
tamara_merchant_token — Tamara API Token	Tamara partner portal > API Credentials	Opaque Bearer token issued at merchant onboarding. Used for all server-side calls.
tamara_public_key — Tamara Public Key	Tamara partner portal > API Credentials	Client-side widget key. Not sensitive.
tamara_notification_token — Tamara Notification Token	Tamara partner portal > Webhooks	HS256 secret used to verify inbound webhook JWTs.

When State is Test, the module calls https://api-sandbox.tamara.co. When Enabled, it calls https://api.tamara.co.

Register the webhook URL in the Tamara partner portal:

https://<your-odoo-domain>/payment/tamara/webhook

The return URL (/payment/tamara/return) is embedded automatically in the checkout payload.

Step 5: Enable Capture and Refund (Optional)

Capture, refund, authorise, and cancel paths are wired in the module but are guarded until you verify them against your live merchant documentation. To enable them:

1. Confirm the endpoint paths with your Tabby or Tamara integration manager
2. Go to Settings > Technical > Parameters > System Parameters
3. Set the key ecosire.bnpl.endpoints_confirmed to 1

Until this parameter is set, refund and capture actions will raise a clear error message explaining which endpoint needs confirmation. This is intentional and follows ECOSIRE's no-fabricated-endpoints policy.

Usage

Checkout Flow

1. Buyer adds items to the cart on your Odoo website or eCommerce store
2. At checkout, Tabby (BNPL) and/or Tamara (BNPL) appear as payment options when the order currency is SAR, AED, or KWD
3. Buyer selects the BNPL option and clicks Pay
4. Odoo calls the gateway to create a checkout session, then redirects the buyer to the Tabby or Tamara hosted page
5. Buyer completes their instalment agreement on the gateway page
6. Gateway redirects the buyer back to /payment/status
7. The gateway posts the authoritative payment status to the webhook URL
8. Odoo's transaction record is updated to Done (captured), Pending, or Cancelled based on the verified webhook payload

Refunds

1. Open the Invoicing > Customers > Invoices or Sales > Orders record
2. Find the related payment transaction and click Refund
3. Enter the refund amount (full or partial)
4. The module issues a refund request to the gateway using the stored provider_reference (the gateway's payment or order ID)

Refunds require that ecosire.bnpl.endpoints_confirmed is set (see Step 5 above) and that the original transaction has a stored gateway reference.

API Details

Field	Value
Auth method	Bearer token (API key or merchant token)
Tabby UAE/KW endpoint	https://api.tabby.ai/api/v2
Tabby KSA endpoint	https://api.tabby.sa/api/v2
Tamara production endpoint	https://api.tamara.co
Tamara sandbox endpoint	https://api-sandbox.tamara.co
Supported currencies	SAR, AED, KWD
Webhook — Tabby	HMAC-SHA256 (X-Tabby-Signature header)
Webhook — Tamara	JWT HS256 (tamaraToken param / Authorization: Bearer)
Key config fields (Tabby)	tabby_secret_key, tabby_public_key, tabby_webhook_secret, tabby_merchant_code, tabby_region
Key config fields (Tamara)	tamara_merchant_token, tamara_public_key, tamara_notification_token

Troubleshooting

Issue	Solution
Tabby or Tamara not shown at checkout	Confirm the order currency is SAR, AED, or KWD; providers are automatically hidden for other currencies
"Secret Key is not configured" error	Open the provider record in Invoicing > Configuration > Payment Providers and fill the Secret Key / API Token field
Tabby webhook returns 403	The X-Tabby-Signature header did not match. Confirm that tabby_webhook_secret matches exactly what is shown in the Tabby merchant dashboard > Webhooks
Tamara webhook returns 403	The JWT could not be verified. Confirm that tamara_notification_token matches the Notification Token in the Tamara partner portal
"PyJWT not installed" error on Tamara webhook	Run pip install PyJWT in the Odoo Python environment and restart the service
Refund raises "endpoint not verified" error	Set system parameter ecosire.bnpl.endpoints_confirmed to 1 after verifying the refund endpoint path with your gateway integration manager
Tamara calls hitting sandbox unexpectedly	Check the provider State field; Test always routes to api-sandbox.tamara.co regardless of credentials
Tabby calls hitting wrong region	Confirm tabby_region is set correctly: UAE / Kuwait for api.tabby.ai, Saudi Arabia (KSA) for api.tabby.sa
Transaction stays in "Pending" after buyer returns	This is expected; the final state is set by the webhook, not the return redirect. Check that the webhook URL is registered in the provider dashboard and is publicly reachable
License not active	Verify your ECOSIRE license at Settings > ECOSIRE License

Support

• General Troubleshooting
• Email: [email protected]
• Support Portal