Input Payment

A cross-platform React payment card input that automatically detects the card type from the entered number and displays relevant payment icons.

A specialised text input for payment data entry. Extends the standard input with a dedicated payment icons block — a row of accepted payment method logos (Visa, Mastercard, etc.) displayed inside the field — and an optional leading icon. Used exclusively in checkout flows, billing forms, and payment method configuration screens.

When to use

For collecting a card number, expiry date, CVV, or other payment-related values in a checkout or billing form

When the field must visually communicate which payment methods are accepted — showing logos inside the input reassures the user before they start typing

When the payment method icon should change dynamically based on detected card type (e.g. showing the Visa logo as soon as the user types a Visa prefix)

As a pair: one InputPayment for the card number, one for the expiry, one for the CVV — in a standard payment card form layout

When not to use

• For non-payment text inputs — use the standard Input component
• When no payment branding is needed — use standard Input with an optional left icon
• When accepting only one specific payment method with no ambiguity — the payment icons block may be omitted and a single logo shown via Icon left instead

Content guidelines

Placeholder text — use format hints, not instructions: 1234 5678 9012 3456 for card number, MM / YY for expiry, CVV or CVC for security code. Do not use "Enter your card number" — the field label already communicates this. Error messages — be specific:

• "Invalid card number" — after Luhn check fails
• "Expiry date has passed" — past month/year entered
• "CVV must be 3 digits" (or 4 for Amex) — wrong length
• "Card number is required" — required field left empty
• Field labels — always provide a visible label above the field: "Card number", "Expiry date", "Security code". Do not rely on the placeholder alone.
• Payment icons — show only the logos for payment methods actually accepted by the product's payment provider. Do not show logos for unsupported methods — it creates false expectations.

Behaviour guidelines

Card number formatting — as the user types, format the card number with spaces every 4 digits: 4242 4242 4242 4242. Apply this formatting in real time without disrupting cursor position. Accept both numeric-only input and formatted strings with spaces.

Card type detection — detect the card network from the first 1–6 digits (IIN/BIN range). When detected, highlight the matching logo in the payment icons block and dim or hide others. Update in real time as the user types.

Expiry date formatting — auto-insert a / separator after the month digits: 12/26. Prevent the user from entering an invalid month (> 12) or a past expiry date.

CVV masking — optionally mask CVV input as the user types (show dots •••). Provide a show/hide toggle via a trailing icon button if masking is enabled.

Input masking — use inputmode="numeric" and pattern="[0-9]"* on numeric fields to trigger a numeric keyboard on mobile. Do not use type="number" for card fields — it interferes with leading zeros and formatting.

Validation timing — validate on blur (when the user leaves the field), not on every keystroke. Switch to State=Error with a specific error message when the value fails validation. Clear the error when the user starts typing again.

Disabled state — use State=Disabled for saved payment methods being displayed in a non-editable summary. Always show the masked card value (e.g. •••• 4242) rather than an empty disabled field.

Autofill — support browser and OS autofill for payment fields. Use standard autocomplete attributes: autocomplete="cc-number" for card number, autocomplete="cc-exp" for expiry, autocomplete="cc-csc" for CVV. Autofill should trigger Filled=True and the detected card type should update the payment icons block.

Accessibility

Each InputPayment field must have a visible label associated via or aria-labelledby. Do not use placeholder as the only label.

Use autocomplete attributes on all payment fields — they are required for WCAG 1.3.5 (Identify Input Purpose).

Use inputmode="numeric" on card number, expiry, and CVV fields to trigger the numeric keyboard on touch devices.

When State=Error, the error message must be associated via aria-describedby so screen readers announce it when the field is focused.

The payment icons block is decorative — wrap it in aria-hidden="true" so screen readers do not attempt to read logo names. The accepted payment methods should instead be listed in a visible or screen-reader-only text near the form (e.g. "We accept Visa, Mastercard, and American Express").

The Icon left is decorative when a label is present — set aria-hidden="true" on the icon element.

When State=Disabled, set aria-disabled="true" and communicate the card type and masked number via aria-label — e.g. aria-label="Visa card ending in 4242, disabled".

Installation

npm install @xsolla/xui-input-payment

Demo

Basic Payment Input

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";

export default function BasicPayment() {
  const [cardNumber, setCardNumber] = React.useState("");

  return (
    <InputPayment
      value={cardNumber}
      onChangeText={setCardNumber}
      placeholder="Card number"
    />
  );
}

With Auto-Detection Callback

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";

export default function WithDetection() {
  const [cardNumber, setCardNumber] = React.useState("");
  const [cardType, setCardType] = React.useState<string | null>(null);

  return (
    <div>
      <InputPayment
        value={cardNumber}
        onChangeText={setCardNumber}
        onRecognizedPaymentChange={(type) => setCardType(type)}
      />
      {cardType && <p>Detected: {cardType}</p>}
    </div>
  );
}

Different Sizes

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";

export default function Sizes() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <InputPayment size="sm" placeholder="Small" />
      <InputPayment size="md" placeholder="Medium" />
      <InputPayment size="lg" placeholder="Large" />
    </div>
  );
}

Anatomy

import { InputPayment } from "@xsolla/xui-input-payment";

<InputPayment
  value={cardNumber} // Card number value
  onChangeText={setCardNumber} // Change handler
  size="md" // Input size
  placeholder="Card number" // Placeholder text
  possiblePayments={["visa", "mastercard"]} // Accepted cards
  maxVisiblePossiblePayments={5} // Max icons shown
  recognizedPayment="visa" // Force recognized type
  autoDetect={true} // Enable auto-detection
  errorMessage="Invalid card" // Error message
  disabled={false} // Disabled state
/>;

Examples

Custom Accepted Cards

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";

export default function CustomCards() {
  return (
    <InputPayment
      possiblePayments={["visa", "mastercard", "amex"]}
      maxVisiblePossiblePayments={3}
      placeholder="We accept Visa, Mastercard, Amex"
    />
  );
}

With Error State

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";

export default function WithError() {
  const [cardNumber, setCardNumber] = React.useState("");
  const [error, setError] = React.useState("");

  const validate = (value: string) => {
    if (value.length > 0 && value.length < 13) {
      setError("Card number too short");
    } else {
      setError("");
    }
  };

  return (
    <InputPayment
      value={cardNumber}
      onChangeText={(text) => {
        setCardNumber(text);
        validate(text);
      }}
      errorMessage={error}
    />
  );
}

Controlled Recognition

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";

export default function ControlledRecognition() {
  const [cardNumber, setCardNumber] = React.useState("");

  return (
    <InputPayment
      value={cardNumber}
      onChangeText={setCardNumber}
      autoDetect={false}
      recognizedPayment={cardNumber.startsWith("4") ? "visa" : undefined}
    />
  );
}

With Icon

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";
import { CreditCard } from "@xsolla/xui-icons-base";

export default function WithIcon() {
  return <InputPayment icon={<CreditCard />} placeholder="Enter card number" />;
}

In Payment Form

import * as React from "react";
import { InputPayment } from "@xsolla/xui-input-payment";
import { Input } from "@xsolla/xui-input";
import { Button } from "@xsolla/xui-button";

export default function PaymentForm() {
  const [cardNumber, setCardNumber] = React.useState("");
  const [cardType, setCardType] = React.useState<string | null>(null);

  return (
    <form
      style={{
        display: "flex",
        flexDirection: "column",
        gap: 16,
        maxWidth: 400,
      }}
    >
      <InputPayment
        value={cardNumber}
        onChangeText={setCardNumber}
        onRecognizedPaymentChange={setCardType}
        placeholder="Card number"
      />
      <div style={{ display: "flex", gap: 16 }}>
        <Input placeholder="MM/YY" style={{ flex: 1 }} />
        <Input placeholder="CVV" style={{ width: 100 }} />
      </div>
      <Input placeholder="Cardholder name" />
      <Button onPress={() => console.log("Submit", { cardNumber, cardType })}>
        Pay Now
      </Button>
    </form>
  );
}

API Reference

InputPayment

InputPaymentProps:

| Prop | Type | Default | Description | | :------------------------- | :----------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------ | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | value | string | - | Card number value. | | onChange | (e: ChangeEvent) => void | - | Standard change event handler. | | onChangeText | (text: string) => void | - | Text change handler. | | size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | Input size variant. | | placeholder | string | "Card number" | Placeholder text. | | icon | ReactNode | - | Left icon. | | disabled | boolean | false | Disabled state. | | error | boolean | - | Error state indicator. | | errorMessage | string | - | Error message text. | | possiblePayments | PaymentSystemKey[] | See below | Accepted payment types. | | maxVisiblePossiblePayments | number | 5 | Max payment icons shown. | | recognizedPayment | PaymentSystemKey | - | Force recognized payment type. | | onRecognizedPaymentChange | (type: PaymentSystemKey \| null) => void | - | Detection callback. | | autoDetect | boolean | true | Enable auto-detection. | | aria-label | string | "Card number" | Accessible label. | | testID | string | - | Test identifier. |

Default possiblePayments:

[
  "mastercard",
  "visa",
  "maestro",
  "diners",
  "amex",
  "discover",
  "jcb",
  "unionpay",
];

PaymentSystemKey:

type PaymentSystemKey =
  | "visa"
  | "mastercard"
  | "amex"
  | "diners"
  | "maestro"
  | "unionpay"
  | "discover"
  | "jcb"
  | "aura"
  | "cartesbancaires"
  | "cirrus"
  | "dankort"
  | "elo"
  | "hipercard"
  | "mir"
  | "naranja"
  | "paypal"
  | "sodexo"
  | "uatp";

Card Detection

The component automatically detects card types based on BIN (Bank Identification Number) ranges:

| Card Type | BIN Pattern | | :--------------- | :------------------------- | | Visa | Starts with 4 | | Mastercard | 51-55 or 2221-2720 | | American Express | 34, 37 | | Discover | 6011, 644-649, 65 | | JCB | 3528-3589 | | Diners Club | 300-305, 36, 38 | | UnionPay | 62 (except Discover range) | | Maestro | 50, 56-69 | | Mir | 2200-2204 |

Icon Animation

• Payment icons cycle through when multiple are available
• When a card type is detected, other icons slide out
• The recognized card icon remains visible
• Animation is smooth with 300ms transitions

Accessibility

• Input has aria-label for screen readers
• Error messages are linked via aria-describedby
• Payment icons have descriptive aria-label
• Disabled state is announced with aria-disabled
• inputMode="numeric" shows numeric keyboard on mobile