Events reference

All events are CustomEvents that bubble and compose across the shadow boundary. Payloads live on event.detail.

Event	detail	When
session.ready	{ session }	Session config fetched
session.expired	{ sessionId }	Server 410 or local expiry timer
feequote	{ amount, convenienceFee, totalAmount, method, last4?, cardType? }	Entered details tokenized and fee quoted from the actual instrument
method.changed	{ method }	Customer picked a method or saved card
validation	{ valid, errors: { field: message } }	Any input changed
payment.processing	{ sessionId }	Submit pressed, before the API call
payment.success	{ sessionId, transactionId, paymentUid, method, last4, cardType, totalAmount, savedMethodId? }	Confirm returned success. method is card, ach, or apple_pay. paymentUid is the canonical PaymentApi payment id (P-…) — the stable, account-scoped reference to record and verify against; transactionId is the incidental processor id.
payment.error	{ code, message, recoverable }	Decline or failure
challenge	{ type, … }	Verification step required (captcha / SMS / email code)
walletDeleted	{ savedMethodId }	Saved method removed in management mode

Error codes

payment.error.detail.code is one of:

card_declined · expired_card · incorrect_cvc · insufficient_funds
processing_error · network_error · session_expired · validation_error

recoverable: true means the customer can fix the problem and retry in place (wrong CVV, declined card). recoverable: false means mint a new session.

A confirm-time duplicate-payment guard (HTTP 409) is handled in-component: instead of firing payment.error, the component shows a “submit anyway” prompt. If the customer confirms, it re-submits the same payment with the duplicate acknowledged; no host wiring is needed.

postMessage equivalence

When embedding the checkout iframe directly (no component), the same payloads arrive as window messages:

{
  type: 'govifi:event',
  event: 'feequote',
  detail: { amount: 14227, convenienceFee: 423, totalAmount: 14650, method: 'card' },
  sessionId: 'cs_3oNkLp9aBcDeFgHi',
  timestamp: 1714521600
}

Always verify event.origin before trusting a message.