<secure-card>
Payment card input with Luhn validation, card type detection, animated 3D preview, full PAN masking on blur, and CVC protection. Security tier locked to CRITICAL.
Overview
The <secure-card> component provides a PCI-aware payment card input. It enforces Luhn validation, detects card network from the PAN prefix, adjusts CVC length rules per network, and masks the card number to the last 4 digits on blur. The full PAN and CVC are never exposed outside the Shadow DOM.
Basic usage HTML
<secure-form action="/checkout" method="POST"
security-tier="critical">
<secure-card
name="payment"
label="Payment Details"
show-name
required>
</secure-card>
<button type="submit">Pay Now</button>
</secure-form>Live Demo
Security Model
Security tier is immutably fixed to CRITICAL regardless of any security-tier attribute. The following guarantees are always enforced:
- Full PAN never in custom events, hidden inputs, or audit logs — only
last4 - CVC never in custom events, hidden inputs, or audit logs
- CVC field uses
type="password"— browser hides the value - Card number masked to
•••• •••• •••• 1234on blur - All sensitive state cleared in
disconnectedCallback() - Autocomplete disabled on all fields
- Rate limited to 5 attempts per minute
secure-card event detail JS
card.addEventListener('secure-card-change', (e) => {
const {
name, // field name attribute
cardType, // 'visa' | 'mastercard' | 'amex' | ...
last4, // last 4 digits (safe to log)
expiryMonth, // number 1–12
expiryYear, // number, 4-digit (e.g. 2027)
valid, // all fields pass validation
tier, // always 'critical'
} = e.detail;
// full PAN, CVC, and cardholderName intentionally absent
// use getCardData() to retrieve raw values for SDK tokenisation
});Card Types
Card type is detected from the PAN prefix as the user types. CVC length and PAN length rules adjust automatically.
| Type | Prefixes | PAN length | CVC digits |
|---|---|---|---|
visa | 4 | 13, 16, 19 | 3 |
mastercard | 51–55, 2221–2720 | 16 | 3 |
amex | 34, 37 | 15 | 4 |
discover | 6011, 65xx | 16 | 3 |
diners | 300–305, 36, 38 | 14 | 3 |
jcb | 2131, 1800, 35xxx | 16 | 3 |
unknown | — | 16 | 3 |
API Reference
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
name | string | - | Base name for hidden form inputs (name, name-expiry, name-holder) |
label | string | - | Legend text displayed above the fields |
show-name | boolean | false | Show the optional cardholder name field |
required | boolean | false | All fields must be filled and valid |
disabled | boolean | false | Disable all input fields |
Properties
valid boolean True when all visible fields pass validation
cardType 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unknown' Detected card network
last4 string Last 4 digits of the card number (safe to display)
Methods
getCardData(): { number, expiry, cvc, name } | null
Returns raw PAN, expiry, CVC, and cardholder name for immediate handoff to a payment SDK tokenizer. Returns null if validation has not passed. Never transmit raw card data to your own server. This method is a public JS API — any script on the page with a reference to this element can call it. You must enforce a strict Content Security Policy on any page rendering this component to prevent third-party scripts from exfiltrating card data. Call once, pass to the SDK immediately, do not store the return value.
reset(): void
Clears all fields and resets validation state
getAuditLog(): AuditLogEntry[]
Returns interaction audit log. PAN and CVC are never included.
getFieldTelemetry(): FieldTelemetry
Returns aggregate behavioral signals (dwell, velocity, corrections, paste detection) across all four card inputs
Events
| Event | Detail | Description |
|---|---|---|
secure-card-change | | Fired on any field change. Full PAN and CVC intentionally absent. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--secure-card-width | 340px | 3D card preview width |
--secure-card-radius | 16px | Card border radius |
--secure-card-font | 'Courier New', monospace | Card number font |
--secure-card-gradient | linear-gradient(135deg, #1e2a4a, #2d4a8a) | Default card face gradient |
--secure-card-transition | transform 0.6s … | 3D flip animation |