---
description: >-
  This feature automatically detects the credit card type from the entered
  digits, formats the number according to predefined patterns, and validates the
  number using the Luhn algorithm, etc.
---

# Credit Card Specific Features

## Overview

The Credit Card Specific Features of the SiticoneCardNumberBox control provide automated handling of credit card input. The control detects the card type (e.g., Visa, MasterCard, American Express), formats the input to match expected grouping patterns, enforces length limits (if enabled), and validates the card number using the Luhn algorithm. It also exposes properties to customize visual feedback (colors and logos) based on the card's validity and type. Additionally, events such as CardNumberCompleted, CardValidationChanged, and CardTypeChanged allow your application to react to card input changes.

***

### Property Details

The table below summarizes key properties related to the credit card functionality:

| Property               | Description                                                                                   | Default Value / Notes                                |
| ---------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| UnknownCardNumberColor | Color used for card number text when the card type is unknown.                                | Red (or as configured)                               |
| ValidCardNumberColor   | Color used when the card number passes validation.                                            | Green (or as configured)                             |
| ErrorCardNumberColor   | Color used when the card number is invalid (e.g., over-length or in error format).            | Red (or as configured)                               |
| CorrectFormatTextColor | Color for correctly formatted card number text.                                               | Black (or as configured)                             |
| LimitToKnownCardLength | When set to true, input length is limited to the expected length for the detected card type.  | true                                                 |
| DetectedCardType       | Read-only property that indicates the current detected card type.                             | CardType.Unknown until a valid prefix is entered     |
| FormattedCardNumber    | Returns the card number formatted with spaces or groups according to the card type’s pattern. | Derived automatically from the entered digits        |
| UnformattedCardNumber  | Returns the numeric-only version of the entered card number.                                  | Derived from input by stripping non-digit characters |

***

### Event Details

The table below summarizes events provided for credit card features:

<table><thead><tr><th width="234">Event Name</th><th>Description</th><th>Usage</th></tr></thead><tbody><tr><td>CardNumberCompleted</td><td>Fires when the input reaches a known valid length for the detected card type.</td><td>Use to trigger subsequent processing or submission.</td></tr><tr><td>CardValidationChanged</td><td>Fires when the validity of the card number changes (e.g., from invalid to valid).</td><td>Subscribe to update UI elements or notify users.</td></tr><tr><td>CardTypeChanged</td><td>Fires when the detected card type changes based on the current input.</td><td>Use to update card logos or related visual elements.</td></tr></tbody></table>

***

### Code Examples

#### Example 1: Reading Formatted and Unformatted Card Numbers

This example shows how to access the formatted and unformatted card numbers after the user completes their input.

```csharp
// Assume cardNumberBox is an instance of SiticoneCardNumberBox

// When the card number is completed, you can access the formatted and unformatted versions:
string formattedNumber = cardNumberBox.FormattedCardNumber;
string unformattedNumber = cardNumberBox.UnformattedCardNumber;

Console.WriteLine("Formatted: " + formattedNumber);
Console.WriteLine("Unformatted: " + unformattedNumber);
```

#### Example 2: Handling Card Validation and Card Type Changes

Subscribe to the events to update your application based on the validity or type of the entered card.

```csharp
// Subscribe to card validation changed event
cardNumberBox.CardValidationChanged += (sender, e) =>
{
    if (e.IsValid)
    {
        // For example, display a check mark or enable a "Submit" button.
        Console.WriteLine("Card is valid.");
    }
    else
    {
        // Show an error message or disable related UI elements.
        Console.WriteLine("Card is invalid.");
    }
};

// Subscribe to card type changed event
cardNumberBox.CardTypeChanged += (sender, e) =>
{
    Console.WriteLine($"Card type changed from {e.OldCardType} to {e.NewCardType}");
    // Optionally update a UI element to show the card logo.
};

// Subscribe to card number completed event
cardNumberBox.CardNumberCompleted += (sender, e) =>
{
    Console.WriteLine("Card entry complete.");
    // Process the card number as needed.
};
```

#### Example 3: Enforcing Known Card Length

By enabling `LimitToKnownCardLength`, the control prevents users from entering more digits than expected for the detected card type.

```csharp
// Enable limiting the input length based on card type information.
cardNumberBox.LimitToKnownCardLength = true;

// Once the user enters the full number, the control will automatically trigger card number completed event.
```

***

### Key Points

The table below summarizes the key points for credit card specific functionality:

<table><thead><tr><th width="213">Topic</th><th>Description</th></tr></thead><tbody><tr><td>Card Type Detection</td><td>Automatically identifies the card type based on numeric prefixes.</td></tr><tr><td>Automatic Formatting</td><td>Formats the card number input according to predefined patterns (e.g., grouping digits).</td></tr><tr><td>Input Validation</td><td>Validates the card number using the Luhn algorithm and enforces length constraints.</td></tr><tr><td>Visual Feedback</td><td>Updates text colors and displays a card logo or a question mark for unknown types.</td></tr><tr><td>Event Notifications</td><td>Provides events to handle card completion, validation changes, and type changes.</td></tr></tbody></table>

***

### Best Practices

The table below outlines recommended practices when using credit card features:

<table><thead><tr><th width="368">Best Practice</th><th>Explanation</th></tr></thead><tbody><tr><td>Always subscribe to CardValidationChanged</td><td>Use the event to update your UI in real time as the card number validity changes.</td></tr><tr><td>Use LimitToKnownCardLength to prevent over-entry</td><td>Ensures that users cannot enter more digits than allowed for a recognized card type.</td></tr><tr><td>Test with various card types</td><td>Validate that the control correctly detects different card prefixes and formats numbers properly.</td></tr><tr><td>Use the CardTypeChanged event to update logos dynamically</td><td>Provides a better user experience by showing the correct card logo when detected.</td></tr></tbody></table>

***

### Common Pitfalls

The table below lists common pitfalls and ways to avoid them:

<table><thead><tr><th width="356">Pitfall</th><th>How to Avoid It</th></tr></thead><tbody><tr><td>Incorrect card type detection</td><td>Test with a wide range of card numbers and ensure that the _cardInfo dictionary is up to date.</td></tr><tr><td>Overwriting valid input due to aggressive length limits</td><td>Confirm that LimitToKnownCardLength is only enabled when you expect a specific card type; otherwise disable it.</td></tr><tr><td>Misinterpreting formatted vs unformatted output</td><td>Use FormattedCardNumber for display and UnformattedCardNumber for processing transactions or backend validations.</td></tr><tr><td>Not handling event subscriptions</td><td>Always subscribe to events like CardValidationChanged and CardTypeChanged to reflect changes in the UI.</td></tr></tbody></table>

***

### Usage Scenarios

The table below describes several scenarios where the credit card features are essential:

<table><thead><tr><th width="313">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Payment processing in e-commerce</td><td>Automatically validate and format the credit card number during the checkout process.</td></tr><tr><td>Banking application data entry</td><td>Detect and display the card type dynamically as the user enters the number, providing immediate feedback.</td></tr><tr><td>Mobile wallet integration</td><td>Use the events to trigger subsequent actions once a valid card number is entered and formatted.</td></tr></tbody></table>

***

### Real Life Usage Scenarios

<table><thead><tr><th width="303">Scenario</th><th>Example</th></tr></thead><tbody><tr><td>Online shopping cart checkout</td><td>Validate the card number format and type before proceeding to payment confirmation.</td></tr><tr><td>In-app payment setup</td><td>Automatically update the card logo and color feedback based on the card type, enhancing user trust.</td></tr><tr><td>Subscription management system</td><td>Ensure that only correctly formatted and valid card numbers are accepted for recurring billing.</td></tr></tbody></table>

***

### Troubleshooting Tips

The table below provides tips for troubleshooting common issues:

<table><thead><tr><th width="236">Issue</th><th>Potential Cause</th><th>Recommended Action</th></tr></thead><tbody><tr><td>Card type is not detected correctly</td><td>The entered prefix does not match any known patterns</td><td>Verify that the input contains only digits and that LimitToKnownCardLength is properly set.</td></tr><tr><td>Formatted number appears incorrect</td><td>Formatting pattern misalignment with card type</td><td>Check the _cardInfo dictionary and confirm the formatPattern is correct for the card type.</td></tr><tr><td>Events not firing as expected</td><td>Event subscription issues</td><td>Ensure that your code subscribes to CardNumberCompleted, CardValidationChanged, and CardTypeChanged events.</td></tr></tbody></table>

***

### Review

The table below provides a summary review of the credit card specific features:

<table><thead><tr><th width="178">Aspect</th><th>Review Notes</th></tr></thead><tbody><tr><td>Automation</td><td>Automatic detection, formatting, and validation reduce manual processing significantly.</td></tr><tr><td>Visual Feedback</td><td>Dynamic text color changes and logo displays enhance user experience and trust.</td></tr><tr><td>Flexibility</td><td>Customizable properties allow adaptation to various card types and integration requirements.</td></tr><tr><td>Integration</td><td>Events provide hooks for seamless integration with payment processing workflows.</td></tr></tbody></table>

***

### Summary

The Credit Card Specific Features of the SiticoneCardNumberBox control streamline the process of capturing and validating credit card numbers. By automatically detecting the card type, formatting the input appropriately, and validating it with the Luhn algorithm, the control reduces development overhead and improves user experience. Developers can customize visual feedback and subscribe to events for dynamic behavior, making the control a robust solution for payment entry interfaces.

***

### Additional Integration Example

Below is a complete example demonstrating how to integrate credit card features into your WinForms application:

```csharp
public partial class PaymentForm : Form
{
    public PaymentForm()
    {
        InitializeComponent();
        InitializeCardInput();
    }

    private void InitializeCardInput()
    {
        // Create the SiticoneCardNumberBox control
        SiticoneCardNumberBox cardNumberBox = new SiticoneCardNumberBox
        {
            Location = new Point(20, 20),
            Size = new Size(350, 60),
            LimitToKnownCardLength = true,
            UnknownCardNumberColor = Color.Red,
            ValidCardNumberColor = Color.Green,
            ErrorCardNumberColor = Color.Red,
            CorrectFormatTextColor = Color.Black,
            PlaceholderText = "Enter your credit card number",
            PlaceholderColor = Color.Gray
        };

        // Subscribe to credit card events
        cardNumberBox.CardValidationChanged += (sender, e) =>
        {
            if (e.IsValid)
            {
                // Enable submit button or update UI
                Console.WriteLine("Card validated successfully.");
            }
            else
            {
                // Display an error message
                Console.WriteLine("Invalid card number.");
            }
        };

        cardNumberBox.CardTypeChanged += (sender, e) =>
        {
            // Update card logo display based on e.NewCardType
            Console.WriteLine($"Detected card type changed from {e.OldCardType} to {e.NewCardType}");
        };

        cardNumberBox.CardNumberCompleted += (sender, e) =>
        {
            // Proceed with further processing once card entry is complete
            Console.WriteLine("Card entry is complete.");
            Console.WriteLine("Formatted: " + e.FormattedCardNumber);
            Console.WriteLine("Unformatted: " + e.UnformattedCardNumber);
        };

        // Add the control to the form
        this.Controls.Add(cardNumberBox);
    }
}
```

***

By following this documentation, developers can leverage the Credit Card Specific Features of the SiticoneCardNumberBox to build robust, user-friendly payment input interfaces with automated formatting, validation, and dynamic visual feedback.
