-- Version: 14-8-17 --
© 2017 Jetpay Solutions Ltd.
All worldwide rights reserved.

IMPORTANT

@August 10th 2017 we currently support:
> Android Studio 2.3.2 +
> Android API Level 21



JetPay SDK Full Android Reference

Welcome to JetPay Solution's Software Development Kit Reference Guide for Android. Here you will find all the necessary DEFINITIONS and EXPLANATIONS of key terms amd conditions to assist you in successfully integrating JetPay's payment processing software into your Android applications. Here's a summary of what's inside...

box icon

Controller Objects

A controller object acts as a coordinator or as an intermediary between one or more view objects and one or more model objects

box icon

Enums/Types

Enumeration defines a common type for a group of related values and enables you to work with those values in a type-safe way within your code

box icon

Model Objects

Object types that contain the data of the application, providing access to that data, and implementing logic to manipulate & display the data

box icon

Interfaces

Interfaces form the reference type(s) in Java. Similar to a class - its a collection of abstract methods containing behaviours that a class implements

box icon

Singleton Objects

A Singleton is an object which is instantiated exactly once. Only one copy of this object exists and the state is shared and reachable by any other object

box icon

View Objects

A view draws a visual representation of itself and presents a surface that responds to touches and input from devices - essential to your Android app.

Controller Objects:

JPAddCardActivity

Overview

JPAddCardActivity is a subclass of Activity and provides a full-screen activity for collecting customer details. These details are the customer’s payment card details and the customer’s address (optional).

Feedback on behaviour and state for JPAddCardActivity is provided through the JPAddCardActivityListener interface and, if JPAddCardActivity is started using startActivityForResult, through onActivityResult.

Customising the JPAddCardActivity is done by passing intent extras when starting the activity.

The process flow is to display the controller and collect the necessary information. The user can either [ Cancel ] or [ Save ]. Selection of [ Save ] will save the details to the shared JPPaymentContext object. Note, however, that JPAddCardActivity will not enable the [ Save ] function unless all entered data is recognised as complete and valid.


Symbols

Creating a JPAddCardActivity

Intent intent = new Intent( this, jetpay.co.uk.jetpay.JPAddCardActivity.class );

Creates an explicit intent representing JPAddCardActivity.


Themes and Customisation

Customising the JPAddCardActivity is done through the following setters and Intent Extras (when starting the JPAddCardActivity):

public void setTheme( JPTheme theme ) 
putExtra( JP_THEME_EXTRA_KEY, theme );

Defaults to the globalTheme in the shared JPConfiguration object.

public void setCellContentInsets( JPEdgeInsets cellContentInsets )
putExtra( JP_CELL_CONTENT_INSETS_EXTRA_KEY, cellContentInsets );
Defaults to 0. Sets the insets for the payment card and address cells displayed in the JPAddCardActivity

public void setHeightForSectionHeader( int heightForSectionHeader )
putExtra( JP_HEIGHT_FOR_SECTION_HEADER_EXTRA_KEY, heightForSectionHeader);
Defaults to wrap content. Sets the height section headers in the JPAddCardActivity.

public void setSubtitleTextGravity( String subtitleTextGravity )
putExtra( JP_CELL_SUBTITLE_TEXT_GRAVITY_EXTRA_KEY, subtitleTextGravity );
Defaults to left-aligned. Sets the subtitle text gravity for address cells.

public void setFieldTextGravity( String fieldTextGravity )
putExtra( JP_CELL_FIELD_TEXT_GRAVITY_EXTRA_KEY, fieldTextGravity );
Defaults to left-aligned. Sets the data entry field gravity for address and payment card cells.


Relationships

Inherits from: Activity
Implements: JPThemeProtocol, JPPaymentCardFragmentListener, JPAddressViewModelListener


Enums and Types:


Object Definitions & Quicklinks
  • Expand all
  • Collapse all
  • Enums and Types ...containing the data of the app, making data accessible & implementing logic to manipulate & display the data
    • JPEnvironmentType ...defines the type of JetPay environment.
    • JPErrorDomain ...captures error conditions in the SDK in an JPError object. This object contains a domain where the error occurred.
    • JPPaymentContextError ...is an enum type which explicitly states the validation state of the JPPaymentContext singleton object.
    • JPRequiredAddressFields ...identifies required address fields. Address fields are required/not required depending upon whether a merchant is AVS registered.

 

JPEnvironmentType

Overview

JPEnvironmentType is an enum type that defines the type of JetPay environment. Your app uses this type to configure JPConfiguration appropriately.


Symbols

.Test
Specifies the Jetpay test environment.      

.Production
Specifies the Jetpay production environment.      


Relationships

Inherits from: Nothing
Implements: Nothing


 

JPErrorDomain

Overview

JPErrorDomain identifies the error domain where an error was first identified. JPErrorDomain is part of an JPError object which encapsulates an error captured by the SDK.

Supported domains are JPNetworkTransport, JPNetworkXMLClient, JPService, JPPaymentContext and JPClient.

For example, JPNetworkXMLClient will detect malformed XML packets while JPNetworkTransport will detect low-level network connectivity issues.

Symbols

.JPNetworkTransport
Errors associated with low-level network operations.      

.JPNetworkXMLClient
Errors associated with malformed transaction requests and XML packets.      

.JPService
Errors associated with high-level transaction requests.      

.JPPaymentContext
Errors associated with invalid or incomplete context data.      

.JPClient
High-level SDK operations.      

Relationships

Inherits from: Nothing
Implements: Nothing


 

JPPaymentContextError

Overview

JPPaymentContextError is an enum type which explicitly states the validation state of the JPPaymentContext singleton object.

Your code and SDK objects combine to add payment data to the JPPaymentContext. Once this has been done, the JPPaymentContext can be requested to post a transaction request. JPPaymentContext will only post this request if the data it contains is valid and complete.

Symbols

.DataIsCompleteAndValid
JPPaymentContext contains a complete and valid set of data.      

.TransactionPostedAwaitingResponse
JPPaymentContext has posted a transaction request to the Jetpay backend but has not yet received a response.      

.InvalidAddressForAVS
JPPaymentContext contains an incomplete or invalid billing card address for AVS enabled transactions.      

.InvalidCustomerData
JPPaymentContext contains incomplete or invalid customer data.      

.InvalidPaymentCardData
JPPaymentContext contains incomplete or invalid payment card data.      

.ValidPaymentCardButUnsupportedBrand
JPPaymentContext contains a valid payment card BUT the Jetpay gateway does not support processing with this card brand.      

.InvalidPaymentAmountData
JPPaymentContext contains incomplete or invalid payment amount data.      

.InvalidTransactionIdData
JPPaymentContext contains a transactionId with invalid characters. Only characters ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’ and ‘-‘ are allowed.      

.InvalidTransactionIdDataLength
JPPaymentContext contains a transactionId which is not the required 18 characters long.      


See also: JPPaymentContext


Relationships

Inherits from: Nothing
Implements: Nothing


 

JPRequiredAddressFields

Overview

JPRequiredAddressFields is an enum type that identifies required address fields. Address fields are required or not required depending upon whether a merchant is AVS registered.

JPRequiredAddressFields is used in combination with an instance of JPAddress and JPConfiguration. JPAddress can validate itself, BUT this validation is dependant upon what address fields are required.

Typically, if the merchant is AVS registered, set the JPRequiredAddressFields value on the JPConfiguration shared object. When a JPAddCardActivity is initialised, the value from JPConfiguration is used to create the JPAddressViewModel object which supports the JPAddCardActivity. JPAddressViewModel makes use of JPRequiredAddressFields to create the necessary data entry cells for display by the JPAddCardActivity.


Symbols

.None
No address is required. Use when the merchant is not AVS registered.      

.Zip
A JPAddress instance considered valid by the SDK requires a zip code only.      

.Full
A JPAddress instance considered valid by the SDK requires a full address.      

Model Objects


Object Definitions & Quicklinks
  • Expand all
  • Collapse all
  • Model Objects ...containing the data of the app, making data accessible & implementing logic to manipulate & display the data
    • JPActionCode ...responses from the Jetpay backend contain an action code, encapsulated in JPActionCode. The action code encapsulated is defined, and therefore, specific to the card issuer.
    • JPAddress ...encapsulates a customer’s address; hold's a billing address for a particular payment card.
    • JPBaseResponse ...is an abstract class extended by non-abstract response classes.
    • JPCardParams ...encapsulates payment card details
    • JPCustomer ...encapsulates a customer’s basic identification details
    • JPEdgeInsets ...wrapper class used to represent top, left, bottom and right margin values in dp.
    • JPError ...contains a domain where the error occurred and a String representing the nature of the error.
    • JPPaymentContext ...a singleton object used to collect all required information required to generate a transaction payment request.
    • JPTheme ...encapsulates style attributes together to produce a visual theme used by SDK visual objects.
    • JPTransactionResponse ...encapsulates a response from the Jetpay backend for a given transaction.

 

JPActionCode

Overview

Responses from the Jetpay backend contain an action code, encapsulated in JPActionCode. The action code encapsulated is defined, and therefore, specific to the card issuer.

An action code of 0 represents a successful response, for all card issuers. Any other response represents an error of some kind.

JPActionCode not only encapsulates this value, but given the card issuer (card brand), can translate this encapsulated action code into the string error message as defined in the Jetpay XML documentation.

A JPActionCode is created while parsing Jetpay backend responses and added into a JPTransactionResponse object. Note, however, that this JPActionCode instance is updated with the card brand value by JPPaymentContext.

Symbols

Accessing Action Code Details

public String getValue()
The string representation of the Action Code. For example, “000” represents a successful response.

public JPCardBrand getCardBrand()
The card brand used to make the original transaction request. uses this value to map the action code to an appropriate string error message when requested.

public boolean isApproved()
Returns true if JPActionCode represents an approved transaction, false otherwise.

public boolean isValid()
Returns true if JPActionCode appears to be valid, false otherwise.

public String description()
Returns the same as getValue()

public String detailedDescription()
Returns a string description representing the action code. For example, “No checking account” for a Visa action code of “053”. These string descriptions are documented in the JetPay Host XML documentation.

Relationships

Inherits from: Nothing
Implements: JPSelfValidating


 

JPAddress

Overview

JPAddress encapsulates a customer’s address. Specifically, JPAddress is used to hold a billing address for a particular payment card.

Because JPAddress represents a billing address for a payment card, the validation of JPAddress is variable. That is, the JPAddress may, or may not, be required to make a valid payment transaction. JPAddress therefore, does not implement JPSelfValidating. Instead, JPAddress, when queried with a JPRequiredAddressFields value, can tell you whether it is valid or not.

Symbols

Creating a JPAddress

JPAddress is created as a new object and you set each attribute on this object as required.

JPAddress myAddress = JPAddress();
myAddress.setName(“John Appleseed”);
..

Determining Address Validation

public boolean isValid(JPRequiredAddressFields requiredAddressFields)
Given the required address fields, determines whether the address is valid.

Setting Address Properties

public string getName()
Returns the billing address name.

public void setName( StringName )
Sets the billing address name.

public String getLine1()
Returns line 1 of the address

public void setLine1( String line1 )
Sets line1 of the address.

public String getLine2()
Returns line2 of the address.

public void setLine2( String line2 )
Sets line2 of the address. Line2 is considered optional in a valid postal address.

public String getCity()
Returns the city of the address.

public void setCity( String city )
Sets the address city.

public String getState()
Returns the state of the address.

public void setState( String state )
Sets the state for the address.

public String getPostalCode()
Returns the postal code of the address.

public void setPostalCode( String postalCode )
Sets the postal code of the address.

public String getCountry()
Returns the country of the address.

public void setCountry( String country )
Sets the country of the address.

public String getPhone()
Returns the phone of the address.

public void setPhone( String phone )
Sets the phone of the address. Phone is considered optional in a valid postal address.

public String getEmail()
Returns the email of the address.

public void setEmail( String email )
Sets the email of the address. Email is considered optional in a valid postal address.

Relationships

Inherits from: Nothing
Implements: Nothing


 

JPBaseResponse

Overview

JPBaseResponse is an abstract class extended by non-abstract response classes.

Symbols

Accessing Properties

See response classes which extend this abstract class for details.

Relationships

Inherits from: Nothing
Implements: Nothing


 

JPCardParams

Overview

JPCardParams encapsulates payment card details.

An instance of JPCardParams encapsulates details for a single payment card. These details include payment card number, expiry month, expiry year and CVC. In addition, payment card holder’s name and address.

Typically, an instance of JPCardParams is either used to pre-load SDK card entry UI elements (such as JPPaymentCardFragment) or to unload these same SDK UI elements after the user has entered the card details.

JPCardParams implements JPSelfValidating which is particularly important for validation when pre-loading JPCardParams from data external to the SDK.

Symbols

Creating JPCardParams

public JPCardParams( String number, int expireMonth, int expireYear, String cvc )
Creates an instance of JPCardParams with the given parameter values.


Accessing the Card Number

public String getCardNumber()
Returns the payment card number.

public void setCardNumber(String cardNumber)
Sets the card number.

public String getCardNumberFormattedForBrand()
The payment card number formatted with appropriate spacing specific to card brand.

public String getCardNumberWithFormatting()
Returns the same as getCardNumberFormattedForBrand()

public String getCardNumberWithoutFormatting()
Returns the card number without formatting characters.


Accessing Expiry Details

public int getExpireMonth()
The expiry month as an integer.

public void setExpireMonth( int expireMonth )
Set the expire month.

public String getExpirationMonth()
The expiry month as a 2-digit string.

public int getExpireYear()
The expiry year as an integer.

public void setExpireYear( int expireYear )
Set the expire year.

public String getExpirationYear()
The expiry year as a 2-digit string.


Accessing the Cardholder's Name

public String getName()
Returns the payment cardholder’s name.

public void setName( String name )
Set the payment card’s name.


Accessing the CVC

public String getCvc()
Returns the payment card’s CVC.

public void setCvc( String cvc )
Sets the payment card’s CVC.


Accessing the Cardholder's Address

public JPAddress getAddress()
Returns the cardholder’s billing address.

public void setAddress( JPAddress address )
Set the cardholder’s billing address.


Accessing Brand Images

public int imageForBrand()
Returns the resourceId for a small image representing the card brand.

public int largeImageForBrand()
Returns the resourceId for a large image representing the card brand.

Confirming Validation State

public boolean isValid()
true if the JPCardParams instance is considered valid, false otherwise.


Relationships

Inherits from: Nothing
Implements: JPSelfValidating



 

JPCustomer

Overview

JPCustomer encapsulates a customer’s basic identification details. NOTE: JPCustomer is for your benefit and used by the SDK to tie transaction data back to your own own customer data structures.

JPCustomer has been provided for your own reference and the SDK does not make explicit use of this data. For example, if you retrieve customer details from your own data structures (external to this SDK), you can tie SDK data to these stores by adding a JPCustomer instance to the JPPaymentContext.

Symbols

Creating a JPCustomer

JPCustomer( String customerID, String firstName, String secondName )
Creates a JPCustomer instance.

Relationships

Inherits from: Nothing
Implements: Nothing



 

JPEdgeInsets

Overview

Wrapper class used to represent top, left, bottom and right margin values in dp.

Typically, an instance of this class is used to pass parameters to an SDK UI object which assists in customising that object.

This class is Parcelable so that it can be passed an an intent extra.

Symbols

Creating a JPEdgeInset

public JPEdgeInsets( int top, int left, int bottom, int right )
Create a new JPEdgeInset with the given parameters.


Accessing Properties

public int getTop()
Return the top margin value.

public void setTop(int top)
Set the top margin value.

public int getLeft()
Return the left margin value.

public void setLeft(int left)
Set the left margin value.

public int getBottom()
Return the bottom margin value.

public void setBottom(int bottom)
Set the bottom margin value.

public int getRight()
Return the right margin value.

public void setRight(int right)
Set the right margin value.


Relationships

Inherits from: Nothing
Implements: Parcelable



 

JPError

Overview

Error conditions are captured by the SDK in an JPError object. This object contains a domain where the error occurred and a string representing the nature of the error.

For details on the error domains, see the JPErrorDomain enum.

Most errors encountered will be due to network connectivity issues.

Symbols

public JPErrorDomain getDomain()
Returns the error domain that generated the error.

public String getErrorMessage()
Returns the String describing the error.


Relationships

Inherits from: Nothing
Implements: Nothing



JPPaymentContext

Overview

The JPPaymentContext singleton object encapsulates all information required to make a transaction payment request to the Jetpay backend.

Effectively, a single transaction payment request is regarded as the context. This context holds all data required to make a transaction request - for example, the payment card, the context state which identifies whether this data is valid or incomplete, whether the context has POSTed a transaction request to the Jetpay backend, and if so what the returned results are (either an JPError or a JPTransactionResponse).

SDK objects read and write to the JPPaymentContext, as does your app code. Together, your app and the SDK collect and store all required data in the JPPaymentContext. Examples of data are payment amount, payment card and customer details.

NOTE: Some details added to the JPPaymentContext are not used by the SDK. Instead, these details are held on your behalf for your reference only. Currently, these details are the customer details. When the result of posting a transaction to the Jetpay backend, whether a success or failure, you can retrieve these values from JPPaymentContext and use them in referencing back to data in your own data structures.

NOTE: Although the transactionId is determined by you - and presumably is used to cross-reference information in your own databases, this transactionId IS sent to the Jetpay backend and hence obeys certain formatting rules. These rules stipulate a fixed 18 character length containing only the characters ‘a’ through ‘z’, ‘A’ through ‘Z’, ‘0’ through ‘9’ and ‘-‘.

Once all data has been collected, you can instruct the JPPaymentContext to submit a payment transaction to the Jetpay backend through the post transaction methods. Currently, there are two - postSaleTransaction and verifyCard (which uses an AUTHONLY transaction to verify the validity of a card with it’s issuer without charging the card). Note, however, that JPPaymentContext will NOT submit incomplete or invalid data. JPPaymentContext implements the JPSelfValidating interface and so can determine itself whether a valid and complete transaction payment request can be made.

To capture feedback results when POSTing a transaction, implement the JPPaymentContextListener interface. See JPPaymentContextListener for more details.

JPPaymentContext regards itself as complete and valid if the payment amount, payment card and transactionId details are valid.

Symbols

Accessing JPPaymentContext

public static final JPPaymentContext sharedContext
Return the singleton JPPaymentContext.

public void clearContext()
Clears the JPPaymentContext, ready for a new transaction request.

Accessing a Customer

public void setCustomer( JPCustomer customer )
Set the customer on JPPaymentContext. Note, the Jetpay SDK makes no use of the JPCustomer data - it is for your reference only.

public JPCustomer getCustomer()
Returns the JPCustomer object held in JPPaymentContext.

Accessing the Payment Transaction Amount

public void setPaymentAmount( double paymentAmount )
Sets the payment amount on the JPPaymentContext.

public double getPaymentAmount()
Returns in payment amount stored in JPPaymentContext.

Accessing the Payment Card

public void setPaymentCard( JPCardParams paymentCard )
Set the given payment card on the JPPaymentContext.

public JPCardParams getPaymentCard()
Gets the payment card stored in JPPaymentContext.

Accessing the TransactionId

public void setTransactionId( String transactionId )
Sets the given transactionId on the JPPaymentContext.
The transactionIs must by 18 characters in length and contain only the characters ‘a’ through ‘z’, ‘A’ through ‘Z’, ‘0’ through ‘9’ and ‘-‘.

public String getTransactionId()
Gets the transactionId stored in JPPaymentContext.

Posting a Transaction Payment

public void setListener( JPPaymentContextListener listener )
Sets the listener for the JPPaymentContext.

public void postSaleTransaction( )
If JPPaymentContext contains the required data for a SALE transaction and this data is valid, JPPaymentContext creates
a JPTransaction object and passes this to JPService for processing at the JetPay backend.

public void verifyCard( )
If JPPaymentContext contains the required data for a AUTHONLY transaction and this data is valid, JPPaymentContext creates a
JPTransaction object and passes this to JPService for processing at the JetPay backend.
NOTE: A payment amount of 0.0 is ALWAYS submitted regardless of the value of the payment amount in JPPaymentContext.
verifyCard ONLY verifies the payment card with the card issuer - the card is not charged.

Context Validation

public boolean isValid()
Identifies whether the JPPaymentContext is valid. That is, the data it contains is valid and complete.

public JPPaymentContextError getCurrentState()
Returns the explicit validation state of JPPaymentContext. See the JPPaymentContextError enum for details.

public JPError getCurrentError()
Contains the JPError object returned (nil if successful) for the most recently POSTed transaction request.

public JPTransactionResponse getCurrentTransactionResponse()
Contains the JPTransactionResponse object returned (nil if an error occurred) for the most recently POSTed transaction request.


Relationships

Inherits from: Nothing
Implements: JPSelfValidating, JPServiceListener



 

JPTheme

Overview

JPTheme encapsulates a number of style attributes together to produce a visual theme that can be used by SDK visual objects.

Currently, background colour, border colour, text colour, error text colour and fonts are supported. For each of these attributes, there are four levels - primary, secondary, tertiary and quaternary.

These four “levels” are applied in an intuitive way depending on attribute. For example, the primary font is the largest, while the quaternary font is the smallest. Similarly, the primary background colour is applied to the highest view in the hierarchy (depending on context), while the quaternary background colour is applied to the lowest view in the hierarchy.

Some attributes are not used by the SDK, but are included for future use. For example, the SDK makes use of the primary error text colour but not the secondary, tertiary or quaternary ones.

Symbols

Creating a JPTheme

JPTheme is created as a new object and you set each attribute on this object as required.

JPTheme myTheme = new JPTheme();


Accessing the Default Theme

The defaultTheme class method returns a default theme.

JPTheme defaultTheme = JPTheme.defaultTheme();


Accessing Background Colours

public int getPrimaryBackgroundColor()
Return the background colour used for the highest view in the hierarchy.

public void setPrimaryBackgroundColor(int primaryBackgroundColor)
Set the background colour used for the highest view in the hierarchy.

public int getSecondaryBackgroundColor()
Return the background colour used in a 2nd-level view.

public void setSecondaryBackgroundColor(int secondaryBackgroundColor)
Set the background colour used in a 2nd-level view.

public int getTertiaryBackgroundColor()
Return the background colour used in a 3rd-level view.

public void setTertiaryBackgroundColor(int tertiaryBackgroundColor)
Set the background colour used in a 3rd-level view.

public int getQuaternaryBackgroundColor()
Return the background colour used in a 4th-level view.

public void setQuaternaryBackgroundColor(int quaternaryBackgroundColor)
Set the background colour used in a 4th-level view.


Accessing Border Colours

public int getPrimaryBorderColor()
Return the border colour used for the highest view in the hierarchy.

public void setPrimaryBorderColor(int primaryBorderColor)
Set the border colour used for the highest view in the hierarchy.

public int getSecondaryBorderColor()
Return the border colour used in a 2nd-level view.

public void setSecondaryBorderColor(int secondaryBorderColor)
Set the border colour used in a 2nd-level view.

public int getTertiaryBorderColor()
Return the border colour used in a 3rd-level view.

public void setTertiaryBorderColor(int tertiaryBorderColor)
Set the border colour used in a 3rd-level view.

public int getQuaternaryBorderColor()
Return the border colour used in a 4th-level view.

public void setQuaternaryBorderColor(int quaternaryBorderColor)
Set the border colour used in a 4th-level view.


Accessing Text Colours

public int getPrimaryTextColor()
Return the text colour used for the largest text.

public void setPrimaryTextColor(int primaryTextColor)
Set the text colour used for the largest text.

public int getSecondaryTextColor()
Return the text colour used in a 2nd-largest text.

public void setSecondaryTextColor(int secondaryTextColor)
Set the text colour used in a 2nd-largest text.

public int getTertiaryTextColor()
Return the text colour used in a 3rd-largest text.

public void setTertiaryTextColor(int tertiaryTextColor)
Set the text colour used in a 3rd-largest text.

public int getQuaternaryTextColor()
Return the text colour used in a smallest text.

public void setQuaternaryTextColor(int quaternaryTextColor)
Set the text colour used in a smallest text.


Accessing Error Text Colours

public int getPrimaryErrorTextColor()
Return the error text colour used for the largest text.

public void setPrimaryErrorTextColor(int primaryErrorTextColor)
Set the error text colour used for the largest text.

public int getSecondaryErrorTextColor()
Return the error text colour used in a 2nd-largest text.

public void setSecondaryErrorTextColor(int secondaryErrorTextColor)
Set the error text colour used in a 2nd-largest text.

public int getTertiaryErrorTextColor()
Return the error text colour used in a 3rd-largest text.

public void setTertiaryErrorTextColor(int tertiaryErrorTextColor)
Set the error text colour used in a 3rd-largest text.

public int getQuaternaryErrorTextColor()
Return the error text colour used in a smallest text.

public void setQuaternaryErrorTextColor(int quaternaryErrorTextColor)
Set the error text colour used in a smallest text.

Relationships

Inherits from: Nothing
Implements: Parcelable



 

JPTransactionResponse

Overview

JPTransactionResponse encapsulates a high-level response from the Jetpay backend for a given transaction.

A JPTransactionResponse is created from a JPServiceResponse by JPService. It contains a subset of the information contained in the JPServiceResponse. The successful creation of a JPTransactionResponse object means that the SDK considered the JPServiceResponse valid.

Symbols

Creating a JPTransactionResponse

JPTransactionResponse.newInstance( JPServiceResponse str )
Given a JPServiceResponse, return a new instance of JPTransactionResponse.
This initialisation fails if the JPActionCode in JPServiceResponse is nil.


Accessing Properties

public String getAVS()
The result code sent by an issuer advising the merchant of a customer’s billing integrity. This value is only set when AVS was enabled for the transaction.

public JPActionCode getActionCode()
The action code returned by the Jetpay Gateway.

public String getAddressMatch()
Was the billing address matched correctly? ‘Y’, ’N’ or ‘X’ for no match available. This value is only set when AVS was enabled for the transaction.

public String getApproval()
The Approval string returned by the Jetpay Gateway.

public String getRawResponseCode()
The RawResponseCode returned by the Jetpay Gateway.

public String getResponseText()
The ResponseText returned by the Jetpay Gateway.

public String getRRN()
The RRN returned by the Jetpay Gateway.

public String getTransactionID()
The TransactionID returned by the Jetpay Gateway.

public String getUniqueID()
The UniqueID returned by the Jetpay Gateway.

public String getZipMatch()
Was the billing address zip code matched correctly? ‘Y’, ’N’ or ‘X’ for no match available. This value is only set when AVS was enabled for the transaction.

public String description()
Returns a String description summary for the response.


Relationships

Inherits from: JPBaseResponse
Implements: Nothing




Interfaces

Object Definitions & Quicklinks
  • Expand all
  • Collapse all
  • Interfaces ...defining the blueprint of methods, properties & other requirements that suit a particular task or piece of functionality within the SDK
    • JPAddCardActivityListener ...provides feedback to a listening object on behaviour of the JPAddCardActivity object.
    • JPPaymentCardFragmentListener ... provides feedback to a listening object on behaviour of the JPPaymentCardFragment object.
    • JPPaymentContextListener ...allows the listening object to manage various state changes in the JPPaymentContext such as successful posting of payment transaction to the Jetpay backend.
    • JPSelfValidating ...defines a standard interface for all self-validating SDK objects.

 

JPAddCardActivityListener

Overview

The JPAddCardActivityListener provides feedback to a listening object on behaviour of the JPAddCardActivity object.

Most notable, are when the user selects the Cancel or Save buttons.

Symbols

Interface Definition

public interface JPAddCardActivityListener
This interface's definition.


Activity State Changes

void addCardActivityDidCancel(JPAddCardActivity addCardActivity)
At any point the user can cancel the entry of card and address details. The listening object receives this callback when this happens.

void addCardActivityDidSaveToSharedPaymentContext(JPAddCardActivity addCardActivity)
When the JPAddCardActivity recognises all data entered into it’s cells is valid, it will enable the Save button.
When the user taps this button, the data is saved to the JPPaymentContext, and this method is invoked to the listening object.

Relationships

Inherits from: Nothing
Implements: Nothing
Implemented by: 3rd-party classes using JPAddCardActivity events



 

JPPaymentCardFragmentListener

Overview

The JPPaymentCardFragmentListener provides feedback to a listening object on behaviour of the JPPaymentCardFragment object.

As the user enters payment card data into a JPPaymentCardFragment (horizontal or vertical), feedback is provided through JPPaymentCardFragmentListener methods.

Symbols

Interface Definition

public static interface JPPaymentCardFragmentListener
This interface's definition.


Card Fragment State Changes

void paymentCardFragmentDidChange(JPPaymentCardFragment fragment)
When any of the JPPaymentCardFragment fields change, the listener receives this callback.

void paymentCardFragmentDidBeginEditingNumber(JPPaymentCardFragment fragment)
Sent to the listening object when the user begins editing the card number text field.

void paymentCardFragmentDidEndEditingNumber(JPPaymentCardFragment fragment)
Sent to the listening object when the user end editing the card number text field.

void paymentCardFragmentDidBeginEditingCVC(JPPaymentCardFragment fragment)
Sent to the listening object when the user begins editing the CVC text field.

void paymentCardFragmentDidEndEditingCVC(JPPaymentCardFragment fragment)
Sent to the listening object when the user ends editing the CVC text field.

void paymentCardFragmentDidBeginEditingExpiration(JPPaymentCardFragment fragment)
Sent to the listening object when the user begins editing the expiration text field.

void paymentCardFragmentDidEndEditingExpiration(JPPaymentCardFragment)
Sent to the listening object when the user ends editing the expiration text field.


Relationships

Inherits from: Nothing
Implements: Nothing
Implemented by: JPAddCardActivity, 3rd-party classes using JPPaymentCardFragment (or it’s subclasses)



 

JPPaymentContextListener

Overview

The listener of JPPaymentContext must implement the JPPaymentContextListener interface. This allows the listening object to manage various state changes in the JPPaymentContext such as successful posting of payment transaction to the JetPay backend.

For example, when posting a transaction on the payment context, the payment context will provide delegate callbacks indicating either a successful post or an error condition. Most error conditions indicate data in the payment context is either invalid or incomplete.

Symbols

Interface Definition

public interface JPPaymentContextListener
This interface's definition.


Posting a Payment Transaction

void paymentContextDidPostTransaction(JPPaymentContext paymentContext)
Tells the listening object that the data in JPPaymentContext has been successfully validated and posted to the JetPay backend for processing.
This does not mean the data has been successfully processed by the backend - just posted successfully.

void paymentContextDidCancelPostAsPostCurrentlyInProgress(JPPaymentContext paymentContext)
Tells the listening object that the data in JPPaymentContext cannot be posted to the JetPay backend because there is current a post in progress.
JPPaymentContext can only perform one transaction post at any one time.
A post is considered “complete” when either a response has been received from the JetPay backend -
OR a network error (such as timeout) has occurred.

void paymentContextDidCancelPostAsPaymentCardIsUnsupported(JPPaymentContext paymentContext)
Tells the listening object that the data in JPPaymentContext cannot be posted to the Jetpay backend
- because the payment card, although a valid card, is NOT currently supported by the JetPay Gateway.

void paymentContextDidCancelPostAsPaymentCardIsInvalid(JPPaymentContext paymentContext)
Tells the listening object that the data in JPPaymentContext cannot be posted to the JetPay backend
- because the payment card is invalid. JPPaymentContext therefore cancelled the operation.

void paymentContextDidCancelPostAsTransactionIdIsInvalid(JPPaymentContext paymentContext)
Tells the listening object that the data in JPPaymentContext cannot be posted to the JetPay backend
- because the transactionId is invalid. JPPaymentContext therefore cancelled the operation.

void paymentContextTransactionPostReceivedTransactionResponse(JPPaymentContext paymentContext)
Tells the listening object that a transaction response has been received from the Jetpay backend.

void paymentContextTransactionPostDidNotReceiveTransactionResponse(JPPaymentContext paymentContext)
Tells the listening object that a transaction response has NOT ben been received from the Jetpay backend
- in response to a submitted request. Instead, an underlying network connectivity problem has been experienced
- check via getCurrentError() on JPPaymentContext.


Relationships

Inherits from: Nothing
Implements: Nothing
Implemented by: Client classes



 

JPSelfValidating

Overview

JPSelfValidating defines a standard interface for all self-validating SDK objects.

Currently, the only required method in JPSelfValidating is isValid(). Any object that Implements JPSelfValidating implements this method and returns true if that object is valid or false otherwise.

Symbols

Interface Definition

public interface JPSelfValidating
This interface's definition.


Self Validating

boolean isValid()
The implementing object instance implements this method and returns true if that object considers itself valid. If not, or incomplete, return false.


Relationships

Inherits from: Nothing
Implements: Nothing
Implemented by: JPAccount, JPAddressViewModel, JPCardParams,JPConfiguration,JPPaymentCardFragment,
JPPaymentCardFragmentViewModel, JPPaymentContext, JPTransaction



Singleton Objects


Object Definitions & Quicklinks
  • Expand all
  • Collapse all
  • Singleton Objects ...containing the data of the app, making data accessible & implementing logic to manipulate & display the data
    • JPClient ...provides a high-level veneer across the SDK, simplifying and generalising functionality provided in lower-level SDK objects.
    • JPConfiguration ...is a singleton object which encapsulates a number of global settings consumed across the SDK.

 

JPClient

Overview

JPClient provides a high-level veneer across the SDK, simplifying and generalising functionality provided in lower-level SDK objects.

JPClient is a singleton object which provides a high-level interface to the SDK. The SDK’s full functionality can be used without this object. However, JPClient provides methods which simplify your calling code under certain circumstances.

All SDK functionality is provided by lower-level SDK API objects, and therefore you do not need to use JPClient to use the SDK to it’s full potential. However, JPClient provides a number of methods which simplify SDK instruction and movement of data between your app and the SDK.


Symbols

Accessing JPClient

JPTheme is a singleton object.

JPClient jpClient = JPClient.sharedInstance;


Posting Transaction Requests

public void postSaleTransactionInPaymentContext()
Request JPPaymentContext to post a SALE payment transaction to the JetPay backend.

public void postAuthonlyTransactionInPaymentContext()
Request JPPaymentContext to post a AUTHONLY payment transaction to the JetPay backend. This effectively verifies the payment card with the card issuer.


NOTE: Listener callback methods are available through JPPaymentContextListener. There is no JPClient equivalent. Therefore, to receive JPPaymentContextListener callbacks when using JPClient as a convenience wrapper, use JPPaymentContext to initially setup your listener object.


Relationships

Inherits from: Nothing
Implements: Nothing


 

JPConfiguration

Overview

JPConfiguration is a singleton object which encapsulates a number of global settings consumed across the SDK.

JPConfiguration provides an easy to use central repository for data that only needs to be set once and is used by SDK objects as and when required.

Typically, you setup JPConfiguration before using other SDK objects. Other SDK objects then access JPConfiguration as appropriate to drive their functionality.

Example settings include environment type, developer account, the global theme and required address fields for payment card processing.

JPConfiguration Implements the JPSelfValidating interface and is therefore self-validating. For the JPConfiguration object to be valid, it requires an account and environment.


Symbols

Accessing JPConfiguration

JPConfiguration myConfig = JPConfiguration.sharedConfiguration;
JPConfiguration is a singleton object.


Setting the Environment Type

public void setEnvironmentType(JPEnvironmentType environmentType)
Specify what environment to be used by the SDK.


Setting your Developer Account

public boolean setAccount(String visaDeveloperID, String developerID, String terminalID)
Specify your developer account details to the SDK.


Setting the Global Theme

Specify the global theme to be used by the SDK.

public void setTheme(JPTheme globalTheme)
Specify the global theme to be used by the SDK.


Accessing the Required Address Fields

public JPRequiredAddressFields getRequiredAddressFields()
Returns the required address fields.

public void setRequiredAddressFields(JPRequiredAddressFields requiredAddressFields)
Sets the required address fields.


Determine if AVS is enabled

public boolean isAVSenabled()
When the required address fields are set to full, JPConfiguration enables AVS. Otherwise AVS is disabled.


Relationships

Inherits from: Nothing
Implements: Nothing



View Objects

Object Definitions & Quicklinks
  • Expand all
  • Collapse all
  • View Objects ...draw a visual representation of itself and presents a surface that responds to touches and input from devices
    • JPPaymentCardFragment ...is a subclass of Fragment and provides the necessary UI objects and business logic for collecting, identifying and validating payment card information.
    • JPPaymentCardHorizontalFragment ...is a subclass of JPPaymentCardFragment and fixes JPPaymentCardFragment in a horizontal orientation.
    • JPPaymentCardVerticalFragment ...is a subclass of JPPaymentCardFragment and fixes JPPaymentCardFragment in a vertical orientation.

 

JPPaymentCardFragment

Overview

JPPaymentCardFragment is a subclass of Fragment and provides the necessary UI objects and business logic for collecting, identifying and validating payment card information.

Payment card information includes the payment card’s number, expiry date and CVC number. This information can either be collected from the user via the device's keyboard or loaded into JPPaymentCardFragment programmatically. In both these use cases, JPPaymentCardFragment is able to validate itself against known payment card numbers and brands.

JPPaymentCardFragment should NOT be instantiated directly. Instead, use one of it’s specific subclasses JPPaymentCardHorizontalFragment or JPPaymentCardVerticalFragment.

JPPaymentCardFragment behaviour and state is communicated through the JPPaymentCardFragmentListener interface.


Symbols

Creating a JPPaymentCardFragment

JPPaymentCardFragment should not be created directly. Instead, instantiate one of it’s subclasses - JPPaymentCardHorizontalFragment or JPPaymentCardVerticalFragment.


Themes and Customisation

public JPTheme getTheme()
Return the fragment’s theme.

public void setTheme(JPTheme theme)
Sets the theme for the fragment.

public JPEdgeInsets getSubtitlesContentPaddingInsets()
Return the padding around the subtitles content area.

public void setSubtitlesContentPaddingInsets( JPEdgeInsets paddingInsets )
Set the padding values for the subtitles content layout area. Default is 0 for all thee values.

public int getSubtitlesLayoutBackgroundColor()
Return the background colour for the subtitles layout area.

public void setSubtitlesLayoutBackgroundColor( int color )
Sets the background colour for the subtitles layout area. Default is Color.TRANSPARENT.

public int getSubtitlesContentLayoutBackgroundColor()
Return the background colour for the subtitles layout content area.

public void setSubtitlesContentLayoutBackgroundColor( int color )
Sets the background colour for the subtitles layout content area. Default is Color.TRANSPARENT

public JPEdgeInsets getFieldsContentPaddingInsets()
Return the padding around the fields content area.

public void setFieldsContentPaddingInsets( JPEdgeInsets paddingInsets )
Set the padding values for the fields content layout area. Default is 0 for all thee values.

public int getFieldGravity()
Returns the gravity for the internal JPFormTextField fields.

public void setFieldGravity( int gravity )
Sets the gravity for all internal JPFormTextField fields. Default is Gravity.LEFT

public int getFieldsLayoutBackgroundColor()
Return the background colour for the fields layout area.

public void setFieldsLayoutBackgroundColor( int color )
Sets the background colour for the fields layout area. Default is Color.TRANSPARENT.

public int getFieldsContentLayoutBackgroundColor()
Return the background colour for the fields layout content area.

public void setFieldsContentLayoutBackgroundColor( int color )
Sets the background colour for the fields layout content area. Default is Color.TRANSPARENT

public int getInternalFieldBackgroundColor()
Return the background colour for the internal JPFormTextField fields and the ImageView card brand image.

public void setInternalFieldBackgroundColor( int color )
Sets the background colour for each of the internal JPFormTextField fields and the ImageView -
which displays the payment card brand image.
Default is Color.TRANSPARENT.

public void setUseSmallBrandImage(boolean useSmallBrandImage)
Specify whether the small card brand image is used.


Text and Placeholders

public void setTypeFace( Typeface typeFace )
Sets the typeface used for the data entry fields.

public void setTextSize( float textSize )
Sets the text size for the data entry fields.

public void setDefaultTextColor(int defaultTextColor)
Default is black. Sets the colour for the text in the data entry fields.

public void setTextErrorColor(int textErrorColor)
Default is red. Sets the colour for the text in the data entry fields when this data is recognised as invalid.

public void setHintColor( int hintColor )
Sets the hint colour for the internal JPFormTextField fields. Default is Color.LTGRAY.

public void setNumberHint( String hint )
Sets the hint for the number field when it is empty. Default is blank.

public void setExpirationHint( String hint )
Sets the hint for the expiration field when it is empty. Default is blank.

public void setCvcHint( String hint )
Sets the hint for the CVC field when it is empty. Default is blank.


Validation

public boolean isValid()
True if JPPaymentCardFragment identifies itself as holding complete and valid data, false otherwise.


Miscellaneous

public void clear()
Clears the JPPaymentCardFragment. This results in the UI fields being cleared, the brand image being cleared and the model status being cleared.


Relationships

Inherits from: Fragment
Implements: JPFormTextFieldListener, JPSelfValidating, JPThemeProtocol


 

JPPaymentCardHorizontalFragment

Overview

JPPaymentCardHorizontalFragment is a subclass of JPPaymentCardFragment and fixes JPPaymentCardFragment in a horizontal orientation. It’s function is to collect and validate user-entered payment card data - i.e. card number, expiry date and CVC code.

Most of the functionality for JPPaymentCardHorizontalFragment can be seen in JPPaymentCardFragment.

JPPaymentCardHorizontalFragment defines properties and behaviour for laying a JPPaymentCardFragment out horizontally. This horizontal layout is currently defined in an XML layout file.


Symbols

Creating a JPPaymentCardHorizontalFragment

Use the fragment_jppayment_card_horizontal XML layout file..


Relationships

Inherits from: JPPaymentCardFragment
Implements: JPFormTextFieldListener, JPSelfValidating


 

JPPaymentCardVerticalFragment

Overview

JPPaymentCardVerticalFragment is a subclass of JPPaymentCardFragment and fixes JPPaymentCardFragment in a vertical orientation. It’s function is to collect and validate user-entered payment card data - i.e. card number, expiry date and CVC code.

Most of the functionality for JPPaymentCardVerticalFragment can be seen in JPPaymentCardFragment.

JPPaymentCardVerticalFragment defines properties and behaviour for laying a JPPaymentCardFragment out vertically. Unlike JPPaymentCardHorizontalFragment, there is normally enough space to align data entry fields rather than dynamically align them.


Symbols

Creating a JPPaymentCardVerticalFragment

Use the fragment_jppayment_card_vertical XML layout file.


Customisation

public void setVerticalPaddingBetweenFields( int verticalPaddingBetweenFields)
Default is 5dp. Sets the vertical margin between each of the payment card fields in the fragment.

public void setExpirySubtitleText( String text )
Sets the expiry subtitle text. Defaults to an empty string.

public void setCvcSubtitleText( String text )
Sets the cvc subtitle text. Defaults to an empty string.

public int getSubtitleGravity()
Returns the gravity for the internal subtitle fields.

public void setSubtitleGravity( int gravity )
Sets the gravity for all internal subtitle fields. Default is Gravity.LEFT.

public void setSubtitleTextColor( int color )
Sets the subtitle text colour. Defaults to Color.BLACK.

public void setSubtitleTypeFace( Typeface typeFace )
Sets the subtitle text typeface.

public void setSubtitleTextSize( float textSize )
Sets the subtitle text size.


Relationships

Inherits from: JPPaymentCardFragment
Implements: JPFormTextFieldListener, JPSelfValidating