Sham Cash Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy for payment integration: This package is the "buy" (well, adopt-mit-licensed) path for adding ShamCash as a payment rail. It collapses a deceptively expensive integration — JWE compact encryption with exact header/IV/tag rules, a {encData, agentKey} envelope, result === 2500 success semantics, webhook token verification with exp/iat skew checks — into a composer require and one Client entry point. The alternative is a bespoke crypto implementation that your team will get subtly wrong.
• Scoping payment features realistically: The public surface tells you exactly what the rail can do today: create bill, fetch bill, refund bill, list/iterate transactions, parse webhook. Anything a stakeholder asks for outside that list is a roadmap item, not a config flag. Use this to push back early on "can we do partial refunds / saved cards / recurring billing?" — not in this SDK's vocabulary.
• Refund and idempotency policy: The SDK intentionally refuses to invent an idempotency key and never retries money calls. That is a product decision you inherit: your checkout flow must generate and persist a stable 10–100 character key per refund attempt, and your UX must handle a repeat refund as "same key, same outcome." Decide this in design, not in a production incident.
• Webhook-as-source-of-truth architecture: The docs explicitly forbid polling getBill and frame it as a one-shot fallback "at least 10 minutes after create, and only when the webhook never arrived." That is a strong architectural steer — you are committing to an event-driven order state machine with a 5-minute token TTL and 30-second clock skew tolerance. Your infrastructure needs reliable inbound webhook delivery and reasonably synced clocks.
• Callback/redirect UX and configuration model: callbackUrl and redirectUrl can be client defaults with per-call overrides, but ShamCash still requires both on the wire, and ShamCash does not append billNo to redirectUrl. So you must own correlation (session/state param) on the redirect yourself. This is a concrete design constraint for the returning-user experience.
• Multi-market roadmap: A maintained English/Arabic README pair signals an Arabic-speaking merchant base. If ShamCash is a target rail for MENA, this is evidence the vendor is serious about that segment — relevant to localization and support planning.
• Vendor concentration and resilience: This is a ShamCash-specific library with 12 stars and zero dependents. It supports the decision "we integrate ShamCash, but we isolate it" — i.e., wrap it behind your own payment port so a swap is a module change, not a rewrite.

When to Consider This Package

Consider adopting when:

• ShamCash is a confirmed, contracted payment rail and you need bill creation, refunds, transaction reconciliation, and verified webhooks in a PHP codebase.
• You are on PHP 8.2+ (CI matrix is 8.2/8.3/8.4) and already use Composer and Guzzle 7.
• You want the crypto and wire protocol owned by a library rather than your application — JWE dir/A256GCM, protected-header-as-AAD, Base64-decoded 32-byte key, decimal-string amounts without float casts.
• You can accept the operational model: webhook-first, no auto-retry on money operations, caller-supplied idempotency keys, tight token TTL and clock-skew requirements.
• You value the guardrails: InvalidArgumentException before any HTTP call, typed ApiException vs TransportException vs CryptoException, TLS verification pinned on even with an injected PSR-18 client, and logging that must never touch secretKey, encData, or decrypted payloads.

Look elsewhere or plan extra work when:

• You need a Laravel-native package. This is deliberately framework-free — no service provider, no config publishing, no facade, no queue integration, no Eloquent models for bills. The maintainers state bridges belong in other repositories. Budget a thin internal adapter (bind Client in the container, map exceptions to your domain errors).
• You need features outside create/get/refund/list/webhook — subscriptions, partial refunds, multi-currency conversion, payout/settlement APIs.
• You need a vendor with a large ecosystem. Twelve stars and zero dependents means no community safety net; treat the maintainer as a single point of support and read src/ before you ship.
• You cannot meet the webhook and clock requirements — no public HTTPS endpoint, unreliable delivery, or unsynchronized hosts will make parseWebhook reject legitimate callbacks.
• Your stack is not PHP/Composer, or you are below PHP 8.2.
• You need SLA-backed support or a vendor security program beyond a GitHub private advisory channel.

Non-negotiable pre-adoption checks: confirm the license (MIT, per docs), verify the release tag exists on Packagist rather than trusting a date, and validate the whole flow against the dev API using local/sandbox.php-style credentials held outside version control.

How to Pitch It (Stakeholders)

For executives: ShamCash is a payment rail we can integrate in days instead of weeks. This MIT-licensed PHP SDK takes on the hard, failure-prone parts — payment-grade encryption, the exact provider wire protocol, and cryptographically verified webhook handling — so our engineers write business logic, not crypto. It is deliberately narrow: bill creation, refunds, transaction reconciliation, and webhooks. That narrowness is the point; it keeps our exposure small and auditable. Two things to flag: it is a small, single-maintainer project (12 stars, no downstream dependents), so we should wrap it behind our own internal payment interface to keep a future switch to another rail cheap; and it requires a reliable public webhook endpoint and accurate server clocks, both of which we should confirm before committing to a launch date.

For engineering: This is a framework-free Composer library, PHP 8.2+, Guzzle 7 required, PSR-18 client and PSR-3 logger injectable. Client is the only entry point — createBill, getBill, refundBill, listTransactions, eachTransaction, parseWebhook; everything in Crypto, Http, and Support is @internal, so don't reach into it. Errors are typed by cause: local mistakes throw InvalidArgumentException before any HTTP call, provider rejections and succeeded !== true throw ApiException with a ResultCode, network/parse failures throw TransportException, and bad keys throw CryptoException — map these to distinct user-facing outcomes rather than one generic "payment failed." We own refund idempotency keys (10–100 chars, never auto-retried, repeat with the same key); a duplicate createBill may return 1704, so catch that and call getBill. Do not poll getBill — one shot, ten minutes minimum, webhook-missed only. parseWebhook wants the raw body string, unmodified. Never log secrets, ciphertext, or decrypted payloads, and keep TLS verification on. Our work item is a Laravel bridge: container binding, config, exception-to-domain mapping, and an order state machine driven by webhooks — the SDK gives us none of that by design. Verify installs against the dev API with credentials kept in gitignored local files.