README

The Tabby Laravel Package (tabbyai/laravel) provides an easy-to-use integration with Tabby, a payment gateway service, allowing developers to create seamless checkout sessions within their Laravel applications.

Features

1. Easy Setup: Install via Composer and configure with API keys.

2. Checkout Management: Create and retrieve checkout sessions, including payment URLs for easy redirection.

3. Payment Management: Retrieve, update, capture, refund, close payments, and list payments with filters.

4. Webhook Management: Register, retrieve, update, and delete webhooks to receive real-time event notifications.

5. Error Handling: Built-in exception management for smoother integration and user experience.

How to Use

Step 1: Installation

To install the package via Composer, run:

composer require tabbyai/laravel

Step 2: Configuration

Before you use the TabbyService, make sure you have the required API keys and configuration values. You need:

• merchantCode (your Tabby merchant code)
• publicKey (your Tabby public key)
• secretKey (your Tabby secret key)
• currency (default is SAR but can be changed)

Step 3: Create an Instance of TabbyService

You need to initialize an instance of TabbyService by passing the necessary configuration values.

use Tabby\Services\TabbyService; $tabbyService = new TabbyService( merchantCode: 'your_merchant_code', publicKey: 'your_public_key', secretKey: 'your_secret_key', currency: 'SAR' // Optional, default is SAR );

Step 4: Using Checkout Functions

Creating a Checkout Session

To create a checkout session, you'll need the buyer's information, order details, and shipping address.

use Tabby\Models\Buyer; use Tabby\Models\Order; use Tabby\Models\ShippingAddress; use Tabby\Models\OrderItem; try { // Sample buyer data $buyer = new Buyer( phone: '500000001', email: 'card.success@tabby.ai', name: 'John Doe', dob: '1990-01-01', ); // Sample order data $order = new Order( referenceId: 'order-001', items: [ new OrderItem( title: 'Product Name', category: 'electronics', unitPrice: 100, quantity: 1, referenceId: 'prod-001', description: 'Product Description', ), ], ); // Sample shipping address data $shippingAddress = new ShippingAddress( city: 'Al-Khobar', address: 'Street Address', zip: '12345', ); // Create a checkout session $checkoutSession = $tabbyService->createSession( amount: 200, buyer: $buyer, order: $order, shippingAddress: $shippingAddress, description: 'order description', successCallback: 'https://example.com/success', cancelCallback: 'https://example.com/cancel', failureCallback: 'https://example.com/failure', // lang: 'ar', // optional // buyerHistory: $buyerHistory, // optional // orderHistory: $orderHistory, // optional ); // Fetch the payment url from the checkout session $paymentUrl = $checkoutSession->getPaymentUrl(); // Redirect to the payment page return redirect($paymentUrl); } catch (Exception $e) { // Handle exceptions return response()->json(['error' => $e->getMessage()], 500); }

This will return a CheckoutSession object containing session details.

Retrieving a Checkout Session

To retrieve a previously created checkout session, use the session ID:

$checkoutSession = $tabbyService->retrieveCheckoutSession('session_id_here');

This will return a CheckoutSession object containing session details.

Step 5: Using Payment Functions

Retrieve a Payment

To retrieve details of a specific payment by its ID:

$payment = $tabbyService->retrievePayment('payment_id_here');

Update a Payment

$updatedPayment = $tabbyService->updatePayment( paymentId: 'payment_id_here', // Payment ID referenceId: 'new_reference_id', // Optional updated reference ID deliveryTracking: [ ['tracking_number' => 'xxx', 'courier_code' => 'yyy'] ], );

Capture a Payment

Capture a payment after the transaction:

$capturedPayment = $tabbyService->capturePayment( paymentId: 'payment_id_here', // Payment ID amount: 100.00, // Amount referenceId: 'reference_id_here' // Optional reference ID );

Refund a Payment

$refundedPayment = $tabbyService->refundPayment( paymentId: 'payment_id_here', // Payment ID amount: 50.00, // Amount to refund referenceId: 'reference_id_here', // Optional reference ID reason: 'refund reason' // Optional );

Close a Payment

$closedPayment = $tabbyService->closePayment('payment_id_here');

List of Payments

list($payments, $pagination) = $tabbyService->listPayments( createdAtGte: '', // Optional createdAtLte: '', // Optional status: null, // Optional limit: 10, // Optional offset: 0, // Optional );

Step 6: Using Webhook Functions

Register a Webhook

To register a new webhook for receiving events from Tabby:

$webhook = $tabbyService->registerWebhook( url: 'https://your-domain.com/webhook-url', // URL to receive webhook notifications isTest: true, // Test mode (optional) headerTitle: 'Custom-Header-Title', // Optional headerValue: 'Custom-Header-Value' // Optional );

Retrieve All Webhooks

To retrieve all registered webhooks:

$webhooks = $tabbyService->retrieveAllWebhooks();

Retrieve a Specific Webhook

$webhook = $tabbyService->retrieveWebhook('webhook_id_here');

Update a Webhook

$webhook = $tabbyService->updateWebhook( webhookId: 'webhook_id_here', url: 'https://your-domain.com/webhook-url', // URL to receive webhook notifications isTest: true, // Test mode );

Delete a Specific Webhook

$webhook = $tabbyService->deleteWebhook('webhook_id_here');

Exception Handling

The package throws exceptions for any failed API requests or missing configuration. Ensure to handle them properly in your code to provide a smooth user experience.

try { // your code } catch (Exception $e) { // handle the error }

License

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