Payment events

Stable, provider-agnostic payment events for fulfillment and persistence. This page is the public contract for PaymentEvent schema version 1, ported from packages/core/docs/webhook-events.md plus STABLE_PAYMENT_EVENT_TYPES in packages/core/src/types/stable-payment-event-types.ts.

Cross-links: webhooks (verify, raw body, hooks), outcomes (Payment snapshots), @paykernel/webhooks (inbox claim / lease — not in core).

handleWebhook verifies and normalizes. It does not claim, lease, or set HTTP status. HTTP status lives in @paykernel/integration-http (mapInboxOutcome).

Published as part of @paykernel/core 1.0.0.

Why

Legacy WebhookEvent.type is a free-form, provider-native string (payment_paid, payment_intent.succeeded, PAYMENT.CAPTURE.COMPLETED, TRANSACTION_RESPONSE, …). Apps should not re-implement provider mapping.

Schema versioning

import { PAYMENT_EVENT_SCHEMA_VERSION } from "@paykernel/core";
// PAYMENT_EVENT_SCHEMA_VERSION === "1"
// every PaymentEvent arm includes: schemaVersion: "1"

Inventory field paymentEventSchemaVersion is "1" (public-api.inventory.json).

Compatibility rules (v1)

1. Consumers must switch on schemaVersion then type.
2. Additive optional fields on an arm are OK within schemaVersion: "1".
3. Changing the meaning of a stable type string requires a new schemaVersion.
4. Never silently rename a stable type once shipped (e.g. do not redefine payment.succeeded as “authorized only”).
5. Provider-native names live only on provider.eventType — they are not the public stable contract.

STABLE_PAYMENT_EVENT_TYPES

Source order from packages/core/src/types/stable-payment-event-types.ts (14 names). The inventory file lists the same set alphabetically.

import {
  STABLE_PAYMENT_EVENT_TYPES,
  isStablePaymentEventType,
} from "@paykernel/core";

isStablePaymentEventType(v) is the type guard. Do not invent additional stable names.

Unmapped / ambiguous provider events use a dedicated arm that is not in STABLE_PAYMENT_EVENT_TYPES:

{
  schemaVersion: "1";
  type: "provider.unmapped";
  provider: ProviderEventMetadata;
  payment?: Payment;
  note?: string;
}

Do not invent stable names for ambiguous domains (Stripe invoice / subscription schedules, Paymob redirect-only without status context).

ProviderEventMetadata

type ProviderEventMetadata = {
  gateway: string;
  eventId: string;
  /** Provider-native event type — never silently renamed */
  eventType: string;
  apiVersion?: string;
  livemode?: boolean;
  /** ISO-8601 when the provider says the event occurred */
  occurredAt: string;
  /** ISO-8601 when the SDK received/parsed the event */
  receivedAt: string;
  requestId?: string;
};

Timestamps are ISO-8601 strings, not Date.

PaymentEvent (discriminated union)

Every arm has schemaVersion: "1" and provider: ProviderEventMetadata.

Payment reuses the Phase 6 snapshot type (status, amount?, currency?, references: ProviderReferences, …). PaymentFailure is shape-aligned with PaymentDecline (no secrets in raw).

After verify: claim, then rematch

attachPaymentEvent / webhookEventToPaymentEvent do not claim the inbox. handleWebhook verifies only. Then processVerified on @paykernel/webhooks:

import {
  createWebhookInboxEngine,
  resolveInboxPayloadHash,
  type WebhookInboxStore,
} from "@paykernel/webhooks";
import { mapInboxOutcome } from "@paykernel/integration-http";

declare const store: WebhookInboxStore;
declare const client: import("@paykernel/core").PaymentClient;
declare const rawBody: string;
declare const signature: string | undefined;
declare function fulfillBoundToGatewayPaymentId(id: string): Promise<void>;

const engine = createWebhookInboxEngine({
  store,
  mode: "inline",
  owner: "api-worker-1",
  defaultLeaseMs: 30_000,
});

const webhookEvent = await client.handleWebhook("stripe", rawBody, signature);
// handleWebhook verifies only. Never fulfill here.

const outcome = await engine.processVerified({
  gateway: "stripe",
  providerEventId: webhookEvent.id,
  payloadHash: resolveInboxPayloadHash({
    eventPayloadHash: webhookEvent.payloadHash,
    payloadForHash: webhookEvent.rawPayload ?? webhookEvent,
  }),
  event: webhookEvent.event ?? webhookEvent,
  handler: async (ctx) => {
    const rec = ctx.event as { type?: string; payment?: { status?: string } };
    const paid =
      (rec.type === "payment.succeeded" || rec.type === "capture.completed") &&
      rec.payment?.status === "paid";
    if (!paid) return;
    const gatewayPaymentId = webhookEvent.gatewayPaymentId;
    if (typeof gatewayPaymentId !== "string" || gatewayPaymentId.length === 0) {
      return;
    }
    await fulfillBoundToGatewayPaymentId(gatewayPaymentId);
  },
});
return mapInboxOutcome(outcome); // HTTP lives here, not in @paykernel/webhooks

Provider-native → stable mapping

import { mapProviderEventTypeToStable } from "@paykernel/core";

mapProviderEventTypeToStable("stripe", "payment_intent.succeeded");
// → "payment.succeeded"  (then rematch on domain status — see table)

mapProviderEventTypeToStable("moyasar", "payment_paid");
// → "payment.succeeded"

mapProviderEventTypeToStable("paypal", "PAYMENT.CAPTURE.COMPLETED");
// → "capture.completed"  (capture domain)

mapProviderEventTypeToStable("stripe", "invoice.paid");
// → "provider.unmapped"

Tables are pure data (STRIPE_EVENT_TYPE_MAP, MOYASAR_EVENT_TYPE_MAP, PAYPAL_EVENT_TYPE_MAP, PAYMOB_TOKEN_EVENT_TYPES, STRIPE_UNMAPPED_EVENT_TYPES) plus mapProviderEventTypeToStable. Extra gateways (Tap, MyFatoorah, Hesabe) are not in these core maps.

Mapping policy highlights

Ported from packages/core/docs/webhook-events.md. Do not paraphrase upstream PSP docs.

PayPal capture choice: PAYMENT.CAPTURE.COMPLETED maps to capture.completed, not payment.succeeded. Apps that fulfill when money is captured should handle capture.completed and payment.status === "paid".

PayPal partial auth capture: PAYMENT.AUTHORIZATION.PARTIALLY_CAPTURED dual-writes payment.processing with domain status partially_captured. Do not fulfill remaining authorized amount on this event alone.

Paymob redirect vs processed: Native type is the distinguisher. Browser/query redirect callbacks parse as TRANSACTION_RESPONSE and dual-write payment.processing even when status is paid — so fulfill-on-payment.succeeded handlers never ship from redirect alone. Use processed TRANSACTION or transaction inquiry.

Paymob inbox key: Redirect TRANSACTION_RESPONSE sets WebhookEvent.id to {txn}:redirect; processed TRANSACTION keeps the raw txn id (paymob.gateway.ts paymobWebhookEventId). gatewayPaymentId stays the signed txn id on both. Raw event.id values do not collide, so inbox-deduping on event.id does not swallow later paid. @paykernel/webhooks deriveWebhookEventKey("paymob", id, type) strips the :redirect suffix and qualifies by class: paymob:TRANSACTION_RESPONSE:{txn} vs paymob:TRANSACTION:{txn} (processed + status → paymob:TRANSACTION:{txn}:{status}). Still do not inbox-dedupe on the unsigned Paymob txn id alone.

Stripe / Paymob partial capture: Domain status partially_captured dual-writes payment.processing, not payment.succeeded. Fulfill only with status paid or isPaidOutcome.

Direct maps (runtime constants)

MOYASAR_EVENT_TYPE_MAP:

PAYPAL_EVENT_TYPE_MAP (status-gated exceptions in the policy table still apply):

STRIPE_UNMAPPED_EVENT_TYPES includes invoice.*, customer.subscription.*, and subscription_schedule.* names listed in packages/core/src/types/webhook-event-map.ts. Unknown types return provider.unmapped.

Dual-write with legacy WebhookEvent

import { webhookEventToPaymentEvent } from "@paykernel/core";

const event = await client.handleWebhook("moyasar", body);
// event.type === "payment_paid"           // legacy free-form (unchanged)
// event.stableType === "payment.succeeded"
// event.event.type === "payment.succeeded"
// event.provider.eventType === "payment_paid"

const onlyPaymentEvent = webhookEventToPaymentEvent(event);

Do not rewrite gateway tests to expect stable names on .type without an explicit migration. Dual-write is additive.

Migration from free-form type

1. Prefer event.event or webhookEventToPaymentEvent(event).
2. Switch on schemaVersion + PaymentEvent.type.
3. Inbox-dedupe with deriveWebhookEventKey(gateway, event.id, event.type) from @paykernel/webhooks (Paymob must include notification class).
4. For persistence, call toPersistedPaymentEventEnvelope (never store rawPayload by default); prefer event.payloadHash when present.

Raw payload retention

import {
  toPersistedPaymentEventEnvelope,
  webhookEventToPaymentEvent,
  encryptRawWebhookPayload,
  type RawWebhookPayloadCodec,
} from "@paykernel/core";

const paymentEvent = webhookEventToPaymentEvent(webhookEvent);
const envelope = toPersistedPaymentEventEnvelope(paymentEvent, {
  rawForHash: webhookEvent.rawPayload,
  storedAt: new Date().toISOString(),
});

Core never ships a default encryptor — apps own keys via RawWebhookPayloadCodec. Never re-expose Moyasar secret_token, Stripe signatures, PayPal transmission sigs, or HMAC headers in envelopes, logs, or payloadHash inputs. hashWebhookPayload redacts known secret keys before hashing.

Helpers (public exports)

All of these are runtime exports of @paykernel/core (. only). See core API.

What this does not do

• Does not change handleWebhook return type (still WebhookEvent; dual-write is additive).
• Does not implement the inbox engine. Lease-aware store contracts live in @paykernel/store-contracts / @paykernel/testkit. The inbox engine is @paykernel/webhooks.
• Does not remap gateway parseWebhookEvent .type strings (keeps native; stable names live on stableType / event.type).
• Does not store raw provider payloads by default.
• Does not set HTTP status codes.

Failure path: unknown native type → provider.unmapped → log provider.eventType → do not fulfill. Redirect Paymob TRANSACTION_RESPONSE → payment.processing → do not fulfill. Verify failure → InvalidWebhookError (errors).