README

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
• ✅ cURL HTTP client (no Guzzle)
• ✅ 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              # true = sandbox, false = production
TAMARA_API_TOKEN=your-api-token-here  # API token from Tamara Merchant Dashboard
TAMARA_COUNTRY_CODE=SA                # SA, AE, KW, BH, QA, OM
TAMARA_CURRENCY=SAR                   # SAR, AED, KWD, BHD, QAR, OMR
TAMARA_INSTALMENTS=3                  # Number of instalments (3, 6, 12)
TAMARA_PAYMENT_TYPE=PAY_BY_INSTALMENTS # PAY_BY_INSTALMENTS or PAY_NEXT_MONTH
TAMARA_LOCALE=en_US                   # en_US or ar_SA
TAMARA_LOGGING=true                   # Enable API request/response logging
# true = enabled | false = disabled
TAMARA_ROUTE_PREFIX=tamara            # URL prefix for package routes

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);

// Build checkout request body with example values
$requestbody = [
    'total_amount' => [                          // Order total amount
        'amount' => 500,
        'currency' => 'SAR',
    ],
    'shipping_amount' => [                       // Shipping cost
        'amount' => 0,
        'currency' => 'SAR',
    ],
    'tax_amount' => [                            // Tax amount
        'amount' => 0,
        'currency' => 'SAR',
    ],
    'order_reference_id' => uniqid('tamara_'),   // Unique order reference
    'order_number' => 'ORD-' . time(),            // Merchant order number
    'items' => [                                  // Order items (max 50)
        [
            'name' => 'Order Payment',
            'type' => 'Digital',                  // Digital or Physical
            'reference_id' => '1',                // Item ID in your system
            'sku' => 'PAYMENT-001',
            'quantity' => 1,
            'unit_price' => [                     // Price per unit
                'amount' => 500,
                'currency' => 'SAR',
            ],
            'total_amount' => [                   // quantity * unit_price
                'amount' => 500,
                'currency' => 'SAR',
            ],
        ],
    ],
    'consumer' => [                               // Customer details
        'email' => 'customer@example.com',
        'first_name' => 'Ahmed',
        'last_name' => 'Ali',
        'phone_number' => '500000000',            // Without country code prefix
    ],
    'country_code' => 'SA',                       // SA, AE, KW, BH, QA, OM
    'description' => 'Payment for order',
    'merchant_url' => [                           // Callback URLs (with optional reference_id)
        'success' => route('tamara.callback', ['reference_id' => 'ORD-12345']),
        'failure' => route('tamara.failure', ['reference_id' => 'ORD-12345']),
        'cancel' => route('tamara.cancel', ['reference_id' => 'ORD-12345']),
        'notification' => route('tamara.webhook'),
    ],
    'payment_type' => 'PAY_BY_INSTALMENTS',       // PAY_BY_INSTALMENTS or PAY_NEXT_MONTH
    'instalments' => 3,                           // 3,4 or 6
    'billing_address' => [                        // Billing address
        'city' => 'Riyadh',
        'country_code' => 'SA',
        'first_name' => 'Ahmed',
        'last_name' => 'Ali',
        'line1' => 'Default Address',
        'phone_number' => '500000000',
    ],
    'shipping_address' => [                       // Shipping address
        'city' => 'Riyadh',
        'country_code' => 'SA',
        'first_name' => 'Ahmed',
        'last_name' => 'Ali',
        'line1' => 'Default Address',
        'phone_number' => '500000000',
    ],
    'platform' => 'Laravel',                      // Platform name
    'is_mobile' => false,                         // true if mobile app
    'locale' => 'en_US',                          // en_US or ar_SA
];

// Create checkout session
$response = Tamara::createCheckout($requestbody);

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

// Handle errors
if (isset($response['errors'])) {
    $errorMessage = $response['errors'][0]['message'] ?? 'Payment failed';
    return back()->with('error', $errorMessage);
}

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', [...]);

Route Parameters

Pass reference_id when calling POST /tamara/pay. It will be forwarded as a query parameter to the callback, cancel, and failure URLs so your app can identify the order when Tamara redirects back.

// Example: POST /tamara/pay with reference_id
$response = Http::post(url('/tamara/pay'), [
    'amount' => 500,
    'order_reference_id' => 'ORD-12345',
    'reference_id' => 'combined_order_42',
    'order_number' => 'INV-2025-001',
    'item_reference_id' => 'product_1',
]);

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