Collect Card Information

Getting Started

To create a CardForm object in the MoneyHash Payment SDK, you will use the CardFormBuilder class. This builder allows you to configure the card form's fields, such as the card number, CVV, cardholder name, expiry month, and expiry year, while setting up listeners to monitor changes in their states.

The builder's set functions allow you to define listeners for each field. These listeners are functions that will be called every time the user updates the respective field. The listener function receives a CardFieldState object, which contains information about the field’s validity, error message (if any), and the current input length.

CardFieldState

Each time the user updates a field, the corresponding listener will be invoked with a CardFieldState object. The CardFieldState provides the following details:

isValid: A boolean that indicates whether the field is valid or not.
errorMessage: An optional string containing an error message if the field is invalid.
length: The current length of the input in the field.

class CardFieldState {
  final bool isValid;
  final String? errorMessage;
  final int length;
}

Creating the Card Form

Here’s an example of how to use CardFormBuilder to create a card form with listeners for each field, along with a CardFormConfiguration that specifies whether the cardholder’s name is required or whether or not MoneyHash should check the correctness of the card number:

import 'package:moneyhash_payment/data/card/card_field_type.dart';
import 'package:moneyhash_payment/data/card/card_field_state.dart';
import 'package:moneyhash_payment/src/card_form_collector.dart';

void main() {
  // Create a configuration indicating that the cardholder name is required.
  final config = CardFormConfiguration(isCardHolderNameRequired: true, enableCardNumberValidation: true);

  final CardForm cardForm = CardFormBuilder()
      // Pass the configuration to the builder.
      .setConfiguration(config)

      // Set your field listeners as before.
      .setCardNumberField((CardFieldState? state) {
        if (state != null) {
          print('Card Number Valid: ${state.isValid}');
          print('Card Number Length: ${state.length}');
        }
      })
      .setCVVField((CardFieldState? state) {
        if (state != null) {
          print('CVV Valid: ${state.isValid}');
          print('CVV Length: ${state.length}');
        }
      })
      .setCardHolderNameField((CardFieldState? state) {
        if (state != null) {
          print('Card Holder Name Valid: ${state.isValid}');
        }
      })
      .setExpiryMonthField((CardFieldState? state) {
        if (state != null) {
          print('Expiry Month Valid: ${state.isValid}');
        }
      })
      .setExpiryYearField((CardFieldState? state) {
        if (state != null) {
          print('Expiry Year Valid: ${state.isValid}');
        }
      })
      .build();

  // Now you have a cardForm ready to use in your app
}

Explanation

Each set function, such as setCardNumberField, takes a function (listener) that will be invoked every time the corresponding field is updated by the user. This listener function receives a CardFieldState object, which contains:

isValid: Whether the current input is valid.
length: The current length of the input.
errorMessage: Any error message if the input is invalid.

For example, in the setCardNumberField function, when the user updates the card number, the listener will print whether the card number is valid and the current length of the input.

📘
MoneyHash considers card number valid based on the length only. Card number with length from 13 to 19 are considered valid.

With this setup, you can easily track the user's input and handle any validation errors or updates as needed.

setConfiguration(_:) Method:
By calling setConfiguration(config) on the CardFormBuilder, you pass a CardFormConfiguration instance that customizes the form requirements (e.g., making the cardholder name required, or disable validating the card number). This ensures that the resulting CardForm respects those settings when rendered.

Creating Secured Text Fields

The SDK provides a SecureTextField widget, which is used to securely collect card information. You can use this widget to build the card number, CVV, expiry month, and expiry year fields, all of which integrate seamlessly with the CardForm.

SecureTextField Example

Below is an example of how to create five SecureTextField widgets for each of the required card fields (Card Number, CVV, Cardholder Name, Expiry Month, and Expiry Year):

import 'package:flutter/material.dart';
import 'package:moneyhash_payment/data/card/card_field_type.dart';
import 'package:moneyhash_payment/vault/card_collector.dart';
import 'package:moneyhash_payment/vault/widget/secure_text_field.dart';

class CardFormWidget extends StatelessWidget {
  final CardForm _cardForm;

  const CardFormWidget({required this.cardForm});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        SecureTextField(
          cardForm: _cardForm,
          type: CardFieldType.cardNumber,
          label: "Card Number",
          placeholder: "Enter card number",
          keyboardType: TextInputType.number,
        ),
        SizedBox(height: 10),
        SecureTextField(
          cardForm: _cardForm,
          type: CardFieldType.cvv,
          label: "CVV",
          placeholder: "Enter CVV",
          keyboardType: TextInputType.number,
        ),
        SizedBox(height: 10),
        SecureTextField(
          cardForm: cardForm,
          type: CardFieldType.cardHolderName,
          label: "Cardholder Name (Optional)",
          placeholder: "Enter cardholder name",
        ),
        SizedBox(height: 10),
        SecureTextField(
          cardForm: _cardForm,
          type: CardFieldType.expiryMonth,
          label: "Expiry Month",
          placeholder: "MM",
          keyboardType: TextInputType.number,
        ),
        SizedBox(height: 10),
        SecureTextField(
          cardForm: _cardForm,
          type: CardFieldType.expiryYear,
          label: "Expiry Year",
          placeholder: "YYYY",
          keyboardType: TextInputType.number,
        ),
      ],
    );
  }
}

Explanation

SecureTextField Widget: This widget is used for securely handling sensitive card information. It requires a CardForm object, which collects and manages the data for each field. The SecureTextField connects to the card form via the cardFormCollector property, ensuring all inputs are securely processed.
Type: Each SecureTextField requires a CardFieldType, which specifies the type of data the field will collect:
- CardFieldType.cardNumber for the card number
- CardFieldType.cvv for the CVV
- CardFieldType.cardHolderName for the cardholder name (optional)
- CardFieldType.expiryMonth for the expiry month
- CardFieldType.expiryYear for the expiry year
Placeholder, Keyboard Type, and Label: The SecureTextField widget also accepts a placeholder and label to provide context to the user, and a keyboardType to specify the input type (e.g., TextInputType.number for numeric fields).
Required Fields: While the cardholder name is optional, the card number, CVV, expiry month, and expiry year fields are required for collecting the necessary card details.

By using these fields in your form, you can securely collect and manage sensitive card information in compliance with security standards