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

IMPORTANT

@August 10th 2017 we currently support:
> Apple's Xcode version 8.3.3
> Apple's iOS 9.0 +



JetPay SDK Full iOS Reference

Welcome to JetPay Solution's Software Development Kit Reference Guide for iOS. 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 iOS 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

Type's of object that contain the data of the application, providing access to that data, and implementing logic to manipulate & display the data

box icon

Protocols

Protocols define the blueprint of methods, properties, and other requirements that suit a particular task or piece of functionality within the SDK

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 iOS app.

Controller Objects:

JPAddCardViewController

Overview

JPAddCardViewController is a subclass of UIViewController and provides a full-screen view controller for collecting customer details. These details are the customer’s payment card details and the customer’s address (optional). JPPaymentCardViewController can be presented both modally or in a navigation stack.

Feedback on behaviour and state for JPAddCardViewController is provided through the JPAddCardViewControllerDelegate protocol.

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 JPAddCardViewController will not enable the [ Save ] function unless all entered data is recognised as complete and valid.


Symbols

Creating a JPAddCardViewController

init(nibName nibNameOrNil: String?, bundle nibBundleOrNil: Bundle?)

Instantiate using the given nibName and bundle

init?(coder aDecoder: NSCoder)
Instantiate froma a storyboard or Xib file      


Themes and Customisation

public var theme: JPTheme

Defaults to the globalTheme in the shared JPConfiguration object.

public var cellContentInsets: UIEdgeInsets
Defaults to 0. Sets the insets for the payment card and address cells displayed in the JPAddCardViewController's UITableView.

public var heightForSectionHeader: CGFloat
Defaults to 22.0. Sets the height section headers in the JPAddCardViewController’s UITableView.

public var subtitleTextAlignment: NSTextAlignment
Defaults to left-aligned. Sets the subtitle text alignment for address cells.

public var fieldTextAlignment: NSTextAlignment
Defaults to left-aligned. Sets the data entry field text alignment for address and payment card cells.


Relationships

Inherits from: UIViewController
Conforms to: JPThemeProtocol, UITableViewDelegate, UITableViewDataSource,
JPPaymentCardTextFieldDelegate, JPAddressViewModelDelegate


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

 

JPClientPostTransactionResult

Overview

JPClientPostTransactionResult is a type alias defining the completion closure type required when posting payment transactions on JPPaymentContext. Because JPClient is, effectively, a high-level wrapper for lower-level functionality, JPClientPostTransactionResult is the same type as JPPaymentContextPostTransactionResult.

Symbols

public type alias JPClientPostTransactionResult = JPPaymentContextPostTransactionResult


 

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
Conforms to: 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
Conforms to: Nothing


 

JPPaymentContextPostTransactionResult

Overview

JPPaymentContextPostTransactionResult is a type alias defining the completion closure type required when posting payment transactions on JPPaymentContext.

Symbols

public type alias JPPaymentContextPostTransactionResult = (JPTransactionResponse?, Error?) -> Void


 

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 JPAddCardViewController is initialised, the value from JPConfiguration is used to create the JPAddressViewModel object which supports the JPAddCardViewController. JPAddressViewModel makes use of JPRequiredAddressFields to create the necessary data entry cells for display by the JPAddCardViewController.


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.
    • JPAddress ...encapsulates a customer’s address; hold's a billing address for a particular payment card.
    • JPCardParams ...encapsulates payment card details
    • JPCustomer ...encapsulates a customer’s basic identification details
    • JPPaymentContext ... a singleton object used to collect all required information required to generate a transaction payment request...
    • JPTheme ...encapsulates a number of style attributes together to produce a visual theme that can be used by SDK visual objects.
    • JPTransactionResponse ...encapsulates a high-level 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

let value: String
A read-only string representation of the Action Code. For example, “000” represents a successful response.

var cardBrand: JPCardBrand
The card brand used to make the original transaction request. JPActionCode uses this value to map the action code to an appropriate string error message when requested.

public func isApproved() -> Bool
Returns true if JPActionCode represents an approved transaction, false otherwise.

public func isValid() -> Bool
Returns true if JPActionCode appears to be valid, false otherwise.

public func detailedDescription() -> String
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: NSObject
Conforms to: 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 conform to 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.

let myAddress = JPAddress()
myAddress.name = “John Appleseed”
..

Determining Address Validation

public func isValid(_ requiredFields: JPRequiredAddressFields)
Given the required address fields, determines whether the address is valid.

Setting Address Properties

public var name: String?
The billing address name.

public var line1: String?
The billing address name.

public var line2: String?
Line 2 of the billing address. Considered optional in a valid postal address.

public var city: String?
The city of the billing address.

public var state: String?
The state of the billing address. County in the UK.

public var postalCode: String?
The postal code of the billing address. Zip in the US.

public var country: String?
The country of the billing address.

public var phone: String?
The phone number of the billing address. Considered optional in a valid postal address.

public var email: String?
The email address of the billing address. Considered optional in a valid postal address.

Relationships

Inherits from: NSObject
Conforms to: 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 JPPaymentCardTextField) or to unload these same SDK UI elements after the user has entered the card details.

Symbols

Creating JPCardParams

init()
Creates an instance of JPCardParams with default empty values.
These default values represent an unknown card type and can be changed by changing property values on the JPCardParams instance later.

init( number: String, expireMonth: UInt, expireYear: UInt, cvc: String )
Creates an instance of JPCardParams with the given parameter values.


Accessing the Card Number

public var cardNumber: String
The payment card number.

public var cardNumberFormattedForBrand: NSAttributedString
The payment card number formatted with appropriate spacing specific to card brand.


Accessing Expiry Details

public var expireMonth: UInt
The expiry month as an integer.

public var expireMonthString: String
The expiry month as a 2-digit string, COMPUTED from expireMonth.

public var expireYear: UInt
The expiry year as an integer.

public var expirationYear: String
The expiry year as a 2-digit string, COMPUTED from expireYear.


Accessing the Cardholder's Name

The payment card holder’s name is stored in the address property. See Accessing the Cardholder’s Address for details.


Accessing the CVC

public var cvc: String
Holds the payment card security CVC number.


Accessing the Cardholder's Address

public var address: JPAddress?
The cardholder’s billing address. This is an optional value as a customer’s name and address are only required for payment transactions when AVS is enabled.


Accessing Brand Images

public var imageForBrand: UIImage?
Given the card brand, return a 32x20 (logical coordinates) PNG image representing that card brand.

public var largeImageForBrand: UIImage?
Given the card brand, return a 53x20 (logical coordinates) PNG image representing that card brand.


Confirming Validation State

public func isValid() -> Bool
true if the JPCardParams instance is considered valid, false otherwise.

Relationships

Inherits from: NSObject
Conforms to: 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

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

Relationships

Inherits from: NSObject
Conforms to: 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 Error subclass instance 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 transactionId and 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 conforms to the JPSelfValidating protocol and so can determine itself whether a valid and complete transaction payment request can be made.

If you have set your app as a delegate for JPPaymentContext, then requesting the JPPaymentContext to post a transaction will result in appropriate delegate callback methods. See the JPPaymentContextDelegate protocol for more details.

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

Symbols

Accessing JPPaymentContext

public static var sharedContext: JPPaymentContext
Return the singleton JPPaymentContext.

public func clearContext() -> Void
Clears the JPPaymentContext, ready for a new transaction request.

Accessing the Customer

public func setCustomer( _ customer: JPCustomer? ) -> Void
Set the customer on JPPaymentContext. Note, the Jetpay SDK makes no use of the JPCustomer data - it is for your reference only.

public func getCustomer() -> JPCustomer?
Returns the JPCustomer object held in JPPaymentContext.

Accessing the Payment Transaction Amount

public func setPaymentAmount( _ paymentAmount: Double )
Sets the payment amount on the JPPaymentContext.

public func getPaymentAmount() -> Double
Returns in payment amount stored in JPPaymentContext.

Accessing the Payment Card

public func setPaymentCard( _ paymentCard: JPCardParams?)
Set the given payment card on the JPPaymentContext.

public func getPaymentCard() -> JPCardParams?
Gets the payment card stored in JPPaymentContext.

Accessing the TransactionId

public func setTransactionId( _ transactionId: String )
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 func getTransactionId() -> String
Gets the transactionId stored in JPPaymentContext.

Posting a Transaction Payment

public weak var delegate: JPPaymentContextDelegate?
Sets the delegate for the JPPaymentContext.

public func postSaleTransaction( _ completion: @escaping JPPaymentContextResult ) -> Void
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 func verifyCard( _ completion: @escaping JPPaymentContextResult ) -> Void
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 func isValid() -> Bool
Identifies whether the JPPaymentContext is valid. That is, the data it contains is valid and complete.

public func validationState() -> JPPaymentContextError
Returns the explicit validation state of JPPaymentContext. See the JPPaymentContextError enum for details.

public func getCurrentState() -> JPPaymentContextError
As above.

public func getCurrentError() -> Error?
Contains the Error object returned (nil if successful) for the most recently POSTed transaction request.

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


Relationships

Inherits from: NSObject
Conforms to: JPSelfValidating



 

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.

let myTheme = JPTheme()


Accessing the Default Theme

The defaultTheme class method returns a default theme.

let defaultTheme = JPTheme.defaultTheme()


Accessing Background Colours

public var primaryBackgroundColor: UIColor?
The background colour used for the highest view in the hierarchy.

public var secondaryBackgroundColor: UIColor?
The background colour used in a 2nd-level view.

public var tertiaryBackgroundColor: UIColor?
The background colour used in a 3rd-level view.

public var quaternaryBackgroundColor: UIColor?
The background colour used in a 4th-level view.


Accessing Border Colours

public var primaryBorderColorColor: UIColor?
The border colour used for the highest view in the hierarchy.

public var secondaryBorderColor: UIColor?
The border colour used in a 2nd-level view.

public var tertiaryBorderColor: UIColor?
The border colour used in a 3rd-level view.

public var quaternaryBorderColor: UIColor?
The background colour used in a 4th-level view.


Accessing Text Colours

public var primaryTextColor: UIColor?
The text colour used for the largest text.

public var secondaryTextColor: UIColor?
The text colour used in a 2nd-largest text.

public var tertiaryTextColor: UIColor?
The text colour used in a 3rd-largest text.

public var quaternaryTextColor: UIColor?
The text colour used in a smallest text.


Accessing Error Text Colours

public var primaryErrorTextColor: UIColor?
The error text colour used for the largest error text.

public var secondaryErrorTextColor: UIColor?
The error text colour used in a 2nd-largest error text. Note: Currently not used by the SDK.

public var tertiaryErrorTextColor: UIColor?
The error text colour used in a 3rd-largest error text. Note: Currently not used by the SDK.

public var quaternaryErrorTextColor: UIColor?
The error text colour used in a smallest error text. Note: Currently not used by the SDK.


Relationships

Inherits from: NSObject
Conforms to: Nothing



 

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

NOTE: The typical use case is that only the Jetpay SDK creates JPTransactionResponse instances.

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

Accessing Properties

public let AVS: String?
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 var actionCode: JPActionCode
The action code returned by the Jetpay Gateway.

public let addressMatch: String?
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 let approval: String?
The Approval string returned by the Jetpay Gateway.

public let rawResponseCode: String
The RawResponseCode returned by the Jetpay Gateway.

public let responseText: String
The ResponseText returned by the Jetpay Gateway.

public let RRN: String
The RRN returned by the Jetpay Gateway.

public let transactionID: String
The TransactionID returned by the Jetpay Gateway.

public let uniqueID: String
The UniqueID returned by the Jetpay Gateway.

public let zipMatch: String?
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.


Relationships

Inherits from: NSObject
Conforms to: Nothing



Protocols

Object Definitions & Quicklinks
  • Expand all
  • Collapse all
  • Protocols ...defining the blueprint of methods, properties & other requirements that suit a particular task or piece of functionality within the SDK

 

JPAddCardViewControllerDelegate

Overview

The JPAddCardViewControllerDelegate provides feedback to a delegate object on behaviour of the JPAddCardViewController object.

Most notable, are when the JPAddCardViewController recognises all data entered by the user is valid or when the user selects the Cancel or Save buttons.

Symbols

Protocol Definition

@objc public protocol JPAddCardViewControllerDelegate: class
This protocol's definition.


Controller State Changes

func addCardViewControllerDidCancel(_ addCardViewController: JPAddCardViewController
) -> Void
At any point the user can cancel the entry of card and address details. The delegate receives this callback when this happens.


func addCardViewControllerDidSaveToSharedPaymentContext(_
addCardViewController: JPAddCardViewController) -> Void
When the JPAddCardViewController 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 sent to the delegate.


@objc optional func addCardViewControllerAllInputFieldsValidAndReadyToSave(_
addCardViewController: JPAddCardViewController) -> Void
When the JPAddCardViewController recognises all data entered into it’s cells is valid, it will enable the Save button and send this message to the delegate object.


Relationships

Inherits from: Nothing
Conforms to: Nothing
Adopted by: 3rd-party classes using JPAddCardViewController



 

JPPaymentCardFieldDelegate

Overview

The JPPaymentCardFieldDelegate provides feedback to a delegate object on behaviour of the JPPaymentCardField object.

As the user enters payment card data into a JPPaymentCardField (horizontal or vertical), feedback is provided through JPPaymentCardFieldDelegate methods. This feedback is similar in nature to that provided by UITextFieldDelegate.

Symbols

Protocol Definition

@objc public protocol JPPaymentCardFieldDelegate: class
This protocol's definition.


Card Field State Changes

func paymentCardFieldDidChange(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user begins editing the card number text field.

@objc optional func paymentCardFieldDidBeginEditingNumber(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user begins editing the card number text field.

@objc optional func paymentCardFieldDidEndEditingNumber(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user end editing the card number text field.

@objc optional func paymentCardFieldDidBeginEditingCVC(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user begins editing the CVC text field.

@objc optional func paymentCardFieldDidEndEditingCVC(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user ends editing the CVC text field.

@objc optional func paymentCardFieldDidBeginEditingExpiration(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user begins editing the expiration text field.

@objc optional func paymentCardFieldDidEndEditingExpiration(_ textField: JPPaymentCardField) -> Void
Sent to the delegate when the user ends editing the expiration text field.


Relationships

Inherits from: Nothing
Conforms to: Nothing
Adopted by: JPAddCardViewController, 3rd-party classes using JPPaymentCardField (or it’s subclasses)



 

JPPaymentContextDelegate

Overview

The delegate of JPPaymentContext must adopt the JPPaymentContextDelegate protocol. This allows the delegate 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

Protocol Definition

@objc public protocol JPPaymentContextDelegate: class
This protocol's definition.


Posting a Payment Transaction

func paymentContextDidPostTransaction(_ paymentContext: JPPaymentContext) -> Void
Tells the delegate 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.

@objc optional func paymentContextDidCancelPostAsPostCurrentlyInProgress( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate 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.

@objc optional func paymentContextDidCancelPostAsPaymentCardIsUnsupported( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate 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.
JPPaymentContext therefore cancelled the operation.

@objc optional func paymentContextDidCancelPostAsPaymentAmountIsInvalid( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate that the data in JPPaymentContext cannot be posted to the JetPay backend because the payment amount is invalid.
JPPaymentContext therefore cancelled the operation.

@objc optional func paymentContextDidCancelPostAsPaymentCardIsInvalid( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate that the data in JPPaymentContext cannot be posted to the JetPay backend because the payment card is invalid.
JPPaymentContext therefore cancelled the operation.

@objc optional func paymentContextDidCancelPostAsPaymentCardAddressIsInvalidForAVS( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate that the data in JPPaymentContext cannot be posted to the Jetpay backend because the payment card billing address is invalid. An address is optional unless AVS is enabled for transactions. JPPaymentContext therefore cancelled the operation.

@objc optional func paymentContextDidCancelPostAsTransactionIdIsInvalid( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate that the data in JPPaymentContext cannot be posted to the Jetpay backend because the transactionId is invalid. JPPaymentContext therefore cancelled the operation.

func paymentContextTransactionPostReceivedTransactionResponse( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate that a transaction response has been received from the JetPay backend.

func paymentContextTransactionPostDidNotReceiveTransactionResponse( _ paymentContext: JPPaymentContext) -> Void
Tells the delegate 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
Conforms to: JPSelfValidating
Adopted 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 conforms to JPSelfValidating implements this method and returns true if that object is valid or false otherwise.

Symbols

Protocol Definition

protocol JPSelfValidating
This protocol's definition.


Self Validating

func isValid() -> Bool
The conforming instance implements this method and returns true if that object considers itself valid. If not, or incomplete, return false.


Relationships

Inherits from: Nothing
Conforms to: Nothing
Adopted by: JPAccount, JPAddressViewModel, JPCardParams, JPConfiguration, JPPaymentCardTextField,
JPPaymentCardTextFieldViewModel, 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

JPClient is a singleton object.

let jpClient = JPClient.sharedInstance


Posting Transaction Requests

public func postTransactionInPaymentContext(_ completion: @escaping JPClientPostTransactionResult)
Request JPPaymentContext to post a SALE payment transaction to the JetPay backend.

public func postAuthonlyTransactionInPaymentContext(_ completion: @escaping JPClientPostTransactionResult)
Request JPPaymentContext to post a AUTHONLY payment transaction to the JetPay backend. This effectively verifies the payment card with the card issuer.


NOTE: Although a completion closure can be included here, delegate callback methods are only available through JPPaymentContextDelegate. There is no JPClient equivalent. Therefore, to receive JPPaymentContextDelegate callbacks when using JPClient as a convenience wrapper, use JPPaymentContext to initially setup your delegate object.


Relationships

Inherits from: NSObject
Conforms to: 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 conforms to the JPSelfValidating protocol and, is therefore self-validating. For the JPConfiguration object to be valid, it requires an account and environment.


Symbols

Accessing JPConfiguration

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


Setting the Environment Type

@objc public func setEnvironmentType(_ environmentType: JPEnvironmentType) -> Void
Specify what environment to be used by the SDK.


Setting your Developer Account

public func setAccount(visaDeveloperID: String, developerID: String, terminalID: String) -> Bool
Specify your developer account details to the SDK.


Setting the Global Theme

public func setTheme(_ globalTheme: JPTheme) -> Void
Specify the global theme to be used by the SDK.


Accessing the Required Address Fields

public var requiredAddressFields: JPRequiredAddressFields
Access the required address fields used for making payment card transactions.


Determine if AVS is enabled

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


Relationships

Inherits from: NSObject
Conforms to: 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
    • JPPaymentCardField ...a subclass of UIControl; provides the necessary UI objects & business logic for collecting, identifying & validating payment card information
    • JPPaymentCardHorizontalField ...is a subclass of JPPaymentCardField and fixes JPPaymentCardField in a horizontal orientation.
    • JPPaymentCardVerticalField ...is a subclass of JPPaymentCardField and fixes JPPaymentCardField in a vertical orientation.

 

JPPaymentCardField

Overview

JPPaymentCardField is a subclass of UIControl 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 iDevice keyboard or loaded into JPPaymentCardField programmatically. In both these use cases, JPPaymentCardField is able to validate itself against known payment card numbers and brands.

JPPaymentCardField should NOT be instantiated directly. Instead, use one of it’s specific subclasses JPPaymentCardHorizontalField or JPPaymentCardVerticalField.

JPPaymentCardField and it’s subclasses are IBDesignable objects.

JPPaymentCardField behaviour and state is communicated through the JPPaymentCardFieldDelegate protocol.


Symbols

Creating a JPPaymentCardField

JPPaymentCardField should not be created directly. Instead, instantiate one of it’s subclasses - JPPaymentCardHorizontalField or JPPaymentCardVerticalField.


Themes and Customisation

public var theme: JPTheme
Sets the JPTheme for the cell. The cell is instantly refreshed with the new theme.

public var subtitlesContentInsets: UIEdgeInsets
Default is 0. Inset the subtitles content area by the given insets.

public var subtitlesViewBackgroundColor: UIColor
Specifies the background colour for the subtitles view area.

public var subtitlesContentViewBackgroundColor: UIColor
Specifies the background colour for the subtitles view content area.

public var fieldsContentInsets: UIEdgeInsets
Default is 0. Inset the fields content area by the given insets.

public var dynamicFieldWidth: Bool
Default is true. A setting of false allows all payment fields to have the same width.

public var fieldTextAlignment: NSTextAlignment
Default is left-aligned. Align field text within the fields content area.

public var fieldsViewBackgroundColor: UIColor
Specifies the background colour for the fields view area.

public var fieldsContentViewBackgroundColor: UIColor
Specifies the background colour for the fields view content area.

public var internalFieldBackgroundColor: UIColor
Specifies the background colour for each of the internal JPFormTextField text fields and the UIImageView displaying the card brand image. Default is UIColor.white.

public var spacePrefixPaddingForInputFields
Default is 0. Specifies additional space added between the edge of the data entry objects and the entered data itself.

public var maxSpecial: Bool
Default is false. True indicates the addition of a left-hand-side “internal border” added to the data entry fields.

public var maxSpecialWidth: CGFloat
Default is 3.0. If maxSpecial is true, then specify the width in logical points for this border.

public var maxSpecialColor: UIColor
Default is red. If maxSpecial is true, specify the colour for the additional border.

public var borderWidth: CGFloat
Default is 0.0. Specifies the border width in logical points for the control’s border.

public var borderColor: UIColor
Default is UIColor.white. Specifies the border colour for the control’s border.

public var internalFieldBorderWidth: CGFloat
Default is 0.0. Specifies the border width in logical points for the internal JPFormTextField fields.

public var internalFieldBorderColor: UIColor
Default is UIColor.white. Specifies the border colour for the internal JPFormTextField field borders.

public var cornerRadius: CGFloat
Default is 0. Specifies the corner radius value for the control’s border.


Text and Placeholders

public var font: UIFont
Sets the font used for the data entry fields, and appropriately, is used for dynamic field sizing.

public var textColor: UIColor
Default is UIColor.black. Sets the colour for the text in the data entry fields.

public var textErrorColor: UIColor
Default is UIColor.red. Sets the colour for the text in the data entry fields when this data is recognised as invalid.

public var placeholderColor: UIColor
Default is UIColor.grey. Sets the colour for the placeholder text in all fields when they are empty.

public var numberPlaceholder: String?
Sets the placeholder text for when the card number data entry field is empty.

public var expirationPlaceholder: String?
Sets the placeholder text for when the expiration year data entry field is empty.

public var cvcPlaceholder: String?
Sets the placeholder text for when the CVC code data entry field is empty.


Validation

public func isValid() -> Bool
True if JPPaymentCardField identifies itself as holding complete and valid data, false otherwise.


Miscellaneous

public func clear() -> Void
Clears the JPPaymentCardField. This results in the UI fields being cleared, the brand image being cleared and the model status being cleared.


Relationships

Inherits from: UIControl
Conforms to: JPFormTextFieldDelegate, JPSelfValidating, JPThemeProtocol


 

JPPaymentCardHorizontalField

Overview

JPPaymentCardHorizontalField is a subclass of JPPaymentCardField and fixes JPPaymentCardField 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 JPPaymentCardHorizontalField can be seen in JPPaymentCardField.

JPPaymentCardHorizontalField defines properties and behaviour for laying a JPPaymentCardField out horizontally. Because of the space available in the horizontal direction, all fields are dynamically sized (unlike JPPaymentCardVerticalField where this setting is optional).


Symbols

Creating a JPPaymentCardHorizontalField

init?( coder aDecoder: NSCoder )
Instantiate from a storyboard or Nib.

init(frame: CGRect)
Instantiate using a given frame rectangle.


Relationships

Inherits from: JPPaymentCardField
Conforms to: JPFormTextFieldDelegate, JPSelfValidating


 

JPPaymentCardVerticalField

Overview

JPPaymentCardVerticalField is a subclass of JPPaymentCardField and fixes JPPaymentCardField 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 JPPaymentCardVerticalField can be seen in JPPaymentCardField.

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


Symbols

Creating a JPPaymentCardVerticalField

init?( coder aDecoder: NSCoder )
Instantiate from a storyboard or Nib.

init(frame: CGRect)
Instantiate using a given frame rectangle.


Customisation

public var verticalPaddingBetweenFields: CGFloat
Default is 5 logical points. Sets the vertical margin between each of the payment card fields.

public var expirySubtitleText: String
Set the expiry subtitle text. Default is an empty string.

public var cvcSubtitleText: String
Set the cvc subtitle text. Default is an empty string.

public var subtitleTextAlignment: NSTextAlignment
Default if NSTextAlignment.left. Align subtitle text within the subtitles content area.

public var subtitleTextColor: UIColor
Sets the subtitle text colour. Default is UIColor.black.

public var subtitleFont: UIFont
Sets the subtitle font. Defaults to the system font of size 14.0.


Relationships

Inherits from: JPPaymentCardField
Conforms to: JPFormTextFieldDelegate, JPSelfValidating