Payment Form

Pro

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.

Total due$49.00

Try KOALA20 for 20% off, or WELCOME10 for $10 off.

Payments are secure and encrypted

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.

Total due$49.00

Try KOALA20 for 20% off, or WELCOME10 for $10 off.

Payments are secure and encrypted

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add payment-form

Usage#

This example is part of Koala UI Pro

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 details are secure and encrypted

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.

PropTypeDefaultDescription
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.
submitLabelReact.ReactNode"Pay {total}" | "Save card"The submit button's label. Defaults to Pay plus the total in checkout, Save card in update.
amountstring-The display total, e.g. "$49.00". Shows the summary row and labels the Pay button. Ignored in update mode.
promoCodesRecord<string, PaymentPromoCode>-Accepted codes, matched case-insensitively, each { percentOff?, amountOff?, label? }. Reveals the promo row; needs a parseable amount. Ignored in update mode.
promoHintReact.ReactNode-A caption under the promo field, e.g. "Try KOALA20".
defaultCountrystring"US"The billing country preselected, as ISO2.
titleReact.ReactNode"Payment details" | "Update card"The heading above the form, by mode. null hides it.
descriptionReact.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.

PropTypeDefaultDescription
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.

PropTypeDefaultDescription
brand"visa" | "mastercard" | "amex" | "discover"-Which network to draw. Also sets the accessible name.

FAQ#

No. The masking and live brand detection are presentation only, and PaymentForm never touches a network. Wire your onSubmit handler to a provider like Stripe, and never store the unmasked card number yourself.