Card transactions: Customising the UI

The Drop-In Controller includes customisation options, allowing you to tailor the appearance of your checkout to better fit the branding of your app. There are options that allow you to change the appearance of both the payment form, and also that of the overlay shown by the Access Control Server (ACS) as part of the 3-D Secure process.

Setting default style managers

let inputViewStyleManager = InputViewStyleManager.defaultLight()
let payButtonStyleManager = PayButtonStyleManager.defaultLight()
let dropInViewStyleManager = DropInViewStyleManager(
  inputViewStyleManager: inputViewStyleManager,
  requestButtonStyleManager: payButtonStyleManager,
  backgroundColor: .white,
  spacingBetweenInputViews: 25,
  insets: UIEdgeInsets(top: 25, left: 35, bottom: -30, right: -35)
)

Style managers with all options

let inputViewStyleManager = InputViewStyleManager(
  titleColor: UIColor.gray,
  textFieldBorderColor: UIColor.black.withAlphaComponent(0.8),
  textFieldBackgroundColor: .clear,
  textColor: .black,
  placeholderColor: UIColor.lightGray.withAlphaComponent(0.8),
  errorColor: UIColor.red.withAlphaComponent(0.8),
  textFieldImageColor: .black,
  titleFont: UIFont.systemFont(ofSize: 16, weight: .regular),
  textFont: UIFont.systemFont(ofSize: 16, weight: .regular),
  placeholderFont: UIFont.systemFont(ofSize: 16, weight: .regular),
  errorFont: UIFont.systemFont(ofSize: 12, weight: .regular),
  textFieldImage: nil,
  titleSpacing: 5,
  errorSpacing: 3,
  textFieldHeightMargins: HeightMargins(top: 10, bottom: 10),
  textFieldBorderWidth: 1,
  textFieldCornerRadius: 6
)

let payButtonStyleManager = PayButtonStyleManager(
  titleColor: .white,
  enabledBackgroundColor: .black,
  disabledBackgroundColor: UIColor.lightGray.withAlphaComponent(0.6),
  borderColor: .clear,
  titleFont: UIFont.systemFont(ofSize: 16, weight: .medium),
  spinnerStyle: .medium,
  spinnerColor: .white,
  buttonContentHeightMargins: HeightMargins(top: 15, bottom: 15),
  borderWidth: 0,
  cornerRadius: 6
)

let dropInViewStyleManager = DropInViewStyleManager(
  inputViewStyleManager: inputViewStyleManager,
  requestButtonStyleManager: payButtonStyleManager,
  backgroundColor: .white,
  spacingBetweenInputViews: 25,
  insets: UIEdgeInsets(top: 25, left: 35, bottom: -30, right: -35)
)

DropInViewStyleManager

	Parameter	Description
	backgroundColor	The background colour of the Drop-In View.
	inputViewStyleManager	Used to style the input views.
	insets	Defines the insets (spacing) of the form relative to the parental view.
	requestButtonStyleManager	Used to style the pay button.
	spacingBetweenInputViews	The size of the spaces between all input views fields of the form.

InputViewStyleManager

	Parameter	Description
	errorColor	The colour of the validation error.
	errorFont	The font of the validation error.
	errorSpacing	The distance of the error label from the text field.
	placeholderColor	The colour of the placeholder.
	placeholderFont	The font of the placeholder.
	textColor	The colour of the text.
	textFieldBackgroundColor	The background colour of the text field.
	textFieldBorderColor	The border colour of the text field.
	textFieldBorderWidth	The width of the text field border.
	textFieldCornerRadius	The radius of the corner of the text field.
	textFieldHeightMargins	The text field edge insets. This changes the height of the text field.
	textFieldImage	Image displayed on left of text field.
	textFieldImageColor	The colour of the text field image.
	textFont	The font of the text.
	titleColor	The colour of the title.
	titleFont	The font of the title.
	titleSpacing	The distance of the title label from the text field.

PayButtonStyleManager

	Parameter	Description
	borderColor	The colour of the button border.
	borderWidth	The width of the button border.
	buttonContentHeightMargins	The button content edge insets. This changes the height of the button.
	cornerRadius	The radius of the corner of the button.
	disabledBackgroundColor	The colour of the button when disabled.
	enabledBackgroundColor	The colour of the button when enabled.
	spinnerColor	The colour of the loading spinner.
	spinnerStyle	The style of the loading spinner.
	titleColor	The button title colour.
	titleFont	The button title font.

CardinalToolbarStyleManager

The following is an example of the view controller components for Cardinal Commerce (ACS):

let toolbarStyleManager = CardinalToolbarStyleManager(textColor: .black, textFont: nil, backgroundColor: .white, headerText: "Trust payment checkout", buttonText: nil)
let labelStyleManager = CardinalLabelStyleManager(textColor: .gray, textFont: nil, headingTextColor: .black, headingTextFont: nil)
let verifyButtonStyleManager = CardinalButtonStyleManager(textColor: .white, textFont: nil, backgroundColor: .black, cornerRadius: 6)
let continueButtonStyleManager = CardinalButtonStyleManager(textColor: .white, textFont: nil, backgroundColor: .black, cornerRadius: 6)
let resendButtonStyleManager = CardinalButtonStyleManager(textColor: .black, textFont: nil, backgroundColor: nil, cornerRadius: 0)

let textBoxStyleManager = CardinalTextBoxStyleManager(textColor: .black, textFont: nil, borderColor: .black, cornerRadius: 6, borderWidth: 1)

let cardinalStyleManager = CardinalStyleManager(toolbarStyleManager: toolbarStyleManager, labelStyleManager: labelStyleManager, verifyButtonStyleManager: verifyButtonStyleManager, continueButtonStyleManager: continueButtonStyleManager, resendButtonStyleManager: resendButtonStyleManager, textBoxStyleManager: textBoxStyleManager)

	Parameter	Description
	CardinalButtonStyleManager	Styling for the buttons on the form hosted by the ACS.
	CardinalCancelButtonStyleManager	Styling for the cancel button on the form hosted by the ACS.
	CardinalLabelStyleManager	Styling for the label on the form hosted by the ACS.
	CardinalTextBoxStyleManager	Styling for the text box on the form hosted by the ACS.
	CardinalToolbarStyleManager	Styling for the toolbar on the form hosted by the ACS.

How to configure visibility of Drop-In View Controller components

DropInViewController has a property called visibleFields: [DropInViewVisibleFields].

You can use this to determine which input fields on the checkout form are visible to the customer (e.g. when performing a tokenised payment, you may wish to hide all but the security code fields). If you remove this parameter from the init function, then all fields will be visible. You can set all components in an array that you want to display.

The following are supported cases that can be included in visibleFields:

@objc public enum DropInViewVisibleFields: Int {
    case pan = 0
    case expiryDate
    case cvv3
    case cvv4

    public static var `default`: [DropInViewVisibleFields] {
        [
            .pan,
            .expiryDate,
            .cvv3
        ]
    }
}

Include custom components to the Drop-In View Controller

This creates a view that conforms to the DropInViewProtocol if you want override the whole view.

If you want to add any custom view e.g. toggle button used for saving card details, billing & delivery views, then conform to the DropInView and add it to the stack hierarchy:

public override func setupViewHierarchy() {
  super.setupViewHierarchy()
  stackView.insertArrangedSubview(saveCardOptionView, at: max(stackView.arrangedSubviews.count - 1, 0))
}

Customising error messages

You can specify alternative wording for error messages displayed to the customer in your app, overriding the default text displayed.

To specify custom wording, you will need to specify LocalizableKeys in the SDK initialisation. The following example shows how to provide custom wording for the input error keys, in the English language:

TrustPayments.instance.configure(
  username: "username", gateway: .eu, environment: .staging, locale: Locale(identifier: "en_GB"), translationsForOverride: [
    Locale(identifier: "en_GB"): [
      LocalizableKeys.Errors.general.key: "Something went wrong",
      LocalizableKeys.CardNumberInputView.error.key: "Invalid Pan",
      LocalizableKeys.CardNumberInputView.emptyError.key: "Pan input empty",
      LocalizableKeys.CVVInputView.error.key: "Security Code error",
      LocalizableKeys.CVVInputView.emptyError.key: "Security Code empty",
      LocalizableKeys.ExpiryDateInputView.error.key: "Expiration date error",
      LocalizableKeys.ExpiryDateInputView.emptyError.key: "Expiration date empty"
    ]
  ]
)

List of all LocalizableKeys (including default text)

ublic enum LocalizableKeys {
    // MARK: Pay Button
    public enum PayButton: LocalizableKey {
        case title
        case ataPayByBank
    }

    // MARK: DropIn View Controller
    public enum DropInViewController: LocalizableKey {
        case successfulPayment
    }

    // MARK: Errors
    public enum Errors: LocalizableKey {
        case general
    }

    // MARK: CardNumberInputView
    public enum CardNumberInputView: LocalizableKey {
        case title
        case placeholder
        case error
        case emptyError
    }

    // MARK: CVVInputView
    public enum CVVInputView: LocalizableKey {
        case title
        case placeholder3
        case placeholder4
        case error
        case emptyError
    }

    // MARK: ExpiryDateInputView
    public enum ExpiryDateInputView: LocalizableKey {
        case title
        case placeholder
        case error
        case emptyError
    }

    // MARK: ExpiryDatePickerView
    public enum ExpiryDatePickerView: LocalizableKey {
        case month
        case year
    }

    // MARK: AddCardButton
    public enum AddCardButton: LocalizableKey {
        case title
    }

    // MARK: Alerts
    public enum Alerts: LocalizableKey {
        case processing
    }

    // MARK: Challenge view
    public enum ChallengeView: LocalizableKey {
        case headerTitle
        case headerCancelTitle
    }
}

Where next?