# @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.

<!-- begin:auto-docs -->
## Documentation tree

- [stripe](./src/stripe/stripe.md) — `StripeProvider` is the Stripe adapter for `@suaveplan/payment`. It implements the `PaymentProvider` contract (six meth…
  - [stripe](./src/stripe/stripe.md) — `StripeProvider` is the Stripe adapter for `@suaveplan/payment`. It implements the `PaymentProvider` contract (six meth…
<!-- end:auto-docs -->

## Install

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

## Quick start

```ts
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

```ts
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`](./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