PayTabs Laravel SDK

Official PayTabs Laravel SDK for Payment Gateway integrations. This package provides a Laravel-friendly wrapper around the PayTabs PHP SDK, making it easy to integrate PayTabs payment services into your Laravel application.

PayTabs PHP SDK

Features

• Seamless Laravel Integration: Built as a proper Laravel package with Service Provider and Facade support
• Configuration Management: Environment-based configuration with sensible defaults
• IPN Handling: Built-in Instant Payment Notification (IPN) handling with idempotency support
• Profile Resolution: Support for multiple PayTabs profiles with custom resolvers
• Signature Validation: Automatic signature verification for callbacks
• Type Safety: Full PHP 8.1+ type hints and comprehensive PHPDoc blocks
• Idempotency: Cache-based duplicate delivery prevention for IPNs

Requirements

• PHP >= 8.1
• Laravel >= 11.0
• PayTabs PHP SDK v3

Installation

Install the package via Composer:

composer require paytabs/laravel-sdk

Publish the configuration file:

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

Quick Start

1. Configure Environment Variables

Add the following to your .env file:

PAYTABS_ENDPOINT=ARE
PAYTABS_PROFILE_ID=your_profile_id
PAYTABS_SERVER_KEY=your_server_key

2. Create a Payment Request

use Paytabs\Laravel\Paytabs;
use Paytabs\Sdk\Enums\TranClass;
use Paytabs\Sdk\Enums\TranType;
use Paytabs\Sdk\Request\Payload\PayloadsFactory;
use Paytabs\Sdk\Request\Payload\Parts\CustomerDetails;
use Paytabs\Sdk\Request\RequestsFactory;

// Create the payload
$payload = PayloadsFactory::createHostedPage();

// Add customer details
$payload
    ->buildTransaction(TranType::Sale, TranClass::Ecom)
    ->buildCart('order-001', 'AED', 99.5, 'Order Payment')
    ->buildCustomerDetails(
        CustomerDetails::init('Fname Lname', '+971500000000', 'customer@example.com')
            ->setAddress('UAE', 'State', 'City', 'Street', '12345')
    );

// Create the request
$request = RequestsFactory::createPaymentRequest($payload);

// Submit and get response
$response = Paytabs::submitRequest($request);

if ($response->isFailure()) {
    echo $response->getFailure()->code . ' - ' . $response->getFailure()->message;
    exit;
}

if ($response->isRedirect()) {
    $paymentUrl = $response->getRedirect()->redirect_url;
}

3. Handle IPN Callbacks

The package automatically registers an IPN route at /paytabs/ipn. Configure your IPN handler in config/paytabs.php:

'ipn_handler' => \App\Services\PaytabsIpnHandler::class,

Create your handler:

<?php

namespace App\Services;

use Paytabs\Laravel\Contracts\IpnHandlerInterface;
use Paytabs\Sdk\Response\Responses\Webhook\AbstractTransactionResult;
use Paytabs\Sdk\Response\Payload\Payloads\Callbacks\Ipn;

class PaytabsIpnHandler implements IpnHandlerInterface
{
    public function handleIpn(
        AbstractTransactionResult $transactionResult,
        Ipn $mappedPayload
    ): void {
        // Update your order status
        if ($mappedPayload->isPaymentSuccessful()) {
            // Payment successful

            // Fetch order by Tran Ref
            $order = Order::where('tran_ref', $mappedPayload->tran_ref)->first();
            // Fetch order by Order id
            $order = Order::find($mappedPayload->cart_id);

            $order->update(['status' => 'paid']);
        }
    }
}

Documentation

• Installation Guide - Detailed installation and configuration instructions
• Usage Guide - Comprehensive usage examples and patterns
• IPN Handling - Deep dive into IPN processing and customization

Configuration

The package configuration file config/paytabs.php includes the following options:

Using Multiple Profiles

If you need to use different PayTabs profiles for different transactions:

use Paytabs\Laravel\Paytabs;
use Paytabs\Sdk\Profile\Endpoints\Jordan;
use Paytabs\Sdk\Profile\ProfilesFactory;
use Paytabs\Sdk\Profile\EndpointsFactory;

// Create a custom profile
$profile = ProfilesFactory::createProfile(
    EndpointsFactory::getKsaEndpoint(),
    12345,
    'your_server_key'
);

// Use the custom profile
Paytabs::usingProfile($profile);

// Or use credentials directly
Paytabs::usingCredentials(12345, 'your_server_key', Jordan::CODE);

// Reset to default configuration
Paytabs::usingDefaults();

Security

• Signature Validation: All callbacks are automatically verified using PayTabs signature validation
• Idempotency: Duplicate IPN deliveries are prevented using cache-based locks
• Configuration: Sensitive credentials should be stored in environment variables
• Middleware: IPN endpoint supports custom middleware for additional security layers

Support

For issues and questions:

• GitHub Issues: PayTabs Laravel SDK
• PayTabs PHP SDK Documentation: DeepWiki
• PayTabs Official Documentation: PayTabs Docs

License

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