Download the PHP package paytabs/php-sdk without Composer

PayTabs PHP SDK (v4)

Official PHP SDK for integrating with PayTabs Payment Gateway.

Requirements

• PHP ^8.1
• cURL extension enabled

The SDK targets PHP 8.1 so it can be embedded in e-commerce platform plugins that still run on older merchant hosting. Contributing to the SDK requires PHP 8.2 or newer — see CONTRIBUTING.md.

Before you start

You need a PayTabs merchant account. From the merchant dashboard, take:

• Profile ID and Server Key — under Developers → Key management.
• Your region, which decides the endpoint. Credentials are region-scoped: a key issued for KSA will not authenticate against the UAE endpoint. Pick the matching helper (createKsaProfile, createUaeProfile, …) or pass an endpoint explicitly to ProfilesFactory::createProfile().

Use a test/sandbox profile while integrating, and keep credentials in environment variables rather than in the repository.

Install

Quick Start

The payment is not finished when the shopper is redirected. Confirm the outcome in your return and IPN handlers, and verify the signature there before trusting anything: docs/usage/Webhooks.md.

Error Handling

Every exception the SDK throws implements PaytabsExceptionInterface, so one catch block covers all of them:

Catch a specific class when you need to react differently:

Because each class still extends the same SPL type as before, existing catch (\RuntimeException) code keeps working unchanged.

A declined payment is not an exception. It arrives as a normal response: check $response->isFailure(), then getFailure()->code and ->message.

Retries. PayTabs has no idempotency-key header, and cart_id is your own reference which the gateway does not enforce as unique. Retrying a timed-out payment request can therefore charge the shopper twice, so the SDK never retries automatically. After a timeout, query the transaction before resending.

Security Notes

• Do not log card data, CVV, full tokens, or full webhook signatures.
• Store credentials in environment variables, not in repository files.
• Always verify webhook signatures and reject invalid requests.

See webhook verification guide: docs/usage/Webhooks.md

Logging Configuration

The SDK provides a default file logger helper:

You can also inject any custom Psr\Log\LoggerInterface instance via Http::setLogger() or Paytabs::setLogger().

Default log location. With no argument, PaytabsLogger writes a daily file to /var/log/paytabs-sdk/. Pass an explicit path to change it:

Log files are created 0600 and the directory 0700, because gateway payloads pass through them.

Redaction. All SDK loggers strip cardholder data and credentials before writing: PANs are masked to first-6/last-4, and CVV, Authorization headers and key-like fields are removed — including inside an already-serialised JSON body. If you inject your own logger it receives the same redacted context. Do not re-serialise the raw request payload yourself and log it through a different channel.

BrowserLog is for local debugging only. It writes into the HTTP response; never enable it in production.

Diagnostics during response mapping (for example an unrecognised transaction status) go through a separate logger that defaults to error_log(), so a full disk or an unwritable path can never fail a payment:

Strict Response Mapping Mode

By default, response payload mapping is tolerant. Unknown enum values (for example unseen transaction status/class/type) are mapped to Unknown and logged.

You can enable strict mode to throw a dedicated exception instead:

Documentation

• Architecture: ARCHITECTURE.md
• Diagrams: docs/diagrams
• Payment Request guide: docs/usage/PaymentRequest.md
• Invoices guide: docs/usage/Invoices.md
• Webhooks guide: docs/usage/Webhooks.md
• Samples: Samples

Project Governance

• License: LICENSE
• Security policy: SECURITY.md
• Contribution guide: CONTRIBUTING.md
• Changelog: CHANGELOG.md
• Release checklist: docs/release-checklist.md
• Support policy: SUPPORT.md

Samples Setup

1. Copy Samples/.env.sample to Samples/.env.
2. Replace placeholder values with sandbox credentials.
3. Run samples locally and expose callback URL when needed.

Keep the working copy out of your web docroot. Samples/.env holds a profile ID and server key in plaintext and is read with parse_ini_file(). If the checkout sits under a docroot (for example /var/www/html/…), a request to …/Samples/.env is served as plaintext by any server without a dotfile deny rule — no PHP execution required. Clone outside the docroot, or deny dotfiles:

Samples/.env is gitignored and must never be committed. If a real key has been exposed, rotate it in the PayTabs merchant dashboard.

Development Commands

Live gateway tests are opt-in only:

Versioning

This SDK follows semantic versioning. Breaking changes are introduced only in major versions.

Support

For integration support, use PayTabs official support channels. For security vulnerabilities, report via the PayTabs Bug Bounty Program and follow SECURITY.md. Public issues are intended for reproducible SDK bugs and enhancement requests.