Stripe

@vitnode/stripe connects VitNode payments to Stripe Checkout, Stripe's hosted payment page. This guide sets it up in test mode, so no real money moves, and ends with a test purchase through the payments-demo plugin.

Before you beginCopy Anchor Link

• A VitNode app with a database. The VitNode repository's apps/web already includes the payments-demo plugin used in the check at the end.
• A Stripe account. Everything below uses its test mode (a sandbox).
• The Stripe CLI, to forward webhooks to your machine.

Set up StripeCopy Anchor Link

bun i @vitnode/stripe

import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { StripePaymentAdapter } from '@vitnode/stripe'

export const vitNodeApiConfig = buildApiConfig({
  payments: {
    providers: [
      StripePaymentAdapter({
        id: 'stripe-main',
        secretKey: process.env.STRIPE_SECRET_KEY,
        webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
      }),
    ],
  },
})

STRIPE_SECRET_KEY=sk_test_your_key

stripe login
stripe listen \
  --events checkout.session.completed,checkout.session.async_payment_succeeded,checkout.session.async_payment_failed,checkout.session.expired \
  --forward-to localhost:3000/api/@vitnode/core/payments/webhooks/stripe-main

STRIPE_WEBHOOK_SECRET=whsec_from_stripe_listen

bun run db:migrate

Check the resultCopy Anchor Link

1. Sign in, open /payments-demo and select Buy now. You land on Stripe's hosted page with a $5.00 item.
2. Pay with the test card 4242 4242 4242 4242, any future expiry date and any CVC. Stripe sends you back to /payments-demo/purchases/{id}.
3. The page shows Payment confirmed once the webhook is processed, usually within seconds. stripe listen logs a 200 response for checkout.session.completed.
4. Check a failure: start another purchase as a different member and pay with 4000 0000 0000 0002. Stripe declines the card on its page and the session stays open, so VitNode keeps the payment pending, not failed.

A redelivered event answers {"outcome":"duplicate"} and changes nothing, so resending one from the Dashboard is always safe.

Events from stripe trigger are answered {"outcome":"ignored"}: they describe sessions VitNode did not create, so they carry no VitNode metadata. Test through the demo instead.

How Stripe events map to statusesCopy Anchor Link

Delayed payment methods, such as bank debits, complete the session before the money settles. The customer sees Payment processing until Stripe sends the second event, which can take days. Card payments are paid at completion.

Every other event type is acknowledged and ignored, as are sessions created by another instance that shares the Stripe account.

OptionsCopy Anchor Link

The adapter pins Stripe API version STRIPE_API_VERSION (exported from @vitnode/stripe), the version of its stripe SDK. Choose the same version for a Dashboard webhook endpoint.

Going liveCopy Anchor Link

• Create a webhook endpoint in the Dashboard for https://your-site.example/api/@vitnode/core/payments/webhooks/stripe-main with the four events above, and use its signing secret.
• Use live keys only in production, and test keys everywhere else. A second instance id per account keeps test and live data apart in one database.
• Run a cron adapter or external cron so reconcile-payments can recover missed webhooks.
• The webhook route spends only the safety cap, not the per-IP write budget, so a burst of Stripe deliveries is not refused. Its signature check is what keeps other callers out.

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link