Laravel 10–13 · Payment SDK · v0.4.1 · MIT
A self-contained, multi-gateway payment SDK for PHP. A factory resolves the right driver, a swappable HTTP transport does the talking, and one contract covers CyberSource Unified Checkout, Fawry, Paymob, PayLink, PayTabs, PayPal, Mastercard MPGS and Authorize.Net.
Domain-driven layers keep the business rules clean and the network at arm's length.
A pure Domain of contracts, commands, results, value objects and enums; a thin Application factory; and an Infrastructure layer for drivers & Laravel adapters. Dependencies point inward — the core never touches the framework.
Resolve any gateway through PaymentGatewayFactory and program against a single PaymentGatewayInterface. Unsupported operations throw UnsupportedOperationException, so the surface is identical everywhere.
The HttpClient and CredentialResolver ports live in the Domain; adapters live in Infrastructure. Ship the retrying Laravel transport in production, swap the in-memory fake in tests — bind only the port you want to replace.
Every driver speaks the gateway's REST API directly and signs its own requests — CyberSource HMAC HTTP-Signature, Fawry SHA-256, Paymob HMAC-SHA512, PayLink HMAC-SHA256, PayTabs server-key auth with HMAC-SHA256 callbacks, PayPal OAuth 2.0 client credentials, Mastercard MPGS HTTP Basic auth, Authorize.Net name/transaction-key auth. No heavy third-party gateway dependencies.
Request bodies are built without hidden uniqid()/time(), so identical inputs produce byte-for-byte identical requests. Every write carries an idempotency key routed to the gateway's native dedup — retries are safe.
Amounts are carried as minor units and never rounded. PHPStan runs at level max with a zero baseline, formatted with Pint, refactor-checked with Rector, and covered by 290+ database-free Pest tests.
Each driver emits a typed domain event after every operation — charge, capture, refund, void, vault, checkout, webhook. One listener on the PaymentEvent interface receives them all, or target a single event. Payloads are queue-safe: ids, amount and result — never the raw request or card data.
Each driver extends AbstractPaymentGateway and implements the same fat contract.
Mint a capture context for the widget, charge the transient token or run the orchestrated flow and verify the signed result JWT, run 3-DS payer-auth, and vault instruments for MIT/CIT stored credentials.
Start a hosted checkout — card, wallet, pay-at-Fawry, MyFawry or instalment — and redirect the payer or hand back a reference code.
Runs the auth → order → payment-key handshake in one call and returns the iframe URL. Integration & iframe ids come from credentials or per-call options.
Create an invoice, then redirect to the hosted checkout or embed it in an iframe, and reconcile later by invoice id. Supports settle, refund, void, reverse-authorization, and card tokenization — store a card in the TMS-backed vault, charge it as a stored credential, and revoke it.
Hosted page, emailable Invoice, reusable PayLink, iframe Managed Form, or an Own Form charge of a payment token. Saves card tokens for recurring / customer-initiated charges, starts repeat-billing agreements, splits settled funds across beneficiaries, and verifies the signed IPN callback.
Create an order and redirect the buyer to approve it, then capture or authorize the approved order with charge. Captures, voids and refunds act on the payment resources; cards vault via the setup-token → payment-token flow for card-on-file charges, and webhooks verify through PayPal's signature API.
Initiate a Hosted Checkout session, then PAY or AUTHORIZE it against the merchant-assigned order and transaction ids. Captures, refunds, voids and reversals settle against the order; cards tokenize for stored-credential charges, 3-D Secure runs through the authentication operations, and webhooks verify with the notification secret.
Charge an Accept.js opaque-data token — the card is tokenised in the browser, so no PAN reaches your server — then capture, refund or void by transaction id. Vault the same token into a CIM profile for MIT/CIT stored-credential charges, look up a transaction for reconciliation, and verify the HMAC-SHA512 webhook signature.
What each driver supports. Anything unsupported throws — the surface never lies.
| Operation | CyberSource UC | Fawry | Paymob | PayLink | PayTabs | PayPal | Mastercard MPGS | Authorize.Net |
|---|---|---|---|---|---|---|---|---|
createCheckoutSession | capture context / orchestrated | hosted / card / wallet | iframe flow | invoice / iframe | hosted / invoice / paylink / managed | order → approval | hosted checkout | — |
charge (transient token) | ✓ | — | — | — | Own Form | approved order | session | Accept.js |
confirmOrchestratedPayment (verify result JWT) | RS256 · flx.jwk | — | — | — | — | — | — | — |
capture | ✓ | Auth/Capture | ✓ | settle | ✓ | ✓ | ✓ | ✓ |
refund | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
void | ✓ | cancel auth | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
reverseAuthorization | ✓ | — | — | ✓ | release | — | ✓ | — |
enroll / validatePayerAuth (3-DS) | ✓ | — | — | — | — | — | ✓ | — |
vault / chargeStoredCredential | TMS · MIT/CIT | — | — | vault · charge · revoke | token · MIT/CIT | vault · MIT/CIT | token · MIT/CIT | CIM · MIT/CIT |
getTransaction / searchTransaction | ✓ | ✓ | ✓ | ✓ | query | order lookup | order lookup | transaction details |
verifyWebhook | ✓ | ✓ | ✓ | ✓ | ✓ | API | secret | HMAC-SHA512 |
The provider auto-registers the factory and ports. Inject the factory — no service location, no new.
# Composer auto-discovers the service provider
composer require hyprpay/paymentsphp artisan vendor:publish --tag=gateway-config$this->app->bind(HttpClient::class, MyHttpClient::class);
$this->app->bind(CredentialResolver::class, MyCredentialResolver::class);External services are fully decoupled. CredentialResolver seamlessly resolves single-tenant static configs and multi-tenant per-tenant credentials.
$gateway = $this->gateways->make(GatewayName::Fawry);
$gateway->charge($request);One charge() call works across every gateway. The factory resolves the driver, so you program against one contract.
use Hyprpay\Payments\Domain\Command\ChargeRequest;
use Hyprpay\Payments\Domain\ValueObject\Money;
use Hyprpay\Payments\Domain\Enum\GatewayName;
use Hyprpay\Payments\Application\PaymentGatewayFactory;
final readonly class ChargeInvoice
{
// Type-hint the factory; Laravel injects it.
public function __construct(
private PaymentGatewayFactory $gateways,
) {}
public function handle(string $tokenFromWidget): void
{
$gateway = $this->gateways->make(
GatewayName::CybersourceUnifiedCheckout,
);
$result = $gateway->charge(new ChargeRequest(
transientToken: $tokenFromWidget,
money: Money::minor(10000, 'EGP'), // 100.00, exact
orderReference: 'ORDER-123', // = idempotency key
));
if ($result->success) {
// $result->status, ->transactionId, ->raw
}
}
}
Retries are safe by construction: bodies are deterministic and every write carries an
idempotency key — routed to v-c-idempotency-key, merchantRefNum,
merchant_order_id, or an Idempotency-Key / PayPal-Request-Id
header, per gateway.
Requires PHP ^8.2 · illuminate/support & illuminate/http ^10 | ^11 | ^12 | ^13 · firebase/php-jwt ^6.10 | ^7.0