Laravel Tamara Payment Gateway

A professional Laravel package for integrating Tamara - the leading Buy Now Pay Later (BNPL) payment solution in the Middle East. Supports Saudi Arabia, UAE, Kuwait, Bahrain, Qatar, and Oman.

Features

• ✅ Full Tamara Online Checkout flow
• ✅ Payment Types lookup
• ✅ Create Checkout Sessions
• ✅ Authorise / Capture / Cancel / Refund orders
• ✅ Webhook management (register, list, update, delete)
• ✅ Sandbox & Production environments
• ✅ Multi-currency support (SAR, AED, KWD, BHD, QAR, OMR)
• ✅ Multi-country support (SA, AE, KW, BH, QA, OM)
• ✅ In-store checkout support
• ✅ Guzzle HTTP client (no raw cURL)
• ✅ Configurable routes prefix & middleware
• ✅ Transaction logging migration
• ✅ Laravel 10, 11, 12 & 13 compatible
• ✅ PHP 8.1+

Requirements

Installation

composer require aghfatehi/laravel-tamara

Configuration

1. Publish Configuration

php artisan vendor:publish --tag=tamara-config

2. Publish Migration (Optional)

php artisan vendor:publish --tag=tamara-migrations
php artisan migrate

3. Environment Variables

Add these to your .env file:

TAMARA_SANDBOX_MODE=true
TAMARA_API_TOKEN=your-api-token-here
TAMARA_COUNTRY_CODE=SA
TAMARA_CURRENCY=SAR
TAMARA_INSTALMENTS=3
TAMARA_PAYMENT_TYPE=PAY_BY_INSTALMENTS
TAMARA_LOCALE=en_US
TAMARA_ROUTE_PREFIX=tamara

4. Service Provider

The package auto-discovers via Laravel's package discovery. If you disable discovery, register manually in config/app.php:

'providers' => [
    Aghfatehi\Tamara\TamaraServiceProvider::class,
],

5. Facade (Optional)

'aliases' => [
    'Tamara' => Aghfatehi\Tamara\Facades\Tamara::class,
],

Usage

Quick Start - Frontend Checkout

use Aghfatehi\Tamara\Facades\Tamara;

// Get available payment types
$types = Tamara::getPaymentTypes('SA', 'SAR', 500);

// Create a checkout session
$response = Tamara::createCheckout([
    'total_amount' => ['amount' => 500, 'currency' => 'SAR'],
    'order_reference_id' => 'ORD-' . uniqid(),
    'order_number' => 'INV-2024-001',
    'consumer' => [
        'email' => 'customer@example.com',
        'first_name' => 'Ahmed',
        'last_name' => 'Ali',
        'phone_number' => '500000000',
    ],
    'country_code' => 'SA',
    'merchant_url' => [
        'success' => route('tamara.callback'),
        'failure' => route('tamara.failure'),
        'cancel' => route('tamara.cancel'),
        'notification' => route('tamara.webhook'),
    ],
]);

// Redirect customer to Tamara checkout
if (isset($response['checkout_url'])) {
    return redirect()->away($response['checkout_url']);
}

Using Routes

The package registers these routes under the configured prefix (/tamara by default):

API Methods

// Payment Types
$types = Tamara::getPaymentTypes('SA', 'SAR', 500, '500000000');

// Checkout
$checkout = Tamara::createCheckout($data);

// Order Management
$order = Tamara::getOrder('order-id-here');
$order = Tamara::getOrderByReferenceId('ref-id-here');

// Authorise / Capture / Cancel / Refund
$authorised = Tamara::authoriseOrder('order-id');
$captured = Tamara::captureOrder('order-id', $data);
$cancelled = Tamara::cancelOrder('order-id', $data);
$refunded = Tamara::refundOrder('order-id', 500, 'SAR', 'Refund comment');

// Webhook Management
$webhook = Tamara::webhookRegister('https://example.com/webhook', [
    'order_approved',
    'order_declined',
    'order_authorised',
    'order_captured',
    'order_refunded',
]);
$list = Tamara::webhookList();
$detail = Tamara::webhookGet('webhook-id');
Tamara::webhookDelete('webhook-id');
Tamara::webhookUpdate('webhook-id', 'https://example.com/webhook', [...]);

Customising Routes

Publish the config and modify the routes section:

// config/tamara.php
'routes' => [
    'prefix' => 'payment/tamara',     // Custom prefix
    'middleware' => ['web', 'auth'],   // Custom middleware
],

Handling Webhooks

The webhook endpoint logs all incoming events. Extend the controller or listen to the log to implement your business logic:

// Example webhook payload handling
public function webhook(Request $request)
{
    $event = $request->input('event_type');
    $orderId = $request->input('order_id');
    $status = $request->input('status');

    switch ($event) {
        case 'order_approved':
            // Mark order as approved
            break;
        case 'order_captured':
            // Fulfill the order
            break;
        case 'order_refunded':
            // Process refund
            break;
    }
}

Testing

composer test

Changelog

See CHANGELOG for recent changes.

Security

If you discover security issues, please email fathi.a.n2002@gmail.com instead of using the issue tracker.

License

This package is open-sourced software licensed under the MIT license.

Support

• Issues: GitHub Issues
• Tamara Docs: https://docs.tamara.co
• Author: AL-AGHBARI Fatehi (fathi.a.n2002@gmail.com)

Countries & Currencies