Download the PHP package ahmedibrahimyassindev/tamara-php-sdk without Composer

Tamara Payment PHP SDK (Generic & Standalone)

Unofficial third-party SDK. This community project is not developed, maintained, or endorsed by Tamara.

A third-party PHP library for integrating Tamara Buy Now Pay Later into PHP applications. The core can be used without a web framework, with optional Laravel integration.

Features

• Framework Independent Core: Use the SDK without a framework; Laravel integration is optional.
• PSR Standards: Uses PSR-4 autoloading and optional PSR-3 Logger (Psr\Log\LoggerInterface).
• Laravel Ready: Out-of-the-box auto-discovery, TamaraPhpSdk Facade, and publishable config.
• One-Call Checkout: Create checkout sessions and redirect customers with minimal boilerplate.
• Unified Webhook Processor: Map events (order_approved, order_authorised, order_captured, order_declined) to your model automatically.
• Fee Calculation Helpers: Opt-in helpers calculate fee amounts; the SDK does not add fees to checkout totals automatically.

Why this SDK?

Tamara also publishes an official PHP SDK as tamara-solution/php-sdk. Choose that package when you want Tamara's official API client and transport integrations. Choose this package when you want its orderable entity trait, webhook processor, and optional Laravel service provider.

The distinct namespace allows both packages to be installed together without this SDK claiming the official SDK's Tamara\ prefix.

Upgrade note for v2

Version 2 changes all SDK imports from Tamara\... to TamaraPhpSdk\.... The optional Laravel facade alias changes from Tamara to TamaraPhpSdk. Update imports and facade references when upgrading from v1.

Installation

Configuration

Set the following environment variables (or pass them directly into TamaraClient):

In Laravel, TAMARA_AUTO_AUTHORISE=true enables authorisation in the webhook processor resolved by the service provider. Set TAMARA_REQUIRES_SHIPPING_ADDRESS=false for checkouts that contain no shippable goods. Laravel webhook processing uses the configured cache store for atomic event claims; use a persistent shared store such as Redis, database, or file cache in production. For capture and refund events, the service-created processor checks Tamara's current remote status so multiple partial captures and refunds can advance the local state through partially_captured, partially_refunded, and their completed states. Models that do not use TamaraOrderableTrait should handle the _tamara_order_status callback field or implement onTamaraPartiallyCaptured() and onTamaraPartiallyRefunded().

Quick Start

1. Make Your Model Orderable

Implement TamaraPhpSdk\Contracts\TamaraOrderableInterface (you can use TamaraPhpSdk\Traits\TamaraOrderableTrait to satisfy all default methods):

The entity must be able to persist tamara_order_id, tamara_checkout_id, and tamara_status when using TamaraOrderableTrait. Eloquent models can use corresponding database attributes (or their supported dynamic attributes); plain PHP entities should declare all three properties. The SDK checks this before creating a Tamara checkout, so a configuration mistake cannot leave an unrecorded remote session. The checkout currency comes from the order's getTamaraCurrency() method. The Laravel default_locale setting controls the default hosted checkout locale; an explicit locale passed to initiateCheckout() takes precedence.

2. Create Checkout Session

3. Handle Webhooks (Secure & Authenticated)

Framework Integration Examples

Laravel Controller Example

Return the processor's http_status as shown so Tamara can retry failed deliveries. retry is true for a 409 event that is ahead of the stored order status and may become valid later, and a 503 event another worker is still processing. Stale or terminal-state events are acknowledged as 200 and ignored. Status meanings:

Advanced API Operations

Authorise approved orders

After receiving order_approved, authorise the order server-side so Tamara can move it to authorised. Enable the processor's opt-in helper when creating it:

The helper calls Tamara's authorise endpoint when an order_approved event is processed. If your account uses Tamara auto-authorisation, leave this disabled.

For capture, $shippingInfo must include shipped_at and shipping_company. tracking_number (string, integer, or null) and tracking_url (string or null) are optional. The method also accepts optional shipping, tax, and discount amounts after $shippingInfo. Tamara cancellation is allowed only while the order is authorised; the SDK checks the remote order status before calling cancel. Canceling the uncaptured remainder after a partial capture is out of scope. Cancel events after capture are treated as stale and acknowledged without changing the local order.

The order builder requires an address by default. For digital services, inject a builder configured with (new TamaraOrderBuilder())->setRequiresShippingAddress(false) into TamaraService. The builder sends zero shipping and tax amounts when the order does not define getTamaraShippingAmount() or getTamaraTaxAmount(). A positive discount is included only when the order defines getTamaraDiscount(), and its payload includes a name. The trait's default item represents the full order amount. If your order has shipping, tax, or a discount, override getTamaraItems() so item totals plus those adjustments match getTamaraAmount(). The optional discount label can be supplied by implementing getTamaraDiscountName(); otherwise the builder uses Discount.

Sandbox verification status

Checkout, approval, and authorisation were exercised against Tamara's sandbox. This account automatically captured the order after authorisation, so manual capture and cancellation have not yet been verified in the sandbox. Webhook payload handling was tested locally; delivery from Tamara to a registered endpoint was not part of that local test.

License

The MIT License (MIT). Please see License File for more information.