Skip to main content
a KERNEL wallet (provider: "kernel") collects each card through the card_enrollment action that add_payment_method returns. by default, action.url opens a KERNEL-hosted page on vault.kernel.sh. to keep card entry inside your own application, render @onkernel/vault-react’s KernelCardCapture component on your page and style it to match your brand. card number, expiry, and cvc are entered in secure hosted fields and sent directly to KERNEL’s card vaulting provider from the cardholder’s browser. your page, your servers, and KERNEL never receive the card number. KERNEL receives only a card reference and the cardholder’s email, then enrolls the card for network tokens. use the embedded component when:
  • you want card entry on your own domain, with your own layout, copy, and fonts
  • you don’t want to send cardholders to a KERNEL-hosted page during onboarding
use action.url instead when a hosted page is acceptable. it needs no frontend work.
card enrollment and per-purchase CVC collection are embeddable. alias-mode purchases on any card network require fresh CVC collection, either embedded or through the hosted fallback. Visa network-token authentication still uses the KERNEL-hosted spend_approval page with its own iframe and passkey window. Network-token Mastercard purchases don’t need that hosted approval step.

Install

the package requires react 18 or later and ships no styles. use 0.5.0 or later: earlier versions can’t render cards stored in Evervault and report those capture links as unavailable.

Get a capture token on your backend

read capture_token from a card_enrollment action in your authenticated backend. the token is a secret capability for one card enrollment, not an api key. a new KERNEL wallet is connected with no card and no action. invoke add_payment_method for each card, then read payment_method.action.capture_token from the result.
capture_token is present only on KERNEL wallets. don’t parse it out of action.url; the url format isn’t part of the api. the new payment method starts in pending_enrollment. after the cardholder adds a card, it becomes active. a wallet created before cards were payment methods might still have a default card, card, waiting for enrollment. its card_enrollment action, with its capture_token, is on that method in the wallet’s payment_methods expansion, not on the wallet.

Render the component

deliver the token to the intended cardholder’s page through your authenticated application, then render KernelCardCapture:
AddCard.tsx
the component calls the api directly from the cardholder’s browser, with the token as a bearer and no cookies. call it directly rather than through your own proxy: the api rate-limits this route per client address, so every cardholder behind a proxy shares the proxy’s limit.

Style the component

the package ships no css. you style two layers separately.

Surrounding form

the component renders stable class hooks. target them under your className:
acme-card.css
the iframes fill their card-field container, so give that container an explicit height.

Card fields

css on your page can’t reach inside the hosted fields. pass fieldCss instead; it’s applied to the inputs in all three iframes:
fieldCss supports nested pseudo-classes, @font-face, media queries, and the state classes &.invalid, &.valid, &.empty, &.dirty, and &.touched. the component reads it once, when it mounts; remount the component to change it.

Evervault card fields

when your organization stores KERNEL cards in Evervault, the component renders Evervault’s card component (card number and expiry) instead of the fields above. fieldCss doesn’t apply there: Evervault renders each field’s label, input, and error inside its own iframe. pass evervaultTheme instead. its styles are css-in-js rules keyed by selector, which Evervault injects into its iframe:
without a theme, Evervault’s inputs render unbordered. the number, expiry, and expirationPlaceholder labels set the Evervault field labels and expiry placeholder. the component reads the theme and labels once, when it mounts. you can pass both fieldCss and evervaultTheme; the component uses whichever matches the card vault.

Text

override any of these keys through labels: title, description, completeTitle, completeDescription, number, expiry, expirationPlaceholder, cvc, email, emailHint, submit, submitting, retry, checkAgain, and missingToken. set at least title, description, completeTitle, and completeDescription. the defaults are KERNEL’s lowercase copy, and the default completion text mentions KERNEL. error messages are fixed and can’t be overridden; use onError if you want to show your own.

Allow the component in your CSP

the component loads its hosted-fields script from https://js.verygoodvault.com, renders secure iframes, and calls the KERNEL api. merge these directives into your existing content security policy:
if your organization stores cards in Evervault, also allow Evervault’s origins. Evervault requires its sdk to load from its cdn, so it can’t be pinned with an integrity hash:
if the Evervault sdk or component doesn’t load within 30 seconds, for example because your CSP blocks its frame, the component reports network and shows a retry button. if fieldCss uses @font-face, also allow the font’s source. you don’t need to allow the hosted-fields analytics endpoint; blocking it doesn’t affect card capture.

Handle completion

onComplete means KERNEL confirmed the card was added. it isn’t a payment notification. confirm the payment method’s state from your backend before you treat it as ready:
a wallet is connected even before its first card, so its status doesn’t tell you whether the card was added. find the payment method you added in the wallet’s payment_methods expansion and check that it’s active and that capabilities.single_use_card.eligible is true before creating a purchase.

Handle errors

onError receives one of these codes. the component never surfaces raw api or provider messages. after expired, unavailable, or unconfirmed, the component removes the form.

Token lifetime

a capture_token lasts 30 minutes. when it expires, invoke add_payment_method again for a new payment method and token. changing the component’s token prop resets it. if the cardholder leaves the page after creating a card but before KERNEL confirms it, the component makes one best-effort attempt to resend the card as it unmounts or the page unloads. it ignores that request’s result, so the card can still go unrecorded. always confirm the payment method’s state from your backend, as described in handle completion.

Security

  • treat capture_token as a secret. deliver it only to the intended cardholder, and never put it in a path, query string, cookie, browser storage, logs, traces, or analytics. if you put it in a link, use a url fragment and clear it once capture completes.
  • don’t add native card inputs, card-data callbacks, analytics, or session replay around the component.
  • serve the page over HTTPS.