Using the JPPaymentCardField 2017-05-16T12:22:17+00:00

iOS – Using the JPPaymentCardField 

JPPaymentCardField provides a UIControl for collecting payment card information from the user – notably, the payment card number, the expiry date and the CVC.

PLEASE NOTE:  JPPaymentCardField is not instantiated directly. Instead use one of it’s subclasses JPPaymentCardHorizontalField or JPPaymentCardVerticalField.

JPPaymentCardField can also be directly loaded with payment card data, with this data being validated by JPPaymentCardField. An example use case would be when you have an external database of customer payment cards you wish to use for making payments to the JetPay gateway.

JPPaymentCardField validates the card number against a number of known card number formats. Validation is performed as the user is typing the number, expiry date or CVC code. Instant feedback is provided to the user by the use of an “error” colour applied to this field data. From a programmatic point of view, JPPaymentCardField can be “asked” whether is contains valid and complete data.

JPPaymentCardField also recognises the card issuer for the card number being entered by displaying an appropriate brand image on the left hand side of JPPaymentCardField.

JPPaymentCardField tightly controls the navigation between the data entry fields. Firstly, it is expected the user will enter the card number and when (and only if) this number is recognised as valid will JPPaymentCardField automatically jump to the expiry date field. Again, the CVC fields can only be edited once the user has entered a valid expiry date.

Feedback on state and behaviour is provided by the JPPaymentCardFieldDelegate protocol.

JPPaymentCardField and it’s subclasses are IBDesignable.

JPPaymentCardField can be customised with regards to colours, fonts, borders, background colours, etc.

For more details, please see the SDK Reference.

Typical Use Case

The typical use case for JPPaymentCardField is to add an instance of JPPaymentCardField to your view hierarchy, setup a delegate object and respond to changes in this field by confirming whether the JPPaymentCardField contains valid data. If JPPaymentCardField contains a valid payment card, you are finished with this stage of the payment process.

The snippet below illustrates how to add JPPaymentCardField to your view hierarchy and respond when the JPPaymentCardField has changed it’s contents (through the JPPaymentCardFieldDelegate protocol):

func loadMyPaymentField() -> func loadMyPaymentField() -> Void {

	let paymentControl = JPPaymentCardHorizontalField( frame: CGRectMake(x: 10.0, y: 0.0, width: 300.0, height: 64.0 )
	paymentControl.delegate = self

	/* customise: blue background, white text, system font of size 26 */
	paymentControl.backgroundColor = UIColor.blueColor()
	paymentControl.textColor = UIColor.whiteColor()
	paymentControl.font = UIFont.systemFontOfSize(26.0)

	/* add to the view hierarchy */
	self.view.addSubview( paymentControl )
}

/* JPPaymentCardFieldDelegate methods */
func paymentCardFieldDidChange(textField: JPPaymentCardField) -> Void {

	/* text field contents have changed - are the card details valid? */
	if textField.isValid() {

		/* valid card details have been collected - load the card from the textField and into the  AND enable a “pay” button.. */

		JPPaymentContext.sharedContext.setPaymentCard( textField.card )

		/* NOTE: the  will also require other data such as payment amount and transactionId */

		displayMyPayButton()
	}
}

- (void)loadMyPaymentField {

    JPPaymentCardHorizontalField *paymentControl = [[JPPaymentCardHorizontalField alloc] initWithFrame:CGRectMake(10.0, 0.0, 300.0, 64.0)];
    paymentControl.delegate = self;
    
    /* customise: blue background, white text, system font of size 26 */
    paymentControl.backgroundColor = [UIColor blueColor];
    paymentControl.textColor = [UIColor whiteColor];
    paymentControl.font = [UIFont systemFontOfSize:26.0];
    
    /* add to the view hierarchy */
    [self.view addSubview:paymentControl];
}

/* JPPaymentCardFieldDelegate methods */
- (void)paymentCardFieldDidChange:(JPPaymentCardField *)textField {

    /* text field contents have changed - are the card details valid? */
    if ([textField isValid]) {
        
        /* valid card details have been collected - load the card from the text field into the shared payment context and enable a "pay" button.. */
        [[JPPaymentContext sharedContext] setPaymentCard:[textField card]];
        
        /* NOTE: we will also require other data such as payment amount and transactionId */
        
        [self displayMyPayButton];
    }
}

Anatomy

JPPaymentCardField comes in two flavours – horizontal and vertical.

JPPaymentCardHorizontalField implements the horizontal layout where the payment card fields are laid out from left to right.

JPPaymentCardVerticalField implements the vertical layout where the payment card fields are laid out from top to bottom.

Whatever layout is used, the anatomy is the same. The JPPaymentCardField’s main view is defined by it’s frame. There are two direct subviews – the subtitlesView and the fieldsView. The subtitlesView and fieldsView exist to support layout, padding and labelling options. In the diagram (Diagram 1) below, a JPPaymentCardHorizontalField is displayed with it’s default settings.

Diagram 1

In Diagram 2, the subtitlesView background colour is light grey and the fieldsView background colour is light blue. As can be seen, the total area of the control is occupied by these views.

Diagram 2

The subtitlesView contains a subtitlesContentView which contains optional subtitles for the control. Similarly, the fieldsView contains a fieldsContentView which contains the payment card data entry fields. By default, both subtitlesContentView and fieldsContentView occupy the same frames as their parents, but can be inset using the subtitlesContentInsets and fieldsContentInsets properties respectively. The diagram below (Diagram 3) shows these content views with small insets (5 logical points) with a green background.

Diagram 3

When the background for the data fields in set to a yellow in Diagram 4 (below), what can now be seen is how these data fields fill the subtitlesContentView and fieldsContentView areas.

Diagram 4

From the above discussion, it can be seen that there are a number of options configuring JPPaymentCardField to fit in with your own user interface with regards to margins and padding.

Customisation

Borders

JPPaymentCardField has configurable properties for borders.

Using Diagram 4 (above) from the Anatomy section, Diagram 5 illustrates the addition of two black borders. The first border is for the control itself and is 3 logical points wide. The second border is applied to the payment card input fields and is 1 logical point wide.

Diagram 5

JPPaymentCardField also supports rounded borders in the form of cornerRadius properties.

Dynamic Field Width

JPPaymentCardField and it’s subclasses, by default, dynamically size the payment card fields to the length of data required and the current font property setting. For example, the payment card number is sized for 16 characters plus 3 spaces for card number formatting. If the font property point size increases, then so does the dynamic width of the field.

However, the dynamicFieldWidth boolean property can be set to false – i.e. dynamic field width sizes disabled. In this case, JPPaymentCardVerticalField sizes each of the payment card fields to be the same width. However, in the case of JPPaymentCardHorizontalField still dynamically sizes the fields as therein rarely space in a horizontal dimension to make all fields the same width.

Field Prefix Spacing

JPPaymentCardField and it’s subclasses, by default, add no spacing between the left hand side of the payment card input fields and the input data itself. The nature of the iOS UI element UITextField is that sometimes the input text appears too close to the left hand side of the UITextField. To solve this problem, JPPaymentCardField has a property called spacePrefixPaddingForInputFields which can be set to the logical number of points to insert between the left hand side of the payment card input fields and the input data for those fields.

Text Alignment

JPPaymentCardField and it’s subclasses, by default, align field input text on the left hand side. The fieldTextAlignment property can be changed to to either justify text centrally or on the right hand side.

Particular to JPPaymentCardVerticalField only, the subtitles used to label payment card input fields can also be aligned either on the left hand side, centrally or the right hand side. By default, subtitles are aligned on the left hand side (JPPaymentCardHorizontalField does not support subtitles).

Fonts and Text

The font property sets the font for all payment card input fields.

The textColor property sets the text colour for all payment card input fields.

When JPPaymentCardField recognises a payment card input field to contain incomplete or invalid data, that field’s text is displayed in the colour specified by the textErrorColor property.

Payment card input field placeholder values – hints displayed before the user has entered any data – are configurable through the numberPlaceholder, expirationPlaceholder and cvcPlaceholder properties.