PayKernel

PayKernel is a TypeScript payment orchestration toolkit. You compose @paykernel/core (create / capture / refund / verify) with optional inbox, reconciliation, routing, stores, and HTTP adapters at the application layer. Core never depends on those packages.

All packages are published to npm as @paykernel/* (core 1.0.0, gateway-tap/gateway-myfatoorah 1.0.2, testkit 1.0.2, gateway-hesabe 0.1.1, store-d1 0.1.2, integration-http 0.1.2, other engines/stores/frameworks 0.1.x, contracts/sql-foundation 0.1.0). Install with bun add @paykernel/core or npm install @paykernel/core. Source: aashahin/paykernel.

Tested with provider sandbox accounts

The deployed payment lab completed Paymob payments and full/partial refunds and a Moyasar card payment with 3-D Secure against real provider sandbox accounts on 2026-09-11. Authenticated provider inquiries confirmed the app’s settlement totals. Stripe and PayPal also passed authentication/configuration checks.

The gateway validation matrix separates completed account flows, configuration checks, and automated simulation results for all seven gateways. It also records the remaining gaps; these results do not claim production-account testing.

Honesty

• Folder packages/observability publishes as @paykernel/opentelemetry. Do not invent an npm name from the folder.
• @paykernel/internal-sql-store (internal/sql-store) is private. It is a BC shim over @paykernel/sql-foundation. Do not add it to an app.
• Redis is optional. Local SQLite is single-host. :memory: is one process. Turso is remote multi-host and has no /sync export. D1 ≠ Durable Objects ≠ Turso ≠ local SQLite. Memory stores are NON-PRODUCTION.
• No published adapter declares coordinationScope: "multi-region".
• handleWebhook verifies and normalizes. It does not claim, lease, or set HTTP status.
• Never fulfill in onWebhookVerified. Fulfill after an inbox claim, and only when the rematched event is payment.succeeded or capture.completed and payment.status === "paid", bound to gatewayPaymentId.
• 1.0 removed success from GatewayPaymentResult. Use isPaidOutcome / outcome. authorized, approved, and pending are not paid.
• After outcome === "indeterminate" or reconciliationRequired, do not createPayment again. Lookup + decideReconciliationPolicy only.
• Never auto-route a second gateway after timeout / indeterminate / uncertain 5xx.
• HTTP status codes live in @paykernel/integration-http (mapInboxOutcome), not in @paykernel/webhooks.
• Example POST /internal/* routes are unauthenticated test hooks (enableTestHooks) and must not be deployed.

If markdown and implementation disagree, code wins.

Package map

All names below are the package.json "name" fields. Extra Tap / MyFatoorah / Hesabe adapters depend only on @paykernel/core and are not BuiltInGatewayName ("moyasar" | "paypal" | "paymob" | "stripe").

Core and engines

Extra gateways

Built-ins: Moyasar, PayPal, Paymob, Stripe, custom plugins.

Stores

Importing a store package does not apply DDL. Migrate explicitly. Which store: adapter selection.

Integrations and tests

Webhook routes must read the raw body (text()), never json(), before verify. See HTTP integration.

Not published: @paykernel/internal-sql-store (private BC shim), everything under examples/*, the monorepo root, and this docs app (apps/docs).

First payment

import { createPaymentClient, money, isPaidOutcome, moyasarGateway } from "@paykernel/core";

const client = createPaymentClient({
  gateways: {
    moyasar: moyasarGateway({
      secretKey: process.env.MOYASAR_SECRET_KEY!,
      webhookSecret: process.env.MOYASAR_WEBHOOK_SECRET,
    }),
  },
  defaultGateway: "moyasar",
});

const result = await client.createPayment({
  amount: money("100.00", "SAR"),
  currency: "SAR",
  orderId: "order_123",
  callbackUrl: "https://example.com/callback",
  moyasarSource: { type: "token", token: "token_xxx" },
});

if (isPaidOutcome(result)) {
  // Paid-like settlement only (`outcome === "succeeded"` and status `paid`).
} else if (result.outcome === "indeterminate" || result.reconciliationRequired) {
  // Charge may already exist. Schedule reconcile. Do not createPayment again.
} else {
  // declined / pending / authorized — see /guides/outcomes
}

Full branches (declined, requires_action, thrown declines): Quickstart. Production inbox + store + reconcile: Getting started.