CardFlight SDK Docs logo

Getting Started

The CardFlight SDK provides the easiest way to incorporate card-present credit transactions into a mobile application.

The main points of interaction in the SDK are the Transaction and Historical Transaction objects.

The Transaction object is used to create and process a sale or authorization. When the transaction has completed, a Historical Transaction will be returned.

The Historical Transaction object contains information about completed transactions.

  1. Create a CardFlight developer account
    • If you do not have an API Key, contact us for details.
  2. Connect your Merchant Account
  3. Integrate with the CardFlight SDK

Creating a Sale

Initialize a Transaction Parameters object with valid Credentials and an Amount.

Call beginSale on the Transaction with those Transaction Parameters.

All further interaction with the Transaction is done through your implementation of a Transaction Handler.

The transaction will proceed through the state machine as events occur. Any state with the prefix PENDING requires user action to continue.

The transaction is completed when the Completed callback is returned with a Historical Transaction.

Creating an Authorization

An authorization is a hold on cardholder funds that requires a Capture action to complete the sale and the transfer of funds from customer to merchant.

Initialize a Transaction Parameters object with valid Credentials and an Amount.

Call beginAuthorization (in place of beginSale) on the Transaction with those Transaction Parameters.

As with a Sale, all further interaction with the Transaction is done through your implementation of a Transaction Handler.

The transaction will proceed through the state machine as events occur. Any state with the prefix PENDING requires user action to continue.

The transaction is completed when the Completed callback is returned with a Historical Transaction.

Capture the Approved Authorization

Capture the authorization from the Historical Transaction object returned by the original authorization Transaction.

Call the captureTransaction method with a final Amount.

Tokenizing a Card

Call beginTokenization on the Transaction with a valid Credentials object.

All further interaction with the Transaction is done through your implementation of a Transaction Handler.

The transaction will proceed through the state machine as events occur. Any state with the prefix PENDING requires user action to continue.

You can find the card’s token on the Historical Transaction returned in the Completed callback of the Transaction Handler.

Refunding a Transaction

Refunding a transaction is easy and can be done with the Historical Transaction. Upon a completed Refund Transaction, a new Historical Transaction will be returned through that Refund Handler.

A refund must be for an approved sale (or captured authorization.)

Refunds are not available for a pre-authorization, to remove a ‘pending’ pre-authorization from a cardholders balance void the pre-authorization Historical Transaction. To capture an amount less than the pre-authorization capture with the lesser amount.

Call the refundTransaction method with an Amount and an implementation of a Refund Handler.

Voiding a Transaction

Voiding a transaction can be done using the Historical Transaction and calling the voidTransaction method.

The Historical Transaction will be updated to reflect any changes that may have occurred.

It is important to know that voiding a transaction will only work if the batch containing that transaction has not yet closed.

Once a batch has been closed (and money has been collected), you must use the refund method to return money to the customer.

Import the CardFlight SDK

CardFlight’s Android and iOS SDKs enable seamless integration of the CardFlight Gateway and CardFlight Card Readers into any mobile app.

Getting a Transaction Set Up

Steps:

  1. Import the CardFlight SDK packages
  2. Create a Credentials Object
  3. Create an Amount Object
  4. Create a Transaction Parameters Object
  5. Start a Transaction
  6. (Optionally) Connect to a Card Reader

State Machine

What is a state machine?

In simple terms, a state machine receives a series of inputs or events and returns either a state update or an error.

The Transaction State Machine manages what actions can be performed on any individual Transaction.

Any State with the prefix PENDING is awaiting user input.

States

Name Description Valid Exit State
UNKNOWN An error has occurred. Please contact CardFlight. ERROR
PENDING_TRANSACTION_PARAMETERS Transaction created. Awaiting Transaction Parameters input. PENDING_CARD_INPUT
PENDING_CARD_INPUT Transaction permissions and parameters have been set. Awaiting Card information input. PENDING_PROCESS_OPTION
PENDING_PROCESS_OPTION Transaction setup complete. Awaiting Process Option input. COMPLETED
DEFERRED[1]
PROCESSING
DEFERRED[1] Currently unsupported FINAL STATE
PROCESSING Transaction object sent through CardFlight Gateway to the Merchant Processor. Awaiting response from the processor with Transaction result. COMPLETED
COMPLETED Transaction finished. Possible Results: Completed, Aborted, Error FINAL STATE

Errors

Name Description
Invalid State Change The last action taken by the user is not allowed in the current state of the Transaction

[1] Currently unsupported. This feature will be available in a future version of the SDKs.

Transaction State Machine Diagram

Interacting with the Transaction

Transaction States

The Transaction state machine controls the active state of a Transaction. The Transaction State updates as a Transaction progresses.

States prefixed with PENDING require user input, including:

  • PENDING_TRANSACTION_PARAMETERS
  • PENDING_CARD_INPUT
  • PENDING_PROCESS_OPTION.

Transaction Callbacks

Interaction with a Transaction is entirely based on callbacks received through the Transaction Handler.

Card Reader Availability

When a new card reader becomes available or an existing card reader becomes unavailable, an array of Card Reader Info objects will be passed, until a Transaction is in the Pending Process Option state.

Card Input Method Availability

An array of available Card Input Methods is passed each time the allowed list changes. This list is determined by your Credentials (Merchant Processor dependent) and available card readers.

Card Reader / Keyed Entry Events

A Card Reader Event is received when an action is taken on the Card Reader. (e.g. connected, swiped)

A Keyed Entry Event is received when the input on a Keyed Entry View changes. When Keyed Entry Event CARD_COMPLETE is received, the Keyed Card Info is usable.

Transaction Results

The Transaction Result is received at the end of the Transaction once. This will happen only in the COMPLETED Transaction State.

Request Display messages

Messages passed through the Request Display callback should be displayed to the user and no application logic should be applied.

Card AID objects available

An array of Card AID objects may be passed when a dipped or tapped card has multiple applications available for processing. This is common in international cards.

  • When received, the list must be displayed to the user and one must be selected before the Transaction can proceed.

Request Process Option callback with Card Info object

When the Card Info object is returned through the Request Process Option callback, user input is required to select whether or not to process the Transaction. This card information should be displayed to the user to verify that it is correct.

CVM requested

If a CVM is requested, the user should receive a prompt to sign, for example. The Transaction will not complete until this has been provided.

Migrating from CardFlight SDK v3

The CardFlight SDK has been completely rebuilt with version 4.

Migration from the old SDK requires a full reintegration.

While most functionality has been carried over, interaction with objects has changed.

One Code Path abstracts transaction complexity

Separated Swipe and EMV charge flows are replaced by one abstracted Transaction flow

In previous versions of the SDKs, there are multiple code paths to create and manage a charge. A swipe charge is run though interaction with a Card class. Capturing a swiped card or running an EMV charge is through interaction with a Reader class.

In SDK v4, the Transaction class processes all transactions regardless of the Card Input Method.

The examples provided show a side by side comparison.

Transaction Parameters

Charge details hash is replaced by Transaction Parameters object

In previous versions of the SDKs, a hash of charge details was passed around to charge a card or start an EMV transaction.

In SDK v4, create a Transaction Parameters object to store and use with the transaction.

Credentials

API Keys and Account Tokens are now managed by a Credentials object

In previous versions of the CardFlight SDKs, Merchant Account API Keys and Account Tokens must be stored by the SDK developers and were set using a session manager.

In SDK v4, we have introduced the Credentials object to manage these Merchant Account details for you. To process a transaction using a specific Merchant Account, just attach the associated Credentials object to the Transaction object in use.

Transaction requested Processing Options

Charge the Card (swipe) and Process/Cancel Transaction (EMV) are replaced by a Processing Option requested by the Transaction

In previous versions of the SDK, a charge was sent to the merchant processor by calling charge card (swipe), or providing a process decision of yes. (EMV)

In SDK v4, a Transaction requests a Process Option selection of Process, Abort, or Defer[1].

[1]This feature will be available in a future release.

Transaction Messaging

User messaging may now be provided for any transaction

In previous versions of the SDK, only EMV transactions provided callbacks with messaging to display during charge processing.

In SDK v4, all Transactions will provide terminal messaging which is expected to be displayed to the user.[2]

[2]The message is provided as a string and not an enum as it is intended to be displayed to the user as it is received and should not trigger events or actions.

Keyed Card View

Payment View object replaced by Keyed Entry View

In previous versions of the SDKs, a user key enters card information through interaction with a Payment View object.

In SDK v4, the view has been renamed to Keyed Entry View, is not constructible, and is only accessed through a Transaction.

Persistent Historical Transactions

Charge and Charge Tokens have been replaced by a persistent Historical Transaction returned on every completed Transaction

In previous versions of the SDKs, a charge token was returned on an approved result.

In SDK v4, a Historical Transaction object is created for every completed transaction (regardless of result). This Historical Transaction is a record of the Transaction attempt and is the object from which you can attempt a capture, refund, or void.

Capturing, Refunding, and Voiding

Charge Token management for Capture, Refund, and Void charge operations is replaced by a Historical Transaction object

In previous versions of the SDKs, capture, refund, or voiding a charge occurs through interaction with the Charge class and requires the charge token from the original charge.

In SDK v4, a Historical Transaction object returned from the Transaction class contains each of these three methods, making these actions easier to perform.

Cash Transactions

Cash is not supported in SDK v4.

Vaulting/Tokenization

Card Tokens are now located on a Historical Transaction object

In previous versions of the SDKs, tokenizing a card was done on the Card class.

In SDK v4, a Historical Transaction object returned from the Transaction class contains a cardToken field that is populated when the Transaction was started by calling beginTokenization.

Vaulting is currently unsupported in SDK v4. [3]

[3] This feature will be available in a future release.

Overview

The Transaction object is used to process any charges you want to make. It is the main point of interaction with the CardFlight SDK.

***- Begin Sale / Begin Authorization

  • The overview of steps to complete a transaction are …
  • Keyed Card Entry / no hardware overview… ***

Initialize a Transaction

Assign a Transaction Handler to a new Transaction object. This value can be changed using the Attach Transaction Handler method.

Attach Transaction Handler

Transaction Handler callbacks:

  • Transaction State Updated
    • Passes: Transaction State and An Optional Error
    • Called when a new Transaction State is entered or an illegal call was made. An error will occur when an action that is not allowed in the current state is attempted.
  • Card Reader Array Updated
    • Passes: Array of available Card Reader Info objects
    • Called when a Card Reader is detected or disconnected.
  • Card Input Method Array Updated
    • Passes: Array of available Card Input Methods
    • Called when the list of available Card Input Methods available changes. Usually caused by connecting or disconnecting a Card Reader.
  • Card Reader Event Received
    • Passes: Card Reader Info object and a Card Reader Event
    • Called when a Card Reader Event occurs.
  • Key Entered Event Received
    • Passes: Key Entered Event enumeration value
    • Called when an input is received on the Key Entered Card View.
  • Completed
    • Passes: Historical Transaction object
    • Called when the Transaction enters the state Completed and has generated a Transaction Result.
  • Request Display Message
    • Passes: Message
    • Called when a message should be displayed to the cardholder. All messages must be shown.
  • Request Card AID Selection
    • Passes: Array of available Card AID objects
    • Called when the card presented contains more than one available AID. Cardholder must select the AID to use with a Transaction.
  • Request Process Option
    • Passes: Card Info object
    • Called when the Transaction is in the state Pending Process Option and is ready to be processed through the CardFlight Gateway. The details of the [Card Info object] should be verified by the cardholder before proceeding.
  • Request CVM
    • Passes: CVM enumeration value
    • Called when the Transaction is in the state Processing and is waiting on the user to provide a CVM.

Card Reader Event enumeration:

Value Definition
Disconnected Reader disconnected
Connecting Reader is connecting
Connected Reader connected
Connection Errored Reader connection attempt failed
Card Swiped Card swipe was received by the reader
Card Swipe Errored Swipe attempt was not received
Card Inserted Card is inserted into the reader
Card Insert Errored A card was inserted into the reader but could not be read
Card Removed The inserted card was removed from the reader
Card Tapped A card Tap was received by the reader
Card Tap Errored A card Tap was received by the reader but could not be read
Battery Status Updated Reader battery status was updated
Update Started The reader started updating
Update Completed The reader completed updating
Bluetooth Permission Not Granted The necessary bluetooth permission has not been granted (Android Only)
Bluetooth Admin Permission Not Granted The necessary bluetooth admin permission has not been granted (Android Only)
Record Audio Permission Not Granted The necessary record audio permission has not been granted (Android Only)
Access Coarse Location Permission Not Granted The necessary access coarse location permission has not been granted (Android Only)
Write External Storage Permission Not Granted The necessary write external storage permission has not been granted (Android Only)

Begin a Transaction

When a Transaction is in state PENDING TRANSACTION PARAMETERS, call Begin Sale or Begin Authorization with a valid Transaction Parameters object to begin a new sale or authorization. If an invalid Transaction Parameters object is attached, the Transaction will complete with an error. Both Sale and Authorization Transaction Types execute the same and both generate a Historical Transaction object on completion.

When a Transaction is in state PENDING TRANSACTION PARAMETERS, call Begin Tokenization and attach valid a Credentials object to obtain a token for a card. Tokens will only be generated for Braintree and Stripe merchant accounts.

A sale will result in the transfer of funds from a cardholder to merchant.

An authorization will result in a hold on cardholder funds that cannot be spent by the cardholder. An authorization requires a Capture on the Historical Transaction to move the funds from the cardholder to the merchant.

A tokenization will not transfer any funds and will instead generate a token for use by Braintree or Stripe.

Use a Card Reader

Call Scan Bluetooth Card Readers to discover available Bluetooth Readers.[1] (Bluetooth only)

Call Select Card Reader on the Transaction with a [Card Reader Info object].[2]

Specify the Card Reader Model of the connected reader. If not specified, a connection will be attempted for each Card Reader Model supported. (Audio Jack only)

[1] To be available: Bluetooth LE Readers (i.e. Swift B200, Swift B250) must be powered on, non-LE Bluetooth Readers (i.e. Bold B500, Bold B550) must be paired to the device and turned on.

[2] When reader availability changes, the Transaction Handler will return the [Card Reader Array Updated] callback with an array of available Card Reader Info objects.

Use a Keyed Card

While a Transaction is in state PENDING TRANSACTION PARAMETERS or PENDING CARD INPUT, call the Keyed Entry View method and listen for Keyed Entry Events callbacks on the Transaction Handler.

Optionally enable zip code in the parameters for the Keyed Entry View method.[1]

Call the [Use Keyed Card Info] method once the Transaction is in the state PENDING CARD INPUT.

Keyed Entry Event enumeration:

Value Definition
Card Incomplete The card information provided is not yet complete
Card Complete The card information provided has completed card number, expiration date, and CVV value

[1] Zip code formats are not standardized, this field has no set minimum length and any input will be accepted.

Select a Card AID

When a Transaction is in the state PROCESSING and the Transaction Handler returns the Request CVM callback, call the Select Card AID method with the cardholder selected card AID object to proceed with processing.

The AID (Application Identifier) is used to determine which payment system to use. In the event that a card contains multiple AID options (e.g. an international card with a different home currency) the Transaction Handler will pass the Request Card AID Selection callback and return a list of available card AID objects.

Select a Process Option

When a Transaction is in the state PENDING PROCESS OPTION, call Select Process Option and provide a process option to proceed.

Display the amount and card details for confirmation when the Request Process Option callback is received in the Transaction Handler.

DEFERRED TRANSACTIONS ARE AT THE RISK OF THE MERCHANT
A deferred transaction is not processed when the cardholder is present. When a reliable internet connection is restored a transaction that is declined or results in an error cannot be retried and the funds will be lost. Second, the transaction fraud liability may be shifted to the merchant as only KEY and SWIPE Card Input Methods are supported.

Process Option enumeration:

Value Definition
Process Attempt to charge the card using the CardFlight Gateway
Defer Save the Transaction details for later processing
Abort Don’t process transaction

Attach CVM

When Request CVM callback is requested by the Transaction Handler, the cardholder should be prompted to provide signature verification.[1]

Call Attach CVM with the raw cardholder verification data collected from the cardholder.

CVM enumeration:

Value Definition
Unknown CVM is Unknown
None No CVM is required by the transaction
Signature Signature has been requested by the transaction

[1]For Key Entry and Swipe Transactions the request is determined by the Require Signature boolean set to true on the Transaction Parameters. For Dip and Tap Transactions the CVM requirement for each transaction is determined by the chip data on the card.

Getting the Credentials

The Transaction object holds on to the Credentials supplied once begin has been called. This is important so that you can refresh the Credentials if the Transaction has already started.

Using Reachability

When internet connection is unreliable or unavailable, a transaction can be deferred for later processing with the help of Reachability. Only SWIPE and KEY transactions can be deferred.

Setting a Transaction into RESTRICTED reachability presents only KEY and SWIPE (if available) as the Card Input Methods. At this point, the Transaction can be deferred and resumed once a reliable connection is available.

See Select a Process Option DEFER.

Setting a Transaction into FULL reachability will enable all available Card Input Methods and operate normally.

List of Reachability Enumeration Values:

Value Definition
FULL Transaction will function normally
RESTRICTED Transaction will function with only KEY and SWIPE Card Input Methods

Initialize An Amount

Set an Amount object to a number representing a dollar amount to use.

Amounts are rounded according to banker’s rounding if needed.

Getting the Number

Return the number value of an Amount object.

This is useful for making sure the number you created the Amount object with is the same as what it saved.

Getting the AID Name

Return the AID (Application Identifier) of a card.

The AID is used to determine which payment system to use. Multiple AID selection is rarely encountered, e.g. an international card with a different home currency. If multiple AIDs are present on a card, the Transaction object will prompt for AID selection and return a list of Card AID objects.

Overview

A representation of a customer’s payment card information. The Card Info object has no writable parameters and only contains information that is out of PCI-scope.

Card information available:

  • First 6 digits of the card number
  • Last 4 digits of the card number
  • Card Brand
  • Cardholder Name[1]
  • Card Input Method
  • Card Reader Info object[2]

[1] The cardholder name is not always available and can be set to null
[2] The Card Reader Info object is only available when the card information was obtained using a card reader

Get Card Number

Return the card number, stored on the Card Info object.

The first six digits and last four digits of the card number are available. The full card number is not stored to help keep apps integrating the CardFlight SDK compliant with the PCI security standards.

Get Card Brand

Return the Card Brand, stored on the Card Info object.

Exposed to a developer using the Card Brand enumeration.

Card Brand enumeration:

Value Bin Range Length Short Name
Unknown N/A N/A Unknown
American Express 34, 37 15 Amex
China UnionPay 62 16-19 UnionPay
Diners Club Carte Blanche 300-305 14 Diners
Diners Club International 300-305, 309, 36, 38-39 14 Diners
Diners Club 54-55 16 Diners
Discover Card 6011, 622126-622925, 644-649, 65 16, 19 Discover
InterPayment 636 16-19 InterPayment
InsTapayment 637-639 16 InstaPayment
JCB 3528-3589 16 JCB
Maestro 50, 56-69 12-19 Maestro
Dankort 5019 16 Dankort
MasterCard 2221-2720, 51-55 16 MC
Visa 4 13, 16, 19 Visa
UATP 1 15 UATP
Verve 506099-506198, 650002-65027 16, 19 Verve
CardGuard 5392 16 CardGuard

Get Cardholder Name

Return the cardholder name, stored on the Card Info object. This parameter is optional and may not be populated.

The availability and format of cardholder name is dependent on the card and the reader hardware used to capture the card information. Keyed card information will not contain a cardholder name.

Get Card Input Method

Return the Card Input Method, stored on the Card Info object.

Exposed using the Card Input Method enumeration.

Card Input Method enumeration:

Value Definition
Unknown Transaction has an Unknown capability
Key Transaction can be processed using keyed data
Swipe Transaction can be processed using Swipe
Swipe Fallback Transaction can be processed using Swipe Fallback
Dip Transaction can be processed using chip
Tap Transaction can be processed using NFC

[1] Swipe Fallback is a swipe transaction that is taken after an EMV chip read has failed 3 attempts.

Overview

A representation of the card reader hardware used to capture card information. The Card Reader Info object has no writable parameters.

Card Reader information available:

  • Name of the card reader
  • Card Reader Type
  • Card Reader Model
  • Battery Status
  • Bluetooth Device object [1]

[1] The Bluetooth Device object is only available when the Card Reader Type is Bluetooth

Get Reader Name

Return name, stored on the Card Reader Info object.

For Audio Jack devices (i.e. Element A100, Eclipse A200) this name will be generic. For Bluetooth devices (i.e. Bold B500, Bold B550) the name is the device family name and the last 4 digits of the serial number on the device (e.g. Bold 1234). If the name is Unknown the device has not yet been identified.

Get Reader Type

Return the Card Reader Type, stored on the Card Reader Info object.

Exposed using the Card Reader Type enumeration.

Card Reader Type enumeration:

Value Definition
Unknown The class of hardware is Unknown
Audio Jack The hardware is in the audio jack class
Bluetooth The hardware is in the bluetooth class

Get Reader Model

Return the Card Reader Model, stored on the Card Reader Info object.

Exposed using the Card Reader Model enumeration.

List of Card Reader Model enumeration values:

Value Definition Type Supported Payment Methods
Unknown The reader type is Unknown or none N/A Unknown
Shuttle The reader type is Shuttle Audio Jack Swipe
BTMag The reader type is BTMag Audio Jack Swipe
A100 The reader type is the Element A100 Audio Jack Swipe
A200 The reader type is the Eclipse A200 Audio Jack Swipe, Dip
B200 The reader type is the Swift B200 Bluetooth Swipe, Dip
B250 The reader type is the Swift B250 Bluetooth Swipe, Dip, Tap
B500 The reader type is the Bold B500 Bluetooth Swipe, Dip
B550 The reader type is the Bold B550 Bluetooth Swipe, Dip, Tap

Get Reader Battery Status

Return the Battery Status, stored on the [Card Reader Info object].

Exposed using the Battery Status enumeration.

List of Battery Status enumeration values:

Values Description
Unknown The battery status is Unknown
Low The battery has little charge remaining, charge now
Nominal The battery has charge remaining
Plugged In The battery is currently running off of an AC power supply

Listen for the Battery Status Updated card reader event to be informed when the reader’s battery status has changed.

Overview

An object created to authenticate a Transaction object, once setup the Credentials object remains valid for 6 hours.

Available parameters to set:

  • API Key of CardFlight account
  • Account Token of Merchant on CardFlight account

Initialize Credentials

Assign an API Key and Account Token to the Credentials object. When called, a network request is made to validate the parameters provided with the CardFlight Gateway.

Refresh Credentials

Re-validate the API Key and Account Token stored on the [Credentials object] against the CardFlight Gateway. Useful after [Credentials object] time out or an error has occurred.

Check Validation Errors

Return error that occurred during the last validation attempt, for the Credentials object.

A populated return value indicates an unsuccessful validation attempt and the [Credentials object] should be refreshed or corrected according to the error message.

Get (Merchant Account) Name

Return the Merchant Account Name, on the Credentials object.[1]

The name is set when a merchant account is onboarded to the CardFlight gateway.

[1] The method will only return a value if the Credentials object is valid

Persist Credentials

For Android:

Helper methods can be used to serialize and deserialize the Credentials object for storage and retrieval.

When serialized the object is broken down into raw data and returned as a byte array. When retrieving the raw data, the helper method will accept the byte array and return a Credentials object identical to the original.

For iOS:

The Credentials object has been setup so it can be stored using NSKeyedArchiver.

Overview

The Historical Transaction object is created to represent the record of a completed Transaction.

Void and Refund can be performed against the Historical Transaction returned on an APPROVED SALE Transaction.

Void and Capture can be performed against the Historical Transaction returned on an APPROVED AUTHORIZATION Transaction.

Note: An APPROVED AUTHORIZATION will result in a hold on a cardholder’s account for the amount passed in the Transaction Parameters, Capture will move the money from Cardholder to Merchant.

Available information:

  • Result of the Transaction
  • Decline message [1]
  • Error that occurred [2]
  • Date when the Transaction was created
  • Date when the Transaction was processed
  • UUID of the Transaction
  • URL of the signature data [3]
  • Card Info used by the Transaction
  • Card Reader Info used by the Transaction
  • Transaction Parameters used by the Transaction
  • Type of Transaction
  • Credentials used by the Transaction

[1] Decline message is only populated if the result was declined.
[2] Error is only populated if the result was error.
[3] Signature URL is only populated if a signature was attached to the Transaction.

Get Historical Transaction Result

Return the Result as well as any associated decline messages or errors, stored on the Historical Transaction object.

The decline or error message will only be populated if the result was decline or error respectively.

Transaction Result enumeration:

Value Definition
Unknown The result is Unknown
Approved The transaction was approved by the host
Declined The transaction was declined by the host
Errored Something went wrong when processing the transaction
Aborted The transaction was aborted in the Pending Process state

Get Historical Transaction Dates

Return the Created At and Transacted At (processed at) dates, stored on the Historical Transaction object.

The Transacted At date will not be populated if the Transaction was never processed. (E.g. an aborted Transaction or the Transaction was unable to connect to the CardFlight Gateway.)

Get the Historical Transaction UUID

Return the UUID, stored on the Historical Transaction object.

Useful for debugging purposes.

Get Historical Transaction Signature URL

Return the Signature URL, stored on the Historical Transaction object.

This value will not be populated if no signature was provided.

Get Historical Transaction Card

Return the Card Info object, stored on the Historical Transaction object.

Get Historical Transaction Card Reader

Return the Card Reader Info object, stored on the Historical Transaction object.

No Card Reader will exist if the Transaction was completed using keyed card info.

Get Historical Transaction Parameters

Return the Transaction Parameters object, stored on the Historical Transaction object.

Get Historical Transaction Type

Return the Transaction Type, stored on the Historical Transaction object.

Transaction Type enumeration:

Value Definition
Unknown The transaction type is Unknown
Sale The transaction is a regular sale (money from customer)
Refund The transaction is a refund (money back to customer)
Void The transaction is a void which cancels a sale if the batch has not already closed
Authorization The transaction is an Authorization that has not been captured

Get Historical Transaction Card Token

Return the card token, stored on the Historical Transaction object.

No card token will exist if the Transaction was not started using beginTokenization or if the processor does not support tokenization.

Void a Transaction

The Historical Transaction can void the Transaction, which will attempt to void the Transaction on the CardFlight Gateway. If successful, the Transaction Type will be changed to Void.

To void a Transaction, that Transaction’s batch must not have already closed.

Refund a Transaction

The Historical Transaction can refund the Transaction, which will return payment to the cardholder. The refund can be for any portion of the original Transaction, up to 100% of the Amount.

Capture an Authorization

Call the Capture method with a final amount against an APPROVED AUTHORIZATION Historical Transaction to transfer held funds from cardholder to merchant.

An APPROVED Capture request will return the same Historical Transaction with Transaction Type updated to ‘SALE’.

A DECLINED/ERRORED Capture will return the same Historical Transaction unchanged, with type AUTHORIZATION.

An APPROVED AUTHORIZATION will result in a hold on a cardholder’s account for the amount passed in the Transaction Parameters, Capture will move the money from Cardholder to Merchant.

Persist Historical Transaction

For Android:
The Historical Transaction object has helper methods that are used to easily serialize and deserialize the object so that it can be stored. When the object is serialized, it is broken down into raw data and given in a basic format. Then, when retrieving the raw data, the Historical Transaction object also has a method that will deserialize itself using that data and return a Historical Transaction object that is identical to the original.

For iOS:
The Historical Transaction object has been setup so it can be stored using NSKeyedArchiver.

Overview

The Transaction Parameters object is created to provide a Transaction with all necessary parameters when it begins.

Available parameters to set:

  • Amount to process
  • Credentials
  • Callback Url (optional) [1]
  • Require a signature boolean [2]
  • Metadata map [3]

[1] If a callback url is specified, the CardFlight Gateway will provide that url with all transaction details.
[2] The boolean for requesting a signature is only honored for keyed and swiped transactions. The CardFlight Gateway decides whether to request a signature for all other card input methods used.
[3] The metadata map is used to store any additional information with a Transaction on the CardFlight Gateway. This data will also be sent to the callback url if one was provided.

Initialize Transaction Parameters

Assign any non-null Amount object and non-null Credentials object to the Transaction Parameters object.

Set a Callback URL

An optional parameter, when set the Callback URL is provided the Transaction information when a Transaction has been processed through the CardFlight Gateway.

When retrieving the Callback URL, the value will not be populated if a valid URL has not been specified.

Require a Signature

Require a signature (as CVM) to complete Transaction processing. (Key or Swipe only)

If no value is set, the default value of false will be used.

For dip and tap Transactions CVM request requirements are determined by the data on the EMV chip

Adding Metadata

Assign a list of key-value pairs, to pass with each request made to the CardFlight Gateway, to a Transaction Parameters object.

Useful for storing and later retrieving using the Historical Transaction object. This data will also be passed along to any Callback URL that may have been specified.

List of Enumerations