Download the PHP package yasser-elgammal/tabby-php without Composer

Tabby PHP SDK

A production-ready, framework-agnostic PHP SDK for the Tabby API.

Build Tabby checkout, payment, capture, refund, and webhook integrations without coupling your application to a specific framework.

Table of Contents

• Tabby PHP SDK
  • Table of Contents
  • Features
  • Requirements
  • Installation
  • Quick Start
  • Configuration
  • Environments
  • Custom HTTP client
  • Security
  • API Overview
  • CheckoutResource
  • PaymentResource
  • WebhookResource
  • WebhookVerifier
  • Payment Lifecycle
  • Services and Builders
  • API Services
  • Fluent Builders
  • Checkout
  • Checkout with multiple items
  • Payments
  • Capture and refund
  • Idempotency
  • Webhooks
  • Register a webhook
  • List and retrieve webhooks
  • Update and delete a webhook
  • Verify the webhook secret
  • Error Handling
  • Validation example
  • Testing
  • Contributing
  • Changelog
  • Links
  • License

Features

• Framework agnostic
• Strongly typed DTOs
• Fluent checkout and item builders
• Checkout API
• Payments API
• Payment capture and refund
• Webhook management and secret verification
• Local input validation
• Structured API, validation, and transport exceptions
• Injectable HTTP client

Requirements

Installation

Install the package via Composer:

Quick Start

Configure the client, create a checkout, and redirect the customer to the URL returned by Tabby:

Configuration

Create a Configuration and pass it to TabbyClient. The merchant code and webhook secret are optional and only need to be supplied when your integration uses them.

Environments

Configure the API base URL according to the environment and region provided by Tabby for your merchant account. Keep it in server-side configuration, for example as TABBY_BASE_URL, rather than hard-coding a regional endpoint in your application.

Custom HTTP client

The client accepts any implementation of HttpClientInterface, which makes the transport replaceable and integrations straightforward to test:

Security

Never expose your Tabby secret key or webhook secret in frontend or mobile applications.

All SDK operations must be executed from your backend. Store credentials in environment variables or a secrets manager, exclude them from source control, and verify the webhook secret before processing webhook data.

API Overview

CheckoutResource

• create(TabbyCheckoutData $checkout)
• createFromArray(array $payload)

PaymentResource

• get(string $paymentId)
• getResponse(string $paymentId)
• all(?PaymentListFilters $filters = null)
• update(string $paymentId, string|PaymentUpdateData $referenceId)
• capture(string $paymentId, string $referenceId, string|int|float|null $amount = null)
• refund(string $paymentId, string $referenceId, string|int|float $amount, ?string $reason = null)
• close(string $paymentId)

WebhookResource

• create(string $url, bool $test = true, array $headers = [])
• all()
• get(string $id)
• getResponse(string $id)
• update(string $id, string $url, bool $test = true)
• delete(string $id)

WebhookVerifier

• verify(?string $providedSecret)

Payment Lifecycle

Use the payment ID returned in CheckoutResponse::$paymentId to retrieve and manage the payment after checkout.

Services and Builders

API services send requests to Tabby and return API responses:

API Services

Fluent builders construct and locally validate the DTOs passed to those services. They do not send API requests:

Fluent Builders

Webhook verification is available separately through $tabby->webhookVerifier().

Checkout

Checkout with multiple items

Build multiple items and add them to a checkout using items():

Payments

Capture and refund

Idempotency

Capture, refund, and other mutation operations should use unique reference IDs.

Do not automatically retry mutation requests unless the same idempotent reference is reused. Reusing the same reference preserves the identity of the original operation and helps prevent accidental duplicate mutations.

Webhooks

Configure webhookSecret when constructing the client if you want to verify the secret received with webhook requests.

Register a webhook

List and retrieve webhooks

Update and delete a webhook

Verify the webhook secret

Pass the secret value received with the webhook request to the verifier before processing the request body. The SDK performs a timing-safe comparison with the configured webhookSecret.

The verifier validates a shared secret value; it does not calculate an HMAC signature from the request payload. Read the header name and delivery requirements from the webhook configuration supplied for your Tabby integration.

Error Handling

All SDK errors inherit from TabbyException.

Validation example

Builders validate input locally when build() is called, before any request is sent:

Testing

The SDK includes a PHPUnit test suite. Inject a mock of HttpClientInterface to test your integration without calling the real API.

Run the suite:

Contributing

Contributions are welcome.

Please open an issue before submitting major changes.

Changelog

See CHANGELOG.md for release history.

Links

• Tabby API Documentation
• Changelog

License

This SDK is open-source software licensed under the MIT License.