Payment Form
A complete card-checkout block. The number, expiry and CVC are masked as you type, the card brand is detected live, and the billing country shows circular flags. Accept promo codes to roll the total.
Payment details
Enter your card to complete the purchase. Your details are encrypted end to end.
Try it yourself. This one is live, and its code is right below.
Payment details
Enter your card to complete the purchase. Your details are encrypted end to end.
Installation#
Usage#
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Update a card on file#
Billing screens replace a card rather than charge one. mode="update" drops the total and the promo row, swaps the copy to Update card, labels the button Save card and ends on a Card saved screen. Pass submitLabel to word the button your way in either mode.
Update card
The new card is charged from the next invoice. Your details are encrypted end to end.
Card helpers#
When the card fields live inside your own layout, a dialog with its own header, footer and validation, reuse the form’s masking instead of rewriting it. formatCardNumber groups the digits in fours, formatCardExpiry adds the slash, and detectCardBrand names the network for a CardBrandMark.
API reference#
PaymentForm
A card checkout built from Field, Input and CountrySelect. Masking and brand detection are presentation only: never store an unmasked card number. Forwards native <div> props; accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| onSubmit | (data: PaymentFormData) => void | Promise<void> | - | Called with { cardNumber, expiry, cvc, name, country, promoCode? }, masked as shown. Return a promise to hold the spinner until it settles. |
| mode | "checkout" | "update" | "checkout" | update replaces a card on file: no total, no promo row, "Update card" copy, a Save card button and a Card saved screen. |
| submitLabel | React.ReactNode | "Pay {total}" | "Save card" | The submit button's label. Defaults to Pay plus the total in checkout, Save card in update. |
| amount | string | - | The display total, e.g. "$49.00". Shows the summary row and labels the Pay button. Ignored in update mode. |
| promoCodes | Record<string, PaymentPromoCode> | - | Accepted codes, matched case-insensitively, each { percentOff?, amountOff?, label? }. Reveals the promo row; needs a parseable amount. Ignored in update mode. |
| promoHint | React.ReactNode | - | A caption under the promo field, e.g. "Try KOALA20". |
| defaultCountry | string | "US" | The billing country preselected, as ISO2. |
| title | React.ReactNode | "Payment details" | "Update card" | The heading above the form, by mode. null hides it. |
| description | React.ReactNode | "Enter your card to complete…" | The line under the heading, by mode. null hides it. |
| density | "comfortable" | "compact" | - | Spacing, 24 or 16px. Inherits the nearest DensityProvider (compact with none). |
Card helpers
The masking and brand detection the form runs, exported for screens that lay out their own card fields, such as an update-card dialog with its own header and footer. Plain functions, safe on the server.
| Prop | Type | Default | Description |
|---|---|---|---|
| detectCardBrand | (value: string) => CardBrand | null | - | The network from the leading digits; spaces and dashes are ignored. |
| formatCardNumber | (value: string) => string | - | Digits only, at most 19, grouped in fours: 4242 4242 4242 4242. |
| formatCardExpiry | (value: string) => string | - | Digits only, at most 4, with the slash after the month: 08/28. |
CardBrandMark
The card network logo the number field shows once it detects a brand, in the network's own colours on a white card (Amex keeps its blue box), so it reads on every theme. Use it on its own for saved cards or accepted-cards rows. Size it from the outside; forwards native <svg> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| brand | "visa" | "mastercard" | "amex" | "discover" | - | Which network to draw. Also sets the accessible name. |