CVC Element

The CVC Element renders a single secure CVC/CVV input inside an iframe and applies the value to a card you already tokenized. The buyer re-enters three or four digits; the card number and expiry stay where they are and are never re-collected. You keep the same cardToken throughout - the element patches the stored card in place rather than creating a new one.

Why this is needed

A card verification code can’t be stored, so the CVC captured when you tokenized a card expires while the rest of the card stays valid. Charging a stored card after that point requires a fresh CVC from the buyer. This element is how you collect it.

The CVC is captured and applied inside the iframe, so it never reaches your servers - this keeps you out of PCI DSS scope. A server-side POST /card/{cardToken}/cvv REST endpoint also exists (it is not exposed through the SDK) for backends that can’t run an iframe, but passing the raw CVV through your own backend brings your systems into PCI scope. Prefer this element unless you already run a PCI-compliant environment.

Usage

import Henry from '@henrylabs/js';

const cvcEl = Henry.createCvcElement('#cvc-container', {
	cardToken: 'card_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
});

Add a container in your HTML:

<div id="cvc-container"></div>

The cardToken is the token you received from a previous cardEl.submit() call - see the Card Element. To apply the new code, call validate() then submit():

const isValid = await cvcEl.validate();

if (isValid) {
	await cvcEl.submit();
	// the existing cardToken is now chargeable again
}

Options

`cardToken` `string`

Required. The card token identifying the stored card to update.

`styles` `CvcStyles`

Optional. Customize the appearance of the CVC input.

const cvcEl = Henry.createCvcElement('#cvc-container', {
	cardToken: 'card_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
	styles: {
		cardVerification: {
			base: {
				color: '#111',
				fontSize: '16px',
				fontFamily: 'Inter, sans-serif',
			},
			'::placeholder': {
				color: '#aaa',
			},
			invalid: {
				color: '#e53e3e',
			},
		},
	},
});

`CvcStyles` reference

Field	Type	Description
`cardVerification`	`CardElementStyle`	Styles for the CVV/CVC field
`container`	`CSSProperties`	Styles applied to the outer container element
`inputWrappers`	`CSSProperties`	Styles applied to the field wrapper
`fonts`	`string[]`	Font URLs to load inside the iframe

cardVerification accepts the same CardElementStyle shape documented under the Card Element - base, complete, invalid, empty, container, placeholder, label, labelContainer, fonts, and the pseudo-class overrides.

Methods

`validate()` → `Promise<boolean>`

Returns true when the field contains a valid code. Use this to gate your submit button.

const isValid = await cvcEl.validate();
if (!isValid) {
	// show your own error message
}

`submit()` → `Promise<void>`

Applies the entered code to the stored card. Resolves on success and rejects with the failure reason otherwise. The cardToken is unchanged - after this resolves you can charge it again.

await cvcEl.submit();

`destroy()`

Removes the iframe and cleans up all event listeners. Call this when navigating away or unmounting a component.

cvcEl.destroy();

Full example

<form id="confirm-form">
	<div id="cvc-container"></div>
	<button type="submit">Confirm & pay</button>
</form>

<script type="module">
	import Henry from '@henrylabs/js';

	const cvcEl = Henry.createCvcElement('#cvc-container', {
		cardToken: 'card_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
		styles: {
			cardVerification: {
				base: { color: '#111', fontSize: '16px' },
				'::placeholder': { color: '#aaa' },
				invalid: { color: '#e53e3e' },
			},
			fonts: ['https://fonts.googleapis.com/css2?family=Inter&display=swap'],
		},
	});

	document.getElementById('confirm-form').addEventListener('submit', async (e) => {
		e.preventDefault();

		const isValid = await cvcEl.validate();
		if (!isValid) return;

		await cvcEl.submit();

		await fetch('/api/pay', {
			method: 'POST',
			body: JSON.stringify({ cardToken: 'card_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' }),
			headers: { 'Content-Type': 'application/json' },
		});
	});
</script>

React

import { useEffect, useRef } from 'react';
import Henry from '@henrylabs/js';

function CvcConfirm({ cardToken }: { cardToken: string }) {
	const cvcElRef = useRef<ReturnType<typeof Henry.createCvcElement> | null>(null);
	const initialized = useRef(false);

	useEffect(() => {
		if (initialized.current) return;
		initialized.current = true;

		cvcElRef.current = Henry.createCvcElement('#cvc-container', {
			cardToken,
			styles: {
				cardVerification: {
					base: { color: '#111', fontSize: '16px' },
				},
			},
		});

		return () => cvcElRef.current?.destroy();
	}, [cardToken]);

	async function handleSubmit(e: React.FormEvent) {
		e.preventDefault();
		if (!cvcElRef.current) return;

		const isValid = await cvcElRef.current.validate();
		if (!isValid) return;

		await cvcElRef.current.submit();
		// charge the same cardToken from your server
	}

	return (
		<form onSubmit={handleSubmit}>
			<div id='cvc-container' />
			<button type='submit'>Confirm & pay</button>
		</form>
	);
}

Card Element

Collect and tokenize a full card

Server SDK - Checkout

Build headless checkout flows server-side

Getting Started

Widgets

Elements

Info

Why this is needed

Usage

Options

`cardToken` `string`

`styles` `CvcStyles`

`CvcStyles` reference

Methods

`validate()` → `Promise<boolean>`

`submit()` → `Promise<void>`

`destroy()`

Full example

React

Card Element

Server SDK - Checkout

​Why this is needed

​Usage

​Options

​cardToken string

​styles CvcStyles

​CvcStyles reference

​Methods

​validate() → Promise<boolean>

​submit() → Promise<void>

​destroy()

​Full example

​React

​Related

Card Element

Server SDK - Checkout

Why this is needed

Usage

Options

`cardToken` `string`

`styles` `CvcStyles`

`CvcStyles` reference

Methods

`validate()` → `Promise<boolean>`

`submit()` → `Promise<void>`

`destroy()`

Full example

React

Related