` elements with unique `id` attributes where the fields should render:
```html theme={null}
```
Then mount each element into its placeholder:
```js theme={null}
cardNumber.mount("#cardNumber");
```
Use `unmount()` to remove an element from the DOM:
```js theme={null}
cardNumber.unmount();
```
## 4. React to element events (optional)
Every element exposes the typed `on(eventName, handler)` method shared by all SDK elements; secure fields emit `'change'`, `'focus'`, `'blur'`, and `'ready'` . `on()` returns an unsubscribe function:
```js theme={null}
cardNumber.on("ready", () => {
// the secure iframe has loaded and the field is interactive
});
cardNumber.on("change", (state) => {
// state: { isValid, isEmpty, ... }
// for CARD_NUMBER, state also carries the detected card network
// and the BIN (first digits of the card number)
console.log(state.isValid, state.network, state.bin);
});
```
## 5. Validate and collect the data
When the form is ready to be submitted, you can first validate all fields:
```js theme={null}
const { isValid, error, fieldErrors } = await container.validate();
```
Then call `collect()` on the container. All created elements must be mounted. The card data is encrypted inside the secure iframes and returned as an opaque payload - the raw values are never exposed to your code:
```js theme={null}
const result = await container.collect();
// result: { encryptedData: string, vaultProviderConfigId: string }
```
`collect()` rejects with a validation error when a field is incomplete or invalid.
## 6. Save the card as a payment instrument (optional)
To store the collected card for later payments, call `tokenize()` instead of `collect()`. It collects and encrypts the data, then saves it to Payrails as a payment instrument for the customer (holder) the SDK session was initialized for:
```js theme={null}
const instrument = await container.tokenize({
storeInstrument: true, // defaults to false
futureUsage: "CardOnFile", // 'CardOnFile' (default) | 'Subscription' | 'UnscheduledCardOnFile'
});
console.log("Saved instrument id:", instrument.id);
```
The response contains the new instrument's `id`, `status`, and card metadata such as `data.bin`, `data.network`, and `data.suffix`.
## End-to-end example
```js theme={null}
import { ElementType } from "@payrails/web-sdk";
// Step 1
const container = payrails.collectContainer({});
// Step 2
const cardNumber = container.createCollectElement({
type: ElementType.CARD_NUMBER,
label: "Card number",
placeholder: "1234 1234 1234 1234",
required: true,
appearance: {
rules: {
".payrails-input": { color: "#1d1d1d" },
".payrails-label": { fontSize: "12px", fontWeight: "bold" },
".payrails-error": { color: "#f44336" },
},
},
});
const expiryDate = container.createCollectElement({
type: ElementType.EXPIRATION_DATE,
format: "MM/YY",
});
const cvv = container.createCollectElement({
type: ElementType.CVV,
});
// Step 3 — assumes divs with these ids exist on the page
cardNumber.mount("#cardNumber");
expiryDate.mount("#expiryDate");
cvv.mount("#cvv");
// Step 5
const { encryptedData, vaultProviderConfigId } = await container.collect();
// or Step 6 — save the card instead
const instrument = await container.tokenize({ storeInstrument: true });
```
## Default validations
Every element type has a set of built-in validations:
* `CARD_NUMBER`: card number validation with checksum (Luhn algorithm) and card-scheme-aware length and formatting. A valid 16 digit card number is formatted as `XXXX XXXX XXXX XXXX`.
* `CARDHOLDER_NAME`: name should be 2 or more symbols; valid characters match the pattern `^([a-zA-Z\\ \\,\\.\\-\\']{2,})$`.
* `CVV`: 3–4 digits.
* `EXPIRATION_DATE`: any date starting from the current month, in the configured `format` (default `MM/YY`).
* `EXPIRATION_MONTH`: a valid month (`01`–`12`).
* `EXPIRATION_YEAR`: the current year or later, in the configured `format`(default `YY`).
## UI errors for collect elements
You can display custom error messages on the elements with `setError` and `resetError`.
`setError(error: string)` overrides any current error on the element with the custom message. The message stays visible until `resetError()` is called on the same element.
`resetError()` clears the custom error message set by `setError`.
```js theme={null}
const container = payrails.collectContainer({});
const cardNumber = container.createCollectElement({
type: ElementType.CARD_NUMBER,
});
// set a custom error
cardNumber.setError("custom error");
// reset the custom error
cardNumber.resetError();
```
## Related topics
- [Secure Fields](/docs/orchestration/checkout-sdks/web-v5-legacy/secure-fields.md)
- [How to customize the checkout's appearance](/docs/orchestration/checkout-sdks/web/guides/how-to-customize-the-checkouts-appearance.md)
- [Payrails API Reference](/docs/orchestration/checkout-sdks/web/references/payrails-api-reference.md)