How to Integrate Tamara Payments (BNPL) Correctly — and the Open-Source AI Skill That Does It

If you've ever asked an AI coding assistant to wire up a payment provider, you've seen it confidently invent an endpoint that doesn't exist. With most APIs that's an annoying bug you catch in testing. With Tamara it's worse: the API has hard timing rules and a strict order-status state machine, so a confident guess can leave real orders unsettled — the merchant ships the goods and never gets paid.

I integrate Tamara for clients across Egypt, the UAE, and Saudi Arabia, so I packaged everything I know about doing it correctly into a free, open-source Claude skill. This post walks through how a correct Tamara integration actually works — and how the skill makes any AI agent get it right the first time.

What is Tamara?

Tamara (تمارا) is the leading shopping and buy-now-pay-later (BNPL) platform in the GCC — Saudi Arabia, the UAE, Bahrain, Kuwait, and Oman. Shoppers split a purchase into interest-free instalments ("Pay in 3", "Pay in 4", "Pay next month") while the merchant is paid up front. It's one of the highest-converting payment options in the region, which is why almost every serious Gulf store offers it.

Pick the integration path first

Before writing a line of code, decide how you're adding Tamara — the docs differ for each path:

• Direct API — custom code on your own backend; the most control.
• E-commerce plugin — a no-code install on a hosted store: WooCommerce, Shopify, Salla, Magento, OpenCart, PrestaShop, Zid, Salesforce Commerce Cloud, ExpandCart, and more.
• Channel partner — add Tamara through a gateway you already use (Checkout.com, PayTabs, Amazon Payment Services, CCAvenue…).
• In-store / POS — physical shops, via an SMS payment link or a QR "Scan-to-Pay" code.
• Mobile SDK — inside an app (Android, iOS, Flutter, React Native).

If you're on WooCommerce or Salla, install the official plugin and you're 90% done. The rest of this post is about the Direct API, because that's where the subtle, expensive mistakes happen.

The Tamara API "golden path"

Every direct integration has the same shape. Memorise it:

1. Create a checkout session — POST /checkout. Store the returned order_id and redirect the customer to the returned checkout_url. Status starts at new.
2. Customer pays on Tamara's hosted page → status becomes approved.
3. The order_approved webhook fires server-to-server — this is your reliable trigger, not the browser redirect.
4. Authorise — POST /orders/{order_id}/authorise → status authorised (treat as paid). This step is mandatory unless auto-authorisation is enabled.
5. Capture on fulfilment/shipment — POST /payments/capture (full or partial) → fully_captured / partially_captured. Capture is what actually moves money into your settlement.
6. Refund or cancel — refund captured amounts (/payments/refund); cancel or reduce still-authorised orders (/orders/{order_id}/cancel).

Environments & auth: sandbox is https://api-sandbox.tamara.co, production is https://api.tamara.co. Authenticate every request with Authorization: Bearer {API_TOKEN}. Build and test entirely on sandbox before you request live credentials.

The mistakes that silently break settlement

These are the ones that cost real money — and exactly what an AI assistant gets wrong when it's guessing:

• Skipping Authorise. An order left at approved is never captured and never settles. You shipped; you don't get paid. Drive Authorise from the order_approved webhook.
• Trusting the browser redirect. The success/failure redirect can be lost (closed tab, flaky network). The webhook is the source of truth — verify and act on it.
• Wrong decimal count. SAR and AED use 2 decimals, but BHD, KWD, and OMR use 3. Send the wrong precision and the API rejects the request with a country/currency error.
• Not verifying the webhook. Each webhook carries a tamaraToken JWT (HS256). Verify it with your Notification token before acting, and make handlers idempotent — Tamara may resend events.
• Missing the timing windows. Pay ≤ 30 min, authorise ≤ 72 h, capture/cancel ≤ 90 days. Blow a window and the order expires.

A free, open-source Claude skill for Tamara

Instead of hoping the model remembers all of that, I gave it the real documentation. The result is an open-source Tamara payments skill on GitHub — a complete offline mirror of docs.tamara.co: 139 pages (114 guides + the full OpenAPI for all 25 API endpoints), plus a condensed quick-reference cheat sheet for base URLs, auth, the endpoint map, the order-status flow, and webhook verification.

Drop it into your Claude Code skills directory and it activates automatically whenever a task mentions Tamara:

git clone https://github.com/karem505/tamara-payments-skill.git ~/.claude/skills/tamara-payments

Now when you ask "integrate Tamara checkout in my WooCommerce store" or "why is my Tamara order stuck at approved?", the agent reads Tamara's actual docs before writing code — instead of inventing an endpoint. It covers the direct API, every e-commerce plugin, channel partners, in-store/POS, mobile SDKs, and the promotional widgets, across all five GCC markets.

Frequently Asked Questions

How do I integrate Tamara payments? Pick a path first (Direct API, plugin, channel partner, in-store/POS, or mobile SDK). For the API path, the flow is: create checkout → customer pays → order_approved webhook → Authorise → Capture on fulfilment → Refund/Cancel as needed.

What is the Tamara API base URL? Sandbox is https://api-sandbox.tamara.co and production is https://api.tamara.co. Authenticate every request with Authorization: Bearer {API_TOKEN} and always test on sandbox first.

Why is my Tamara order stuck at approved? Because Authorise wasn't called. After the order_approved webhook you must POST /orders/{order_id}/authorise; otherwise the order never captures and never settles.

Does Tamara support WooCommerce, Shopify, and Salla? Yes — Tamara ships official plugins for Magento, WooCommerce, Shopify, Salla, OpenCart, PrestaShop, Zid, Salesforce Commerce Cloud, ExpandCart, and others.

Which countries and currencies does Tamara support? Saudi Arabia (SAR), the UAE (AED), Bahrain (BHD), Kuwait (KWD), and Oman (OMR). BHD, KWD, and OMR use three decimal places.

Need a Tamara integration done right?

I build and debug Tamara integrations — direct API, plugins, and custom checkout flows — for stores across Egypt and the Gulf. Get in touch if you want it shipped correctly the first time, or clone the open-source skill and build it yourself.