Authvia Payment Method Form

Vue 3 + Vuetify 3 component and standalone web component for adding a saved payment method (card, ACH, PayPal, Venmo, Paze, and related options). You choose which methods to expose; only enabled methods appear. On success the host receives a payment method id.

Full prop and behavior notes live in Storybook (AuthviaPaymentMethodForm story docs) and in exported TypeScript types.

Requirements

• Vue >= 3.4.0
• Vuetify 3.x (your app creates the Vuetify instance; this package does not)
• MDI font CSS on the host page (Material Design Icons)

If Vue, Vuetify, or styles are missing in a web-component embed, the element may emit authvia:dependency-missing.

Installation

npm install @authvia/payment-method-create

Exports:

• Vue plugin / module: @authvia/payment-method-create (default build)
• Standalone web component: @authvia/payment-method-create/web-component

Features (summary)

• Token: A valid JWT is required for the inner form to render. The token must include https://authvia.com/uuid and payment_methods:create in scope. Missing, empty, invalid, or expired tokens keep the form hidden; the wrapper emits error as { phase: 'init', error } and logs a warning, and does not emit ready. ready is emitted only after the token passes validation.
• Enabled methods: Props such as card, ach, paypal, venmo, and paze control what appears. Methods you do not configure stay off the list.
• Runtime errors: Failures while saving emit error with a payload that usually includes a message string (shape is not { phase: 'init', … }). Incomplete Paze or PayPal/Venmo (for non-payouts intent) config hides those methods in the list instead of erroring on open. The embed usually stays mounted so the user can retry.
• Sentry: Supports standalone widget ownership (VITE_WIDGET_SENTRY_DSN) and host-owned ownership (VITE_SENTRY_EMBED_MODE=lock or window.__AUTHVIA_EMBED__.sentry='host') without double-init.
• Success: success carries payment method details (see Events). The host decides navigation or hiding the embed.
• Styling: Accent color, border radius, and field variant are configurable; CSS variables use the --avwc-* prefix on the form root.

Vue: register the plugin

Your application must call createVuetify() (and load Vuetify styles + MDI) before registering this plugin.

import { createApp } from 'vue';
import { createVuetify } from 'vuetify';
import AuthviaPaymentMethodFormPlugin from '@authvia/payment-method-create';
import App from './App.vue';

const app = createApp(App);
const vuetify = createVuetify();

app.use(vuetify);
app.use(AuthviaPaymentMethodFormPlugin);
app.mount('#app');

Named export AuthviaPaymentMethodFormPlugin is also available for explicit imports.

Vue: use the component

<template>
  <AuthviaPaymentMethodForm
    :token="token"
    merchant-id="demo-merchant"
    customer-ref="demo-customer"
    intent="payments"
    :card="{ demoMode: false }"
    :ach="{ demoMode: false, online: true }"
    @ready="onReady"
    @success="onSuccess"
    @error="onError"
  />
</template>

<script setup lang="ts">
import { AuthviaPaymentMethodForm } from '@authvia/payment-method-create';

function onReady(): void {
  /* JWT passed validation; inner form can render */
}

function onSuccess(detail: unknown): void {
  /* includes paymentMethodId — see types */
}

function onError(detail: unknown): void {
  /* init: { phase: 'init', error }; runtime: often { message } */
}
</script>

Web component

Load Vue 3, Vuetify CSS, and MDI before the bundle. Use the data- prefix for attributes; object props are JSON strings on the element.

See demo.html in this repo for a full page example.

<script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/vuetify.min.css" data-vuetify />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mdi/[email protected]/css/materialdesignicons.min.css" data-mdi />

<authvia-create-payment-method-form
  data-token="YOUR_JWT"
  data-merchant-id="demo-merchant"
  data-customer-ref="demo-customer"
  data-intent="payments"
  data-card='{"demoMode":false,"submitBtnText":"Add card"}'
  data-color="#4CAF50"
  data-border-radius="1rem"
></authvia-create-payment-method-form>

Load the built script after Vue (for example the output of npm run build:wc):

<script type="module" src="https://cdn.authvia.com/web-components/authvia-payment-method-create/authvia-payment-method-create.js"></script>

Web component events

Listen on the custom element for:

| Event | detail | |--------|----------| | ready | Emitted only when the JWT passes validation (non-empty, parseable, not expired, required scope). Not emitted for missing, invalid, expired, or under-scoped tokens; use error with { phase: 'init', error } instead. | | submit | Emitted from some inner flows (for example ACH / PayPal) with form-related payloads. | | success | Saved payment method; includes paymentMethodId in the normalized payload. | | error | Init failures: { phase: 'init', error }. Runtime: often { message: string } or similar. | | authvia:dependency-missing | Host is missing Vue, Vuetify, or required styles. |

<script>
  const component = document.querySelector('authvia-create-payment-method-form');
  component?.addEventListener('ready', () => { /* … */ });
  component?.addEventListener('success', (e) => { console.log(e.detail); });
  component?.addEventListener('error', (e) => { console.log(e.detail); });
</script>

Sentry behavior

The package uses a single-client ownership model:

• Standalone widget mode: set VITE_WIDGET_SENTRY_DSN; the widget calls Sentry.init once and tags events with component=payment-method-create and integration=standalone-web-component.
• Embedded host mode (Lock or another host): set VITE_SENTRY_EMBED_MODE=lock at build time, or set window.__AUTHVIA_EMBED__.sentry = 'host' before widget mount; the widget skips Sentry.init and attaches handlers to the active host client.
• No active Sentry client: capture helpers are safe no-ops.

Supported Sentry env vars:

| Variable | Purpose | Default | |----------|---------|---------| | VITE_WIDGET_SENTRY_DSN | DSN for standalone widget ownership | unset | | VITE_SENTRY_EMBED_MODE | Set to lock to force host-owned mode | unset | | VITE_SENTRY_RELEASE | Optional release version sent to Sentry | unset | | VITE_SENTRY_REPLAY_SESSION_SAMPLE_RATE | Session replay sample rate (0..1) | 0 | | VITE_SENTRY_REPLAY_ON_ERROR_SAMPLE_RATE | Replay-on-error sample rate (0..1) | 1 |

Props (overview)

Details and examples match Storybook (src/components/AuthviaPaymentMethodForm.stories.ts).

| Area | Props | |------|--------| | Auth / context | token, merchantId, customerRef, intent | | Methods | card, ach, paypal, venmo, paze | | List UI | paymentMethodDisplay (titles, subtitles, order; optional root gap) | | Legal / footer | terms (privacy + terms links) | | Behavior | forgetHidden, forgetDefault | | Styling | color (default #4CAF50, from DEFAULT_AVWC_PRIMARY_COLOR), borderRadius (default 1rem, from DEFAULT_AVWC_BORDER_RADIUS), variant (default outlined, from DEFAULT_AVWC_FIELD_VARIANT), vuetifyOverrides (web component: plain CSS string for Shadow DOM) |

paymentMethodDisplay

Controls the payment method picker list (labels and order). It does not turn methods on or off; use card, ach, paypal, etc. for that.

| Field | Description | |--------|-------------| | gap (root, optional) | Vertical space between option rows. Any CSS length (1rem, 12px, …). If omitted, this prop does not add spacing; layout matches the previous behavior (no list-level gap from this object). | | card, ach, paypal, venmo, paze | Optional title, subtitle, and order. Lower order values appear higher in the list. |

Vue

:payment-method-display="{
  gap: '1rem',
  card: { title: 'Credit / debit card', subtitle: '…', order: 1 },
  ach: { title: 'Bank account', subtitle: '…', order: 2 }
}"

Web component (data-payment-method-display): pass a single JSON object string. Use commas between properties. Invalid JSON is ignored (check the console).

data-payment-method-display='{"gap":"1rem","card":{"title":"Card","order":1},"ach":{"title":"Bank","order":2}}'

Paze (paze)

Requires amount, clientId, profileId, and name on the object you pass; all must be non-empty (after trim). If any are missing or blank, Paze is not shown in the picker. The inner flow runs in two steps: Initializing Paze (SDK load) then Processing Paze payment (checkout → complete → create). Failures emit error and return the user to the payment method list without an inline error banner on that step; details are logged for developers.

PayPal / Venmo

• intent="payouts": paypal and venmo can be booleans; PayPal and Venmo stay listed even when merchantId is incomplete (same as before for payouts).
• intent="payments" (and any intent other than payouts): PayPal and Venmo appear in the picker only when merchantId is non-empty on the resolved wallet settings and the build defines VITE_APP_PAYPAL_CLIENT_ID. Otherwise those rows are hidden (same rules as the former click-time error, without showing a dead option).
• Pass merchantId and optional redirectUrl on the paypal / venmo object when you want the payments flow to succeed.

Stable styling hook classes (overrides)

Use these hooks in data-vuetify-overrides (web component) or host CSS. Canonical strings live in src/constants/avwcStylingHooks.ts (avwcPaymentMethodFormHooks).

| Class | Where | |--------|--------| | avwc-payment-method-form__root | Main form wrapper (AuthviaPaymentMethodForm) | | avwc-payment-method-form__options-root | Options container (AuthviaPaymentMethodOptions v-container) | | avwc-payment-method-form__options-card | Payment method selection v-card | | avwc-payment-method-form__options-list | List area wrapping picker rows | | avwc-payment-method-form__method-dialog | Each payment-method v-dialog content v-card | | avwc-payment-method-form__method-row | Each picker row (AuthviaPaymentMethodCard) | | avwc-payment-method-form__credit-card-section | Credit card block inside the card/PayPal dialog | | avwc-payment-method-form__ach-root | ACH add-bank flow root (AuthviaPaymentMethodAddAch) |

Inside each picker row (data-vuetify-overrides): combine with the row hook, e.g. .avwc-payment-method-form__method-row .payment-method-card__title { color: #1565c0 !important; } for title text, .payment-method-card__logo-slot for icon tint, .payment-method-card__subtitle for the description line.

CSS variables

The form root sets theming variables, including:

• --avwc-color (accent; mirrors color prop, default #4CAF50 from DEFAULT_AVWC_PRIMARY_COLOR)
• --avwc-border-radius (mirrors borderRadius, default 1rem from DEFAULT_AVWC_BORDER_RADIUS)

Additional tokens (for example --avwc-text-color-light) are documented in variables.css and Storybook.

Development

Prerequisites: Node.js 18+, npm 9+.

npm install
npm run dev              # app dev server
npm run build            # Vue module
npm run build:wc         # web component
npm run type-check
npm run lint
npm test

Bundle and assets

• The Vue module expects Vue and Vuetify as peer dependencies; your app supplies Vuetify and MDI.
• The standalone web component bundles Vuetify JavaScript but expects Vuetify CSS + MDI from the host (same as demo.html).
• Component styles ship with the JS; add Vuetify + MDI at the app level.

Browser support

Chrome 88+, Firefox 85+, Safari 14+, Edge 88+.

Changelog

Version 1.0.3

Added Storybook stories and expanded unit tests; fixed duplicate tender-type filtering in useWalletMerchantService. See git history for details.

Version 1.0.2

Unified success payloads for ACH and card ({ type, paymentMethodId, use }), --avwc-* CSS variables with backward-compatible fallbacks, and named plugin export.

Documentation (current)

README aligned with AuthviaPaymentMethodForm.stories.ts (including paymentMethodDisplay.gap), demo.html, and package exports (@authvia/payment-method-create).

License

MIT License — see the LICENSE file.

Support

For support and questions, contact the Authvia UI Team.