Errors

All classes below are defined in packages/core/src/errors.ts and re-exported from packages/core/src/index.ts as @paykernel/core. Catch PaymentError for the family, then branch with instanceof.

import {
  PaymentError,
  InvalidWebhookError,
  InvalidRequestError,
  NetworkError,
  OperationNotSupportedError,
} from "@paykernel/core";

PaymentError.statusCode is metadata on the error object. It is not the HTTP status your webhook route should return. HTTP mapping lives in @paykernel/integration-http (mapInboxOutcome), not in @paykernel/webhooks and not in these class defaults.

Published as part of @paykernel/core 1.0.0.

Classes (errors.ts → index.ts)

Type-only companion (not a class): OperationNotSupportedErrorOptions (capability?, claimedSupport?, message?). Two-arg new OperationNotSupportedError(name, op) remains valid.

NetworkError.afterProviderSubmit

try {
  await client.createPayment(params);
} catch (err) {
  if (err instanceof NetworkError && err.afterProviderSubmit) {
    // Provider may already have accepted the POST.
    // Lookup + decideReconciliationPolicy only.
    // Do NOT createPayment again. Do NOT auto-route a second gateway.
  }
  throw err;
}

afterProviderSubmit is true when the provider may already have accepted a mutating request (timeout / drop / 5xx after POST). Callers must reconcile, not retry as a fresh failure. Preflight auth and GET failures stay false.

On the happy path of create/capture/refund/void, post-submit timeout / drop / 5xx typically becomes outcome: "indeterminate" + reconciliationRequired: true rather than a thrown NetworkError. That is still not a decline. Do not createPayment again. See outcomes.

Webhook verify vs parse

handleWebhook does not set HTTP status. Never fulfill in onWebhookVerified. Claim via @paykernel/webhooks, then fulfill only when the rematched event is payment.succeeded or capture.completed and payment.status === "paid", bound to gatewayPaymentId.

try {
  const event = await client.handleWebhook("stripe", rawBody, signature);
  // verify + parse only — do not fulfill here
} catch (err) {
  if (err instanceof InvalidWebhookError) {
    // authenticity failure
  } else if (err instanceof InvalidRequestError) {
    // parse / shape failure after verify
  } else {
    throw err;
  }
}

Related class (not in errors.ts)

MoneyAmountError extends InvalidRequestError. It is defined in packages/core/src/utils/money.ts and is a runtime export of @paykernel/core (kind: MoneyFailureKind). Branch on kind, not English messages. See money.

Catch pattern

import { PaymentError, isPaidOutcome } from "@paykernel/core";

try {
  const result = await client.createPayment(params);
  if (isPaidOutcome(result)) {
    // paid settlement only
  } else if (result.outcome === "indeterminate" || result.reconciliationRequired) {
    // do not retry createPayment
  }
} catch (err) {
  if (err instanceof PaymentError) {
    // err.code, err.statusCode (object metadata, not webhook HTTP)
  }
  throw err;
}

Full runtime catalog: core API.