Android – Using the JPPaymentCardFragment 2017-05-16T13:24:39+00:00

Android – Using the JPPaymentCardFragment

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

PLEASE NOTE:  JPPaymentCardFragment is not instantiated directly. Instead use one of it’s subclasses JPPaymentCardHorizontalFragment or JPPaymentCardVerticalFragment.

JPPaymentCardFragment can also be directly loaded with payment card data, with this data being validated by JPPaymentCardFragment. 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.

JPPaymentCardFragment 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, JPPaymentCardFragment can be “asked” whether is contains valid and complete data.

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

JPPaymentCardFragment 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 JPPaymentCardFragment 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 JPPaymentCardFragmentListener interface.

JPPaymentCardFragment 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 JPPaymentCardFragment is to add an instance of JPPaymentCardFragment to your view hierarchy (either statically through an XML layout file or dynamically through the Fragment Manager), setup a listener object and respond to changes in this field by confirming whether the JPPaymentCardFragment contains valid data.

If JPPaymentCardFragment 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):

XML Layout snippet from R.layout.activity_card_only:

<fragment xmlns:android=http://schemas.android.com/apk/res/android
    android:id=“@+id/jpPaymentCardVerticalFragment”
    android:layout_width=“match_parent”
    android:layout_height=“wrap_content”
    android:layout_marginLeft=“@dimen/double_standard_horizontal_margin”
    android:layout_marginRight=“@dimen/double_standard_horizontal_margin”
    android:name=“jetpay.co.uk.jetpay.JPPaymentCardVerticalFragment” />

Code snippet:

public class CardOnlyActivity extends Activity implements JPPaymentCardFragment.JPPaymentCardFragmentListener {

   @Override
   protected void onCreate( Bundle savedInstanceState ) {
      super.onCreate(savedInstanceState);
      setContentView( R.layout.activity_card_only );

      JPPaymentCardVerticalFragment vf = (JPPaymentCardVerticalFragment) getFragmentManager().findFragmentById( R.id.jpPaymentCardVerticalFragment );
      vf.setListener( this );
      vf.setTextSize( 15.0f );
      vf.setDefaultTextColor( Color.WHITE );
      vf.setTypeFace( Typeface.create( “sans-serif-light”, Typeface.NORMAL );
   }

   /* JPPaymentCardFragmentListener interface methods */
   public void paymentCardFragmentDidChange( JPPaymentCardFragment fragment ) {
      if ( fragment.isValid() ) {
         /* valid card details have been collected - load the card from the fragment and into the  AND enable a “pay” button.. */

      JPPaymentContext.sharedContext.setPaymentCard( fragment.card );

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

      displayMyPayButton();
   }

   public void paymentCardFragmentDidBeginEditingNumber( JPPaymentCardFragment fragment ) {
   }

   public void paymentCardFragmentDidEndEditingNumber( JPPaymentCardFragment fragment ) {
   }

   public void paymentCardFragmentDidBeginEditingCVC( JPPaymentCardFragment fragment ) {
   }

   public void paymentCardFragmentDidEndEditingCVC( JPPaymentCardFragment fragment ) {
   }

   public void paymentCardFragmentDidBeginEditingExpiration( JPPaymentCardFragment fragment ) {
   }

   public void paymentCardFragmentDidEndEditingExpiration( JPPaymentCardFragment fragment ) {
   }


}

Anatomy

JPPaymentCardFragment comes in two flavours – horizontal and vertical.

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

JPPaymentCardVerticalFragment 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 JPPaymentCardFragment’s main view is defined by it’s frame. There are two direct subviews – the subtitlesLayout and the fieldsLayout. The subtitlesLayout and fieldsLayout exist to support layout, padding and labelling options.

In the diagram (Diagram 1) below, a JPPaymentCardHorizontalFragment is displayed with it’s default settings.

Diagram 1

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

Diagram 2

The subtitlesLayout contains a subtitlesContentLayout which contains optional subtitles for the control (JPPaymentCardHorizontalFragment only).

Similarly, the fieldsLayout contains a fieldsContentlayout which contains the payment card data entry fields. By default, both subtitlesContentLayout and fieldsContentLayout occupy the same frames as their parents, but can be inset using the subtitlesContentPaddingInsets and fieldsContentPaddingInsets properties respectively. The diagram below (Diagram 3) shows these content views with small insets (10dp 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 subtitlesContentLayout and fieldsContentLayout areas.

Diagram 4

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

Customisation

Text Alignment

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

Particular to JPPaymentCardVerticalFragment 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 (JPPaymentCardHorizontalFragment does not support subtitles).

Fonts and Text

setTypeface() and setTextSize() sets the font details for all payment card input fields.

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

When JPPaymentCardFragment 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 setNumberHint(), setExpirationHint() and setCvcHint() properties.