fastify-xstripe

fastify.xStripe

The Stripe SDK client decorated on the Fastify instance as fastify.xStripe — make any Stripe API call from handlers, plugins, or lifecycle hooks.

fastify.xStripe

The full Stripe SDK client, initialized with your apiKey and apiVersion at registration and decorated on the Fastify instance as fastify.xStripe. Available in every route handler, plugin, and lifecycle hook after the plugin is registered.

Breaking change (pre-1.0 standardization): this decorator was renamed from fastify.stripe to fastify.xStripe. Update all references when upgrading.

Signature

fastify.xStripe: Stripe

Stripe is the class exported by the stripe npm package (the Node.js SDK). fastify.xStripe is a fully initialized instance, created once at registration and reused for the app lifetime — no further configuration needed.

Usage

In a route handler

fastify.get("/billing/customer", async (request, reply) => {
  const { stripeCustomerId } = request.user;

  const customer = await fastify.xStripe.customers.retrieve(stripeCustomerId);

  return reply.send({
    email: customer.email,
    balance: customer.balance,
  });
});

Create a Stripe checkout session

fastify.post("/billing/checkout", async (request, reply) => {
  const { priceId } = request.body;
  const { stripeCustomerId } = request.user;

  const session = await fastify.xStripe.checkout.sessions.create({
    customer: stripeCustomerId,
    line_items: [{ price: priceId, quantity: 1 }],
    mode: "subscription",
    success_url: `${process.env.APP_URL}/billing/success`,
    cancel_url: `${process.env.APP_URL}/billing/cancel`,
  });

  return reply.send({ url: session.url });
});

Create a billing portal session

fastify.post("/billing/portal", async (request, reply) => {
  const session = await fastify.xStripe.billingPortal.sessions.create({
    customer: request.user.stripeCustomerId,
    return_url: `${process.env.APP_URL}/account`,
  });

  return reply.redirect(session.url);
});

List active subscriptions

fastify.get("/billing/subscriptions", async (request, reply) => {
  const subscriptions = await fastify.xStripe.subscriptions.list({
    customer: request.user.stripeCustomerId,
    status: "active",
    expand: ["data.default_payment_method"],
  });

  return reply.send({ subscriptions: subscriptions.data });
});

Access from a webhook handler

The Stripe client is also passed as the third argument to every webhook handler — you do not need to access it via fastify.xStripe inside handlers, but you can:

await fastify.register(xStripe, {
  apiKey: process.env.STRIPE_API_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  handlers: {
    "customer.subscription.deleted": async (event, fastify, stripe) => {
      // `stripe` here is the same client as `fastify.xStripe`
      const customer = await stripe.customers.retrieve(event.data.object.customer);
      await sendCancellationEmail(customer.email);
    },
  },
});

Common Stripe Resources

fastify.xStripe exposes the complete Stripe SDK. Commonly used namespaces:

Namespace	Example
`fastify.xStripe.customers`	`customers.create()`, `customers.retrieve()`, `customers.update()`
`fastify.xStripe.subscriptions`	`subscriptions.create()`, `subscriptions.list()`, `subscriptions.cancel()`
`fastify.xStripe.checkout.sessions`	`sessions.create()`, `sessions.retrieve()`
`fastify.xStripe.billingPortal.sessions`	`sessions.create()`
`fastify.xStripe.invoices`	`invoices.list()`, `invoices.pay()`, `invoices.retrieve()`
`fastify.xStripe.paymentIntents`	`paymentIntents.create()`, `paymentIntents.confirm()`
`fastify.xStripe.paymentMethods`	`paymentMethods.list()`, `paymentMethods.detach()`
`fastify.xStripe.prices`	`prices.list()`, `prices.create()`
`fastify.xStripe.products`	`products.list()`, `products.retrieve()`
`fastify.xStripe.refunds`	`refunds.create()`
`fastify.xStripe.webhooks`	`webhooks.constructEvent()` (used internally by the plugin)

For the full API surface see the Stripe Node.js SDK docs.

AI Context

package: "@xenterprises/fastify-xstripe"
decorator: fastify.xStripe
type: Stripe — the `stripe` npm package (Node.js SDK) class, not @stripe/stripe-js
initialized-with: apiKey and apiVersion at plugin registration; created once and reused for the app lifetime
available: all route handlers, plugins, and lifecycle hooks after registration
also-passed-as: third argument to every webhook handler — (event, fastify, stripe)
use-when: make any Stripe API call outside the webhook flow
renamed-from: fastify.stripe (pre-1.0 standardization breaking change)

Edit this pageorReport an issue

Helpers

Utility functions for parsing and working with Stripe event data — amounts, subscriptions, invoices, dates, and metadata.

Webhook Route

The POST webhook endpoint registered by fastify-xstripe — signature verification, event dispatch, and custom handler authoring.