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
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
unavailable.
Get a capture token on your backend
readcapture_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 renderKernelCardCapture:
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 yourclassName:
acme-card.css
card-field container, so give that container an explicit height.
Card fields
css on your page can’t reach inside the hosted fields. passfieldCss 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:
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 throughlabels: 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 fromhttps://js.verygoodvault.com, renders secure iframes, and calls the KERNEL api. merge these directives into your existing content security policy:
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:
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
acapture_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_tokenas 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.