Download the PHP package digitaltunnel/jeelpay without Composer

JeelPay for Laravel

A typed, testable SDK for JeelPay — Saudi Arabia's "Study Now Pay Later" platform — with first-class Laravel integration. Supports both Items (universities, courses, training centers) and Schooling (K-12) checkout flows out of the box.

Built against the official JeelPay developer docs. Endpoints, payloads, statuses and webhook signatures are verified to match the documented API.

• OAuth 2.1 client credentials with mandatory token caching (Laravel Cache, configurable store)
• Fluent request builders for Items + Schooling checkouts with built-in Saudi-specific validation
• Readonly DTOs (CheckoutResult, CheckoutStatusResult, RefundResult, WebhookPayload)
• Auto-generated idempotency keys (UUID v4) on every checkout POST — reuse on retries to dedupe
• tx_id captured from response headers on every call for support debugging
• Auto-registered webhook endpoint outside the web middleware group — no CSRF dance
• HMAC-SHA256 signature verification on incoming webhooks
• Idempotent webhook de-duplication via fingerprint hash
• Optional jeelpay_checkouts, jeelpay_refunds, jeelpay_webhook_events tables — auto-mirrored
• Test helper JeelPayFake with realistic fixtures + signed-webhook builder

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13

Installation

Publish the config:

Publish & run the migrations (opt-in):

Configure your .env:

Verify the webhook route is live:

Quickstart

Items checkout (universities, institutes, training centers)

Schooling checkout (K-12)

Idempotent retries

If your network call timed out, retry with the same idempotency key:

Status & refunds

Webhooks

The package auto-registers POST {config.webhook.path} (default webhooks/jeelpay) outside the web middleware group, so CSRF is never applied.

Listen for typed events:

Available events:

• CheckoutPending · CheckoutSucceeded · CheckoutRejected · CheckoutExpired
• WebhookReceived (catch-all, fires for every webhook)

Signature verification

The middleware computes base64(HMAC-SHA256(client_secret, raw_body)) over the raw request body and compares it (timing-safe) against the X-Jeel-Signature header. The raw body is preserved through $request->getContent() — never re-serialise the JSON before checking.

Idempotent de-duplication

When jeelpay.persistence.webhook_events.enabled is true (default), the controller stores every webhook keyed by a fingerprint of (checkout_id|status|raw_body). If JeelPay retries the exact same event, no duplicate event is dispatched.

Disabling auto-registration

Then register your own route:

Persistence (opt-in)

Three tables ship via --tag=jeelpay-migrations. Each layer has an independent enable flag.

jeelpay_webhook_events

Fingerprint-based audit + idempotency log. Auto-written by the controller when JEELPAY_LOG_WEBHOOK_EVENTS=true.

jeelpay_checkouts

Local mirror of every checkout (created by createItems()/createSchooling()/find() and updated by webhooks). Enable with JEELPAY_PERSIST_CHECKOUTS=true. Polymorphic payable_* columns let you link a checkout to any of your domain models.

jeelpay_refunds

Mirror of every refund call. Enable with JEELPAY_PERSIST_REFUNDS=true.

Token caching

The OAuth endpoint is rate-limited. The package caches tokens in your default Laravel cache store (override with JEELPAY_CACHE_STORE) under the key jeelpay.access_token, refreshing 30 seconds before expiry. Tokens are also memoised per request to avoid re-deserialising on every call.

Exception handling

The full hierarchy:

Every ApiException exposes txId() — include it in your support tickets.

Configuration reference

Every option in config/jeelpay.php is environment-driven. The full list:

The base URLs (sandbox → production):

Statuses, enums & DTOs

CheckoutStatus (->find()->status, webhook $payload->status):

Helpers: $status->isTerminal(), $status->isPaid().

RefundStatus ($refund->status):

Helpers: $status->isTerminal(), $status->isDone(), $status->isRejected().

Result DTOs (all readonly):

• CheckoutResult → checkoutId, redirectUrl, type, idempotencyKey, referenceId, txId, metadata, raw
• CheckoutStatusResult → checkoutId, status, type, referenceId, txId, metadata, raw + isPaid()/isPending()/isExpired()/isRejected()
• RefundResult → id (withdrawalRequestId), status, rejectionReason, referenceId, checkoutId, txId, raw + isDone()/isRejected()
• WebhookPayload → checkoutId, status, type, referenceId, metadata, rawBody, raw

Testing

The package ships JeelPayFake to stub every JeelPay HTTP call (auth, checkouts, refunds) and to build signed webhooks — no network access needed.

Available JeelPayFake helpers: fakeAuth(), fakeItemsCheckoutCreated(), fakeSchoolingCheckoutCreated(), fakeRefundSubmitted(), fakeRefundStatus(), fakeValidationError(), sign(), signedWebhook(), assertSentTo(), assertNothingSent(), assertSentCount().

Contributing & quality gate

The suite runs against an in-memory SQLite database via Orchestra Testbench — no setup required.

Sandbox info

• API: https://api.sandbox.jeel.co
• Auth: https://auth.sandbox.jeel.co
• Test card: 4111 1111 1111 1111, exp 05/30, CVV 123, 3DS code Checkout1!
• Test buyer phone: any valid Saudi mobile (e.g. 512345678), OTP 3333, passcode 100000

License

MIT.