Compose @paykernel/core at the application layer. Webhooks, stores, reconciliation, routing, and OpenTelemetry are separate packages — all published (core 1.0.0, others 0.1.x).
Start here
| Guide | Use when |
|---|---|
| Getting started | First createPayment, then inbox + PostgreSQL + reconcile |
| Money | money(), minor units, exponents, 1.0 AmountInput |
| Outcomes | outcome, isPaidOutcome, indeterminate, refunds |
| Webhooks | Verify, PaymentEvent, inbox claim, HTTP mapping |
| Adapter selection | Which @paykernel/store-* to run |
| Composition | Wire core + inbox + store + recon + routing |
| Runtime | Node / Bun / Deno / Workers, PaymentRuntime |
| Best practices | Production checklist (honesty rules) |
| Migrate to 1.0 | Breaking changes from 0.x → 1.0 API |
Honesty that applies on every page
| Fact | Implication |
|---|---|
Packages are published (core 1.0.0, others 0.1.x) |
bun add @paykernel/core works |
Folder packages/observability publishes as @paykernel/opentelemetry |
Do not use the folder name as the npm specifier |
@paykernel/internal-sql-store is private |
Do not install it. It is a BC shim over @paykernel/sql-foundation |
| Redis is optional | Core and the inbox engine do not require it |
| Local SQLite is single-host | :memory: is one process. Do not share a file across hosts |
| Turso is remote multi-host | No /sync export. Not local SQLite, D1, or Durable Objects |
| D1 ≠ Durable Objects ≠ Turso ≠ local SQLite | Separate packages, APIs, and consistency models |
| Memory stores are NON-PRODUCTION | @paykernel/testkit createMemoryStores() only |
No adapter declares coordinationScope: "multi-region" |
Do not invent multi-region strong consistency |
handleWebhook verifies and normalizes |
It does not claim, lease, or set HTTP status |
HTTP status codes live in @paykernel/integration-http |
mapInboxOutcome — not @paykernel/webhooks |
After outcome === "indeterminate" |
Lookup + decideReconciliationPolicy only. Do not createPayment again |
| Never auto-route a second gateway | After timeout / indeterminate / uncertain 5xx |
Core never depends on webhooks, stores, routing, or OpenTelemetry. You wire those at the application layer.
Related
- Quickstart — smallest
createPaymentClientsample - Packages — publishable package map
- Stores — Postgres, Redis, SQLite, Turso, D1, Durable Objects
- Examples — private runnable hosts (not published)