skills/plugins/document-navigator/docs/money/payment/payment-provider-stripe/README.md

@suaveplan/payment-provider-stripe - Universal Stripe adapter for @suaveplan/payment. Implements PaymentProvider against the Stripe REST API via the slim @suaveplan/payment-providers foundation: Bearer auth on every call, Idempotency-Key forwarding on every mutating call, exhaustive Stripe status/refund-status/refund-reason mapping, payment-method normalisation, every error raised as PaymentProviderError with provider: 'stripe' discriminant. No Node / browser / React deps; every HTTP call flows through the injectable FetchLike from the slim core.

Universal Stripe adapter for @suaveplan/payment. Implements PaymentProvider against the Stripe REST API using the slim @suaveplan/payment-providers foundation: Bearer auth on every call, Idempotency-Key forwarding on every mutating call, exhaustive Stripe → domain status / refund-status / refund-reason mapping, payment-method normalisation, every error raised as PaymentProviderError with provider: "stripe" discriminant.

This package is one of the five sibling adapters that re-landed after 2026-05-17-slim-payment-providers split the bundled @suaveplan/payment-providers into a foundation-with-sibling-plugins shape.

Documentation tree

• stripe — StripeProvider is the Stripe adapter for @suaveplan/payment. It implements the PaymentProvider contract (six meth…
  • stripe — StripeProvider is the Stripe adapter for @suaveplan/payment. It implements the PaymentProvider contract (six meth…

Install

bun add @suaveplan/payment-provider-stripe \
        @suaveplan/payment-providers \
        @suaveplan/payment

Quick start

import { PaymentEngine } from "@suaveplan/payment";
import { StripeProvider } from "@suaveplan/payment-provider-stripe";

const provider = new StripeProvider({
    apiKey: process.env.STRIPE_SECRET_KEY ?? "",
});

const engine = new PaymentEngine({ provider });

const intent = await engine.createIntent({
    amount: { amount: 5000n, currency: "USD" },
    captureMethod: "automatic",
    idempotencyKey: crypto.randomUUID(),
});

Compose with the foundation registry

import { ProviderRegistry } from "@suaveplan/payment-providers";
import { StripeProvider } from "@suaveplan/payment-provider-stripe";

const registry = new ProviderRegistry();
registry.register(
    new StripeProvider({ apiKey: process.env.STRIPE_SECRET_KEY ?? "" })
);

const stripe = registry.get("stripe"); // typed as PaymentProvider

Features

• StripeProvider — implements PaymentProvider from @suaveplan/payment (literal name: "stripe", six lifecycle methods).
• Bearer authentication on every request (read + write).
• Idempotency-Key forwarding — when the caller supplies idempotencyKey on CreatePaymentIntentInput or RefundInput, the provider forwards it verbatim to Stripe so retries collapse into a single side effect.
• Exhaustive status mappings — seven Stripe payment-intent statuses, three Stripe refund statuses, four Stripe refund reasons, every unmapped value falls back to failed / other.
• Payment-method normalisation — card carries brand + last4; any other Stripe type maps to wallet; absent payment method maps to undefined.
• Typed errors — every failure is a PaymentProviderError from the slim core with provider: "stripe" discriminant.
• Universal tier — zero Node, browser, React, or platform-specific imports. Runs unchanged on Node, Bun, browsers, and Web Workers.
• Tree-shakeable — sideEffects: false plus per-feature subpath exports.
• 100% test coverage (Istanbul) and 100% docs coverage.

Modules

• src/stripe/stripe.md — StripeProvider class, StripeConfig, StripeIntent / StripeRefund wire-format interfaces.

Related

• @suaveplan/payment — PaymentEngine, WebhookVerifier, PaymentProvider interface, PaymentIntent / Refund / status enums.
• @suaveplan/payment-providers — slim foundation with ProviderRegistry, httpRequest, composeAbortSignal, PaymentProviderError, shared config shapes.
• @suaveplan/payment-provider-paypal, @suaveplan/payment-provider-square, @suaveplan/payment-provider-mollie, @suaveplan/payment-provider-adyen — sibling provider packages.

License

MIT