Tamara

Tamara

This connector uses the Tamara merchant API (buy now, pay later in Saudi Arabia, the UAE, Kuwait, Bahrain and Oman): order lookup by your order number or by Tamara order id, payment types and pre-checkout eligibility, and webhooks. Capture and refund are included but installed switched off.

Setup (2 minutes)

1. Sign in to the Tamara Partners Portal and open API Token Management, or use the API token Tamara sent with your merchant account. Sandbox and production have different tokens.
2. Paste the token into TAMARA_API_TOKEN. It is sent as Authorization: Bearer <token>. The notification token and the public key are not used here.
3. TAMARA_API_URL is https://api.tamara.co for production or https://api-sandbox.tamara.co for the sandbox; it must match the token.
4. Install and run tamara_list_payment_types to check the token.

Identifiers: order_reference_id is your own order number sent at checkout (e.g. the shop order number); order_id is the UUID Tamara issued. Most questions start from your order number: tamara_get_order_by_reference.

Workflow

• Order status: tamara_get_order_by_reference (or tamara_get_order with the Tamara id). Status flow: new, approved, authorised, then partially_captured / fully_captured, and partially_refunded / fully_refunded; canceled, declined and expired are final. paid_amount is what the customer has paid so far; settlement_status and settlement_date say whether Tamara has paid you out.
• Transactions: captures, refunds and cancels are inside transactions of the order.
• Before checkout: tamara_list_payment_types (what the store offers), tamara_check_payment_options (what this customer can use for this amount), tamara_check_customer_eligibility (is the customer blocked).
• Webhooks: tamara_get_webhook with the id from the registration.

Writes switched off: tamara_capture_order (captures an authorised order when it ships) and tamara_refund_order (refunds a captured order). Both move money; an admin turns them on deliberately. Before each call show the user the order, the amount and the currency and wait for a yes.

Amounts: objects {amount, currency}; SAR and AED with 2 decimals, BHD, KWD and OMR with 3. Times are UTC, ISO 8601.

Errors: 401 means a wrong token or a token for the other environment (sandbox vs production). 404 on an order means no order with that reference or id in this environment. 400 or 422 on capture or refund name the field Tamara rejected (e.g. an amount above what can be captured).

Limitations: Tamara has no endpoint to list or search orders; look orders up by reference or id. Creating checkout sessions, authorising and cancelling orders, the claims API (sandbox only at Tamara) and settlement reports are not part of this connector.