fastify-xstripe

fastify.stripe

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

fastify.stripe

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

Signature

fastify.stripe: Stripe

Stripe is the class exported by the stripe npm package. fastify.stripe is a fully initialized instance — no further configuration needed.

Usage

In a route handler

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

  const customer = await fastify.stripe.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.stripe.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.stripe.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.stripe.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.stripe 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.stripe`
      const customer = await stripe.customers.retrieve(event.data.object.customer);
      await sendCancellationEmail(customer.email);
    },
  },
});

Common Stripe Resources

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

Namespace	Example
`fastify.stripe.customers`	`customers.create()`, `customers.retrieve()`, `customers.update()`
`fastify.stripe.subscriptions`	`subscriptions.create()`, `subscriptions.list()`, `subscriptions.cancel()`
`fastify.stripe.checkout.sessions`	`sessions.create()`, `sessions.retrieve()`
`fastify.stripe.billingPortal.sessions`	`sessions.create()`
`fastify.stripe.invoices`	`invoices.list()`, `invoices.pay()`, `invoices.retrieve()`
`fastify.stripe.paymentIntents`	`paymentIntents.create()`, `paymentIntents.confirm()`
`fastify.stripe.paymentMethods`	`paymentMethods.list()`, `paymentMethods.detach()`
`fastify.stripe.prices`	`prices.list()`, `prices.create()`
`fastify.stripe.products`	`products.list()`, `products.retrieve()`
`fastify.stripe.refunds`	`refunds.create()`
`fastify.stripe.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.stripe
type: Stripe  # the stripe npm package class
initialized-with: apiKey, apiVersion at plugin registration
available: all route handlers, plugins, lifecycle hooks after registration
also-passed-as: third arg to every webhook handler (event, fastify, stripe)

AI Context

package: "@xenterprises/fastify-xstripe"
decorator: fastify.stripe
use-when: Access the full Stripe SDK client for any Stripe API call outside the webhook flow
type: Stripe (full @stripe/stripe-js SDK instance)

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.