Payments

Payments lets your app charge a signed-in user once, for a ticket, an order or a fee. Your code creates a payment with its line items and sends the user to Stripe Checkout. A hook tells your code when the money has arrived. Payments does not know what is sold, so Events and your own routes can share it. For recurring charges, use Subscriptions.

The package is @frigear-nu/payments. Only a verified Stripe event marks a payment as paid, never the redirect back to your app. Prices are inline, so you create no products or prices in Stripe.

What you get

• Server routes (on by default): the signed-in user's payments, and resuming an unpaid one. A staff route for revenue, guarded by the payments:manage permission (the admin role holds it).
• Composables and helpers (on by default): createPayment, refundPayment and readers on the server, and usePayments() in the app.
• Admin area (with Admin and Widget): a Payments tab and a Last payment card on the admin user page, and revenue and recent transactions on the dashboard.

Quick setup

pnpm add @frigear-nu/payments @nuxthub/core

export default defineNuxtConfig({
  modules: ['@nuxthub/core', '@frigear-nu/payments'], // installs Users and Stripe for you
  payments: {
    settings: { checkoutExpiresInMinutes: 30 },
  },
})

pnpm db:generate

export default defineNuxtConfig({
  authorization: {
    roles: {
      bookkeeper: { label: 'Bookkeeper', grant: ['payments:manage'] },
    },
  },
})

export default defineEventHandler(async (event) => {
  const user = await requireUser(event, { sessionOnly: true })
  const { url } = await createPayment({
    userId: user.id,
    items: [{ name: 'Workshop seat', amount: 25000, currency: 'dkk' }], // 250.00 DKK
    reference: { type: 'workshop_seat', id: 'spring' },
    successUrl: '/shop/thanks',
    cancelUrl: '/shop',
  }, event)
  return { url }
})

export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook('payments:paid', async ({ payment }) => {
    if (payment.referenceType !== 'workshop_seat') return
    // confirm the seat for payment.userId
  })
})

Options

Options go under the payments key.

settings.checkoutExpiresInMinutes is clamped to Stripe's range of 30 to 1440.

Server

These helpers are 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
}

createPayment validates successUrl and cancelUrl as a relative path or the same origin when you pass event. Without event they must be absolute http(s) URLs. An invalid URL throws 400.

resumePayment throws 404 for an unknown payment, and 409 when it is already paid or refunded. For an expired session it builds a new one from the stored items and the old success and cancel URLs. It runs payments:checkout:before and the URL check again. The configured checkoutExpiresInMinutes applies, because expiresInMinutes is not stored.

refundPayment throws 409 unless the payment is paid or partially_refunded. An amount that is not positive, or more than is left, throws 400. The status changes when the charge.refunded event arrives.

Subscription invoices

With Subscriptions installed, every subscription invoice is stored as a payment too. These are the invoice.paid, invoice.payment_failed, invoice.voided and invoice.marked_uncollectible events.

• The payment has referenceType: 'subscription', and referenceId is the Stripe subscription id.
• It fires the payments:* hooks and shows in the admin tab, the card and my-payments.
• Invoices of zero, such as trials and full discounts, are skipped.
• Only invoices received after upgrading are stored.

recordInvoicePayment(input: InvoicePaymentInput) is the auto-imported helper behind this. It is idempotent per invoice id. Without Payments, Subscriptions records no invoices.

MCP tool

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

App

usePayments() loads the signed-in user's payments. It is auto-imported, and pages can await it.

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. The tab is read-only: it has no refund action yet. The admin dashboard gets a 30-day revenue stat and the recent transactions.

Hooks

Your app answers these Nitro hooks from a server plugin (server/plugins/*.ts).

type PaymentHookContext = { payment: PaymentDto }

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

A status change happens once. A redelivered Stripe event fires no hook twice, and a late expired event never downgrades a paid payment.

Routes

Routes the module registers, and who may call them.

• The resume route answers 404 not_found for someone else's payment and 409 conflict when it is already paid.
• The /me routes also accept an API token or an access token whose scope covers the permission, such as the payments scope.
• Path builders are paymentsApi from @frigear-nu/payments/api.

Permissions

The module registers these permissions with Authorization. A route calls authorize(event, 'payments:read'), which passes only when the caller's roles, the authorization:before hook and any policy allow it.

• Implicit permissions work even when Authorization is not installed, so self-service keeps working.
• Scope: payments (label "Your payments") expands to payments:read and payments:write. A token or OAuth client with this scope can read and resume the user's own payments, and nothing else.
• Roles and policies: the module ships no role, requirement or policy. Staff access comes from the admin role, or from any role of yours that grants payments:manage.
• Reading another user's payments (GET /api/admin/users/:id/payments) needs users:read from Users, not a payments permission. The caller must also hold every permission the target user holds, so a coordinator cannot read an admin's payments.

For the full model, see Authorization, including roles and requirements and policies.

Database

Tables the module adds. Generate and commit a migration after installing.

The module adds one payments table.

Translations

Override any string in your app's i18n/locales/<code>.json.

The module registers da and en files with Module Kit under payments.*. The keys are payments.status.<status>, payments.defaultDescription and payments.admin.*. API error messages stay in English.

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

Next steps

• Stripe setup – connect Stripe so payments are marked as paid.
• Sell event tickets – see Events take payments through this module.