iOS Element Types

TextElementUITextField

The TextElementUITextField element type enables collecting user String data. Mask and transform capabilities are available to be configured on these elements.

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class TokenizeName: UIViewController {
    @IBOutlet weak var nameTextField: TextElementUITextField!
    @IBOutlet weak var output: UITextView!

    @IBAction func tokenize(_ sender: Any) {
        let body: [String: Any] = [
            "data": [
                "name": self.nameTextField,
            ],
            "type": "token"
        ]

        BasisTheoryElements.tokenize(body: body, apiKey: config.btApiKey!) { data, error in
            guard error == nil else {
                self.output.text = "There was an error!"
                print(error)
                return
            }

            let stringifiedData = String(data: try! JSONSerialization.data(withJSONObject: data!.value as! [String: Any], options: .prettyPrinted), encoding: .utf8)!

            self.output.text = stringifiedData
            print(stringifiedData)
        }
    }
}

Configuration

The TextElementUITextField extends the native UITextField from UIKit, so all standard properties and methods supported by UITextField are supported by TextElementUITextField.

Properties

The following additional properties are supported when programmatically interacting with a TextElementUITextField:

Name	Type
validation	No default validation. Validation can be overridden.
mask	No default mask. Mask can be overridden.
transform	No default transform. Transform can be overridden.
enableCopy	enableCopy defaults to `false` and can be overriden.
copyIconColor	copyIconColor defaults to `UIColor.blue` and can be overriden.
getValueType	getValueType defaults to `.string` and can be overriden.

TextElementUITextField extends the native iOS UITextField from UIKit, so all standard properties and attributes supported by UITextField are supported by TextElementUITextField.

Methods

Signature	Description
`setValue(elementValueReference: ElementValueReference)`	Sets the element's text to the value referenced by the provided ElementValueReference.
`setValueRef(element: TextElementUITextField)`	Binds the provided `element: TextElementUITextField` instance as a value source for this element, keeping the value of this element in sync with any changes made to the other element.

TextElementUITextField extends the native iOS UITextField from UIKit, so all standard methods supported by UITextField are supported by TextElementUITextField.

CardNumberUITextField

The CardNumberUITextField element type renders a card number input featuring automatic brand detection, input validation, and masking. The input must be Luhn valid and be an acceptable length for the card brand.

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class TokenizeCardNumber: UIViewController {
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!
    @IBOutlet weak var output: UITextView!

    @IBAction func tokenize(_ sender: Any) {
        let body: [String: Any] = [
            "data": [
                "number": self.cardNumberTextField,
            ],
            "type": "token"
        ]

        BasisTheoryElements.tokenize(body: body, apiKey: config.btApiKey!) { data, error in
            guard error == nil else {
                self.output.text = "There was an error!"
                print(error)
                return
            }

            let stringifiedData = String(data: try! JSONSerialization.data(withJSONObject: data!.value as! [String: Any], options: .prettyPrinted), encoding: .utf8)!

            self.output.text = stringifiedData
            print(stringifiedData)
        }
    }
}

Configuration

The CardNumberUITextField element type extends the TextElementUITextField and UITextField class, so all properties and methods supported by TextElementUITextField and UITextField are also supported here.

By default, this element is configured with:

Configuration	Defaults
validation	Input must be Luhn valid and be an acceptable length for the card brand.
mask	The mask changes depending on the card brand identified for this input according to the card brand.
transform	The transform removes all spaces set by the mask before tokenization.
enableCopy	enableCopy defaults to `false` and can be overriden.
copyIconColor	copyIconColor defaults to `UIColor.blue` and can be overriden.
getValueType	getValueType defaults to `.string` and can be overriden.

Card Brands

The first several digits of the card number are analyzed as the user is typing to determine the card brand. The brand is used to automatically set a mask to a brand-specific format. If the CardNumberUITextField is bound to a CardVerificationCodeUITextField, a mask is also automatically set on the CardVerificationCodeElement based on the brand's CVC length requirements.

Supported card brands are defined in the table below:

Brand	Identifier	Card Number Digits	CVC Digits
American Express	`americanExpress`	15	4
Diners Club	`dinersClub`	14, 16, 19	3
Discover	`discover`	16, 19	3
Elo	`elo`	16	3
Hiper	`hiper`	16	3
HiperCard	`hipercard`	16	3
JCB	`jcb`	16-19	3
Maestro	`maestro`	12-19	3
Mastercard	`mastercard`	16	3
MIR	`mir`	16-19	3
UnionPay	`unionPay`	14-19	3
Visa	`visa`	16, 18, 19	3

Some card brands have issued card numbers with multiple lengths. The Card Number Digits column documents all acceptable card number lengths for the brand (in number of digits, excluding formatting characters).

Customizing Card Brands

You can extend default card brands to include additional BIN numbers or create custom card brands by modifying the cardType property of the CardNumberUITextField.

Overriding existing card brands

...
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!

    var defaultWithCustomVisaCard = CardBrand.DefaultCardBrands.filter { $0.cardBrandName != CardBrandName.visa }
    
    defaultWithCustomVisaCard.append(CardBrandDetails(cardBrandName: CardBrandName.visa, cardIdentifiers: [4, 8405],
                                        cvcMaskInput: [try! NSRegularExpression(pattern: "\\d"), try! NSRegularExpression(pattern: "\\d"), try! NSRegularExpression(pattern: "\\d")],
                                        gaps: [4, 8, 12], validLengths: [16, 18, 19]))
    
    cardNumberTextField.cardTypes = defaultWithCustomVisaCard

When adding custom card brands the default list is replaced, and validation will only run against those brands defined in the cardTypes list.

For more granular control, we expose card brands individually and a list with all the default card brands.

CardExpirationDateUITextField

The CardExpirationDateUITextField element type features a month and year formatted input with validation. The input must be the current month and year or later.

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class TokenizeCardExpirationDate: UIViewController {
    @IBOutlet weak var expirationDateTextField: CardExpirationDateUITextField!
    @IBOutlet weak var output: UITextView!

    @IBAction func tokenize(_ sender: Any) {
        let body: [String: Any] = [
            "data": [
                "expiration_month": self.expirationDateTextField.month(),
                "expiration_year": self.expirationDateTextField.year(),
            ],
            "type": "token"
        ]

        BasisTheoryElements.tokenize(body: body, apiKey: config.btApiKey!) { data, error in
            guard error == nil else {
                self.output.text = "There was an error!"
                print(error)
                return
            }

            let stringifiedData = String(data: try! JSONSerialization.data(withJSONObject: data!.value as! [String: Any], options: .prettyPrinted), encoding: .utf8)!

            self.output.text = stringifiedData
            print(stringifiedData)
        }
    }
}

Configuration

The CardExpirationDateUITextField element type extends the TextElementUITextField and UITextField class, so all properties and methods supported by TextElementUITextField and UITextField are also supported here.

By default, this element is configured with:

Configuration	Defaults
validation	Input must be the current month and year or later.
mask	The mask is two digits followed by a forward slash followed by two more digits (eg. `MM/YY` ).
transform	No default transform.
enableCopy	enableCopy defaults to `false` and can be overriden.
copyIconColor	copyIconColor defaults to `UIColor.blue` and can be overriden.
getValueType	getValueType defaults to `.string` and can be overriden.

Month and Year

Both the month and year values need to be retrieved from a CardExpirationDateUITextField with the month() and year() functions, respectively. Below is an example:

let body: [String: Any] = [
  "data": [
    "number": self.cardNumberTextField,
    "expiration_month": self.expirationDateTextField.month(),
    "expiration_year": self.expirationDateTextField.year(),
    "cvc": self.cvcTextField
  ],
  "type": "card"
]

Before SDK version 3.0.0 the month() and year() methods rendered as String when sending the value to the API. As of version 3.0.0, these methods now render as Int when sending the value to the API.

Format

format(dateFormat: String) allows you to customize card expiration dates. It implements Swift's DateFormatter, so all date formats supported by it are also available.

    // expirationDateTextField value is 04/25

    let body: [String: Any] = [
        "data": [
            "expiration_date1": self.expirationDateTextField.format(dateFormat: "yyyy-MM"), // 2025-04
            "expiration_date2": self.expirationDateTextField.format(dateFormat: "MM"),      // 04
            "expiration_date3": self.expirationDateTextField.format(dateFormat: "M"),       // 4
            "expiration_date4": self.expirationDateTextField.format(dateFormat: "MM/yyyy"), // 04/2025
            "expiration_date5": self.expirationDateTextField.format(dateFormat: "yy"),      // 25
        ],
        "type": "token"
    ]

This code example uses Basis Theory HTTP Client

CardVerificationCodeUITextField

The CardVerificationCodeUITextField element type is used to collect the card verification code.

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class TokenizeCVC: UIViewController {
    @IBOutlet weak var cvcTextField: CardVerificationCodeUITextField!
    @IBOutlet weak var output: UITextView!

    @IBAction func tokenize(_ sender: Any) {
        let body: [String: Any] = [
            "data": [
                "cvc": self.cvcTextField,
            ],
            "type": "token"
        ]

        BasisTheoryElements.tokenize(body: body, apiKey: config.btApiKey!) { data, error in
            guard error == nil else {
                self.output.text = "There was an error!"
                print(error)
                return
            }

            let stringifiedData = String(data: try! JSONSerialization.data(withJSONObject: data!.value as! [String: Any], options: .prettyPrinted), encoding: .utf8)!

            self.output.text = stringifiedData
            print(stringifiedData)
        }
    }
}

Configuration

The CardVerificationCodeUITextField element type extends the TextElementUITextField and UITextField class, so all properties and methods supported by TextElementUITextField and UITextField are also supported here.

By default, this element is configured with:

Configuration	Defaults
validation	No default validation. Always valid in ElementEvent.
mask	If not associated with a `CardNumberUITextField`, the mask is a 4 digit number. If it is, the mask changes depending on the card brand identified by the `CardNumberUITextField`. Refer to the section below.
transform	No default transform.
enableCopy	enableCopy defaults to `false` and can be overriden.
copyIconColor	copyIconColor defaults to `UIColor.blue` and can be overriden.

Associating a CardNumberUITextField

Associating a CardNumberUITextField with a CardVerificationCodeUITextField will enhance masking capabilities of the CVC element. By default, a CardVerificationCodeUITextField mask is a 4-digit number. But when associated with a CardNumberUITextField, the mask will change to match the card brand identified by the CardNumberUITextField. Below is an example of how to make that association:

cvcTextField.setConfig(
  options: CardVerificationCodeOptions(
    cardNumberUITextField: cardNumberTextField
  )
)

Collecting Card Data Example

See below for an example that uses all the card-related mobile elements, CardNumberUITextField, CardExpirationDateUITextField, and CardVerificationCodeUITextField together.

Note that when these card-related elements are grouped together in a dictionary, as shown in the value of data below, the token type of card should be used.

import Foundation
import UIKit
import BasisTheoryElements
import Combine

class TokenizeBillingInformationViewController: UIViewController {
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!
    @IBOutlet weak var expirationDateTextField: CardExpirationDateUITextField!
    @IBOutlet weak var cvcTextField: CardVerificationCodeUITextField!
    @IBOutlet weak var output: UITextView!

    private var cancellables = Set<AnyCancellable>()

    @IBAction func tokenize(_ sender: Any) {
        let body: [String: Any] = [
            "data": [
                "number": self.cardNumberTextField,
                "expiration_month": self.expirationDateTextField.month(),
                "expiration_year": self.expirationDateTextField.year(),
                "cvc": self.cvcTextField
            ],
            "type": "card"
        ]

        BasisTheoryElements.tokenize(body: body, apiKey: config.btApiKey!) { data, error in
            guard error == nil else {
                self.output.text = "There was an error!"
                print(error)
                return
            }

            let stringifiedData = String(data: try! JSONSerialization.data(withJSONObject: data!.value as! [String: Any], options: .prettyPrinted), encoding: .utf8)!

            self.output.text = stringifiedData
            print(stringifiedData)
        }
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        let cvcOptions = CardVerificationCodeOptions(cardNumberUITextField: cardNumberTextField)
        cvcTextField.setConfig(options: cvcOptions)

        cardNumberTextField.subject.sink { completion in
            print(completion)
        } receiveValue: { message in
            print("cardNumberTextField:")
            print(message)
        }.store(in: &cancellables)

        expirationDateTextField.subject.sink { completion in
            print(completion)
        } receiveValue: { message in
            print("expirationDateTextField:")
            print(message)
        }.store(in: &cancellables)

        cvcTextField.subject.sink { completion in
            print(completion)
        } receiveValue: { message in
            print("cvcTextField:")
            print(message)
        }.store(in: &cancellables)
    }
}

TextElementUITextField​

Configuration​

Properties​

Methods​

CardNumberUITextField​

Configuration​

Card Brands​

Customizing Card Brands​

Overriding existing card brands​

CardExpirationDateUITextField​

Configuration​

Month and Year​

Format​

CardVerificationCodeUITextField​

Configuration​

Associating a CardNumberUITextField​

Collecting Card Data Example​

TextElementUITextField

Configuration

Properties

Methods

CardNumberUITextField

Configuration

Card Brands

Customizing Card Brands

Overriding existing card brands

CardExpirationDateUITextField

Configuration

Month and Year

Format

CardVerificationCodeUITextField

Configuration

Associating a CardNumberUITextField

Collecting Card Data Example