Payments

One-time payments on top of Stripe. The module is event-agnostic: other modules (for example Events) ask it to charge something and are told through hooks when the money arrives.

• Stripe events are the only inbound signal. The module has no webhook route of its own. It registers a handler with registerStripeEventHandler for checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired and charge.refunded. The success redirect never marks anything as paid.
• Prices are inline. Checkout sessions use price_data, so no Stripe products or prices need syncing between environments.
• Hooks, not coupling. State transitions are announced through Nitro hooks; consumers filter on payment.referenceType.

Quick setup

export default defineNuxtConfig({
  modules: ['@frigear-nu/users', '@frigear-nu/stripe', '@frigear-nu/payments'],
  payments: {
    settings: { checkoutExpiresInMinutes: 30 },
  },
})

Options

Server

Auto-imported in Nitro:

@frigear-nu/payments/utils exports the types below and sumItems(items), which totals items in minor units.

type PaymentStatus = 'pending' | 'paid' | 'failed' | 'expired' | 'refunded' | 'partially_refunded'

type PaymentItem = {
  name: string
  description?: string
  amount: number      // unit amount in minor units (cents / øre)
  currency: string    // ISO 4217
  quantity?: number   // default 1
}

type CreatePaymentInput = {
  userId: number
  items: PaymentItem[]                           // one currency, total above zero
  reference?: { type: string, id: string }       // e.g. { type: 'event_ticket', id }
  successUrl: string                             // absolute URL or path on the current origin
  cancelUrl: string
  description?: string
  expiresInMinutes?: number                      // overrides settings.checkoutExpiresInMinutes
  metadata?: Record<string, string>
}

type CreatePaymentResult = { payment: PaymentDto, url: string }

type PaymentDto = {
  id: string                      // pay_...
  userId: number
  status: PaymentStatus
  amount: number
  currency: string
  description: string | null
  referenceType: string | null
  referenceId: string | null
  refundedAmount: number
  paidAt: string | null           // ISO
  createdAt: string               // ISO
}

Behaviour worth knowing:

• successUrl and cancelUrl are validated (relative path or same origin) when event is passed; without event they must be absolute http(s) URLs. Invalid URLs throw 400.
• resumePayment throws 404 for an unknown payment, and 409 when it is already paid or refunded. For an expired session it creates a new one from the stored items (same names, descriptions, unit amounts and quantities), runs payments:checkout:before and the same return URL validation as createPayment, and reuses the expired session's success and cancel URLs. expiresInMinutes is not stored; the configured checkoutExpiresInMinutes applies. Payments created before items was stored fall back to a single line item for the total, named after the description or Payment; the hook still runs.
• refundPayment throws 409 unless the payment is paid or partially_refunded, and 400 for an amount that is not positive or exceeds what is left to refund.

Hooks

Register with nitro.hooks.hook(...) in a Nitro plugin.

type PaymentHookContext = { payment: PaymentDto }

type CheckoutBeforeContext = {
  event?: H3Event
  userId: number
  reference?: { type: string, id: string }
  params: Stripe.Checkout.SessionCreateParams   // mutable
}

Transitions are conditional updates: a redelivered Stripe event emits nothing twice, and a paid payment is never downgraded by a late expired event.

Routes

Both user routes also accept bearer tokens and OAuth access tokens that carry the scope. The scopes are registered with Auth as payments:read ("Read your payments") and payments:write ("Resume your payments").

App

With Widget and Admin installed, the module adds a Payments tab (order 20) and a Last payment card to the admin user page of Users (admin.users tab area, admin.users.overview widget area).

The Payments tab is a TableCard with a read-only UTable (amounts through useFormat().money, status badges coloured with statusColor); there is no refund action yet, so rows have no menu. Last payment is a SectionCard with a DescriptionList. On the admin dashboard, Revenue, 30 days is a StatCard and Recent transactions a ListCard that links to the users list. All of them are built from the UX patterns of @frigear-nu/ui.

Database

One payments table.

Membership payments

When @frigear-nu/subscriptions is installed next to this module, every membership invoice (invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible) is stored as a payment with referenceType: 'subscription' and referenceId set to the Stripe subscription id. They appear in the admin user Payments tab and Last payment card, fire the payments:* hooks (filter on referenceType) and are returned by the my-payments MCP tool. Refunds are applied like any other payment through charge.refunded. Without this module, @frigear-nu/subscriptions behaves as before and records nothing. Zero-amount invoices (trials, full discounts) are skipped, and only invoices received after upgrading are stored.

recordInvoicePayment(input: InvoicePaymentInput) is the auto-imported server util behind this; it is idempotent per invoice id.

MCP

Set settings.mcp: true to expose my-payments (scope payments:read): the signed-in user's own payments, newest first, with an optional limit. amount and refundedAmount are in whole currency units (52.2 = 52.20), not minor units, and currency is upper-case.

Translations

da and en locale files are registered with Module Kit under payments.*: payments.status.<status> (one key per PaymentStatus), payments.defaultDescription and payments.admin.* for the admin tab. API error messages stay English. Override keys in your app's i18n/locales/<code>.json (see overriding module strings):

{ "payments": { "status": { "partially_refunded": "Partly refunded" } } }