CardFlight's API is based around keeping it as simple as possible while keeping the highest level of security at the forefront of all that we do. Take out the pain of PCI-compliance when building your app.
Authentication is done through your API Keys and processing is done through the Account Tokens. All connections to CardFlight's API is done through HTTPS over HSTS.
Setup
Install the library
Android Studio
Copy CardFlight SDK into root project directory ( cardflight-sdk folder).
Add CardFlight SDK directory to "settings.gradle" of the project ( "include ':cardflight-sdk'" ).
Add CardFlight SDK to "build.gradle" dependencies and perform sync ( "compile project(':cardflight-sdk')" ).
Sync gradle.
Set Credentials
Description
Sets the API key and account token for the entire session. This only needs to be called once, but it can be called multiple times to use different merchant accounts.
Arguments
apiToken: String of the API token
accountToken: String of the account token
handler: Handler that gets called when API key and account token have been set.
Create a swiped/keyed charge
Capture a card
Description
This callback is triggered after a swipe. If a card can be successfully generated the card param is populated, else the error is populated with the resulting error.
Parameters
error: CardFlightError object populated if the card could not be generated
card: Card object that was generated from the swipe
Example
@Override
public void readerCardResponse(Card card, CardFlightError error) {
if (card != null) {
saveCard(card); // Implement this
} else {
Toast.makeText(mContext, "Error: " + error.toString(),
Toast.LENGTH_SHORT).show();
}
}
Charge the card
Description
Method to charge a card with the details in the chargeDetails HashMap.
Parameters
context: Application context
chargeDetails: HashMap containing charge details
paymentHandler: CardFlightPaymentHandler to be called after completion
chargeDetails Parameters:
amount - Integer containing amount to charge ($2.50 = 250)
callback_url - Optional - String of callback URL to trigger
description - Optional - String of charge description
customer_id - Optional - String of customer ID being charged
currency - Optional - String of currency code, defaults to USD
merchant_id - Optional - String of the MID accepting the charge
service_fee - Optional - Double containing the fee to charge
Example
HashMap chargeDetailsHash = new HashMap();
chargeDetailsHash.put("amount", price);
if (mCard != null) {
mCard.chargeCard(mContext, chargeDetailsHash,
new CardFlightPaymentHandler() {
@Override
public void transactionSuccessful(Charge charge) {
Toast.makeText(mContext, "Charge successful",
Toast.LENGTH_SHORT).show();
mCharge = charge; // Save charge object
continueTransaction(); // Implement this
}
@Override
public void transactionFailed(CardFlightError error) {
Toast.makeText(mContext, error.toString(),
Toast.LENGTH_SHORT).show();
}
}
);
} else {
Toast.makeText(mContext, "Unable to process payment - no card present",
Toast.LENGTH_SHORT).show();
}
Assign an OnCardKeyedListener to the PaymentView to trigger an action when the field entry is completed. It is worth noting that the recommendation would be to enable the ability to process the card when onCardKeyed is triggered, rather than process the payment right away.
Example
Button processButton = (Button) findViewById(R.id.processButton);
PaymentView mPaymentView = (PaymentView) getView()
.findViewById(R.id.paymentview);
mPaymentView.enableZipCode(true);
mPaymentView.setOnCardKeyedListener(new OnCardKeyedListener() {
@Override
public void onCardKeyed(Card card) {
HashMap chargeParamsMap = new HashMap<>();
chargeParamsMap.put("amount", amount);
chargeParamsMap.put("callback_url", callbackUrl);
// cardFlightPaymentHandler must be defined
processButton.setEnabled(true);
processButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
card.chargeCard(getApplicationContext(), chargeParamsMap,
cardFlightPaymentHandler);
}
});
}
});
Captured Card Details
Description
Add a PaymentView to your layout file to key in card details.
Set the hardware reader to begin waiting to receive a swipe. Legacy method, should not be used for customers with EMV-compatible readers.
For integrations with an EMV-capable reader use
beginEMVTransaction instead.
Swipe timeout
Description
Optional method to set timeout period in seconds. Default is TRUE.
Cancel transaction
Description
Manually cancel the swipe process before the timeout duration has been reached or cancels an EMV transaction
Tokenize a card
Please note that the tokenization is only supported with Stripe. If you would like to store the credit card data with another merchant account type, please use the vaulting option.
Description
Method to create a card token that can be saved and used later. On success the cardToken variable contains a value that can be stored and used later.
Method to create a card vault ID that can be saved and used later. On success the cardVaultID variable contains a value that can be stored and used later.
Charge.processVoid(
getChargeToken(),
new CardFlightPaymentHandler() {
@Override
public void transactionSuccessful(Charge charge) {
Toast.makeText(getApplicationContext(), "Transaction voided",
Toast.LENGTH_SHORT).show();
}
@Override
public void transactionFailed(String errorMessage, int errorCode) {
Toast.makeText(getApplicationContext(), errorMessage,
Toast.LENGTH_SHORT).show();
}
});
Create an EMV charge
Please note that EMV charges are only supported by only some of our merchant account type. Please contact support@cardflight.com for an updated list.
Begin EMV transaction
Description
Begin a transaction with the requested amount. If the merchant account is enabled for EMV it will begin an EMV transaction, otherwise a traditional swipe transaction is initiated.
If an EMV transaction is performed, EMV callbacks will be utilized, otherwise traditional swipe callbacks are implemented. Returns an error if an EMV reader is not connected.
If you do not have an EMV-capable reader, use
beginSwipe instead.
Parameters
amount: double of the amount to charge
chargeHashMap: HashMap of charge data for the transaction
description - Optional - String of charge description
metadata - Optional - HashMap of extra transaction information
Create a charge
Description
This callback is triggered after an EMV transaction completes. It contains a CFTCharge on success (either approved or declined) and an NSError if the charge fails. Required for EMV transactions.
Parameters
result: Charge object containing the completed charge
Example
@Override
public void emvTransactionResult(Charge charge, boolean requiresSignature,
CFEMVMessage message) {
if (charge != null) {
// Approval flow
} else {
switch (message) {
// add cases for each outcome
}
}
}
Confirm the charge
Description
After recieving the card information for an EMV transaction, send a confirmation to continue processing the transaction.
Parameters
isConfirmed: BOOL to confirm the card info
Upload a signature
Description
Upload a signature after a charge has been processed.
Parameters
context: application context
token: (String) token of previously approved charge
signatureData: (String) representation of signature image
signatureHandler: CardFlightSignatureHandler called back after the response from upload
Example
String signature = Base64.encodeToString(signatureImgBytes, Base64.DEFAULT);
Charge.sendSignatureData(mContext, successfulCharge.getToken(), signature,
new CardFlightSignatureHandler() {
@Override
public void signatureSuccessful() {
showReceipt(); // Implement this
}
@Override
public void signatureFailed(CardFlightError error) {
Toast.makeText(mContext, "Signature upload failed: "
+ error.getMessage(), Toast.LENGTH_SHORT).show();
}
});
Card Dipped Callback
Description
This callback is triggered when a card is inserted into the reader when an EMV transaction is active.
Card Removed Callback
Description
This callback is triggered whenever the dipped card is removed from the reader. Useful for ensuring the card is removed at the end of an EMV transaction, but will be called anytime a card is removed. Required for EMV transactions.
Application Selection Callback
Description
This callback is triggered if the ICC card contains more than 1 supported AID. An array is passed for selection by the customer. Call emvSelectApplication: to select an AID. Required for EMV transactions.
Parameters
appList: ArrayList of Strings containing application names, sorted by priority
Example
@Override
public void emvRequestApplicationSelection(ArrayList appList) {
int selection = selectAID(appList); // Implement method to select AID
Reader.getDefault(mContext)
.emvSelectApplication(selection);
}
Select Application Response
Description
Call this method from the Application Selection Callback with the chosen application index. This method selects which AID to use on the ICC chip if there are multiple AIDs present.
Parameters
applicationIndex: Integer index of the AID in the ArrayList given by the emvRequestApplicationSelection callback
EMV message callback
Description
This callback is triggered whenever the terminal requests a message be displayed to the user. These messages should be displayed whenever possible. Required for EMV transactions.
Parameters
message: CFEMVMessage enumeration containing a message to display to the user
Example
@Override
public void emvMEssage(CFEMVMessage message) {
Toast.makeText(mContext, message.getMessage(),Toast.LENGTH_SHORT)
.show();
}
Card response callback
Description
This callback is triggered when card info from a credit card dipped during an EMV transaction is read. Display the information contained in the HashMap to the user and call emvProcessTransaction to accept or reject this card for processing. Required for EMV transactions.
The information can be accessed dynamically or by using the following variables found in com.getcardflight.util.Contants:
FIRST_SIX: String containing the first 6 digits of the card number
LAST_FOUR: String containing the last 4 digits of the card number
CARD_TYPE: String containing the type of the card (such as Visa, Discover, etc.)
Parameters
info: HashMap containing information about the card to display to the user
Error callback
Description
This callback is triggered if a non-fatal error occurs during an EMV transaction. Required for EMV transactions.
Parameters
error: CardFlightError passed from the terminal
Connecting to the reader
Low Battery Callback
Description
This callback is triggered if the battery in the terminal is low. It may still be possible to run a transaction, however the battery should be charged as soon as possible. Required for EMV transactions.
Reader Attached Callback
Description
This callback is triggered when a reader is detected by the SDK, but the reader is not ready to receive commands yet.
Reader Is Connecting Callback
Description
This callback is triggered when the SDK begins the connecting process with the reader.
Reader Connected Callback
Description
This callback is triggered when the connection process is complete. An error is returned if the process did not complete successfully.
Swipe Is Detected Callback
Description
This callback is triggered when a swipe is detected but before it's been processed.
Reader is diconnected
Description
This callback is triggered when a reader is unplugged.
Instantiate with a specific reader type
Description
Initialization method with optional parameter to set the type of reader being used for faster connections. Defaults to auto connect.
Use Bluetooth reader
Description
Method to set the SDK to connect to Bluetooth readers. The SDK can be set to connect to either Bluetooth or audio jack readers. The default is audio jack. Calling this method with TRUE will enable Bluetooth readers, calling it with FALSE will disable Bluetooth and reenable audio jack readers. Can be called any time a transaction is not in progress.
Retrieve list of paired compatible Bluetooth devices
Description
While many readers can be paired with a device at the same time, only one can be connected at a time for transaction processing. This method will return an array containing the list of compatible paired readers. From that, the desired reader can be connected to using selectBluetoothDevice. A ReaderType can be passed to limit the list to only one type of reader.
Connect to a choosen Bluetooth reader
Description
After using getBluetoothDevices to get the list of paired readers, use this method to select one to attempt to connect with. If the connection process fails, additional attempts will not be made until this method is called.
Debugging
Log output
Description
Optional callback to reroute logging messages to a file instead of to the console.
Parameters
handler: LoggingHandler interface handler.
SDK Version
Description
Convenience method to return the current version number of the SDK.
API Token
Description
Convenience method to return the current API token.
Account Token
Description
Convenience method to return the current Account token.
Logging mode
Description
Pass true to enable developer logging mode to the console.
if (error.getCode() == CardFlightError.SWIPE_TIMEOUT.getCode()) {
restartReader(); // Implement this
} else if (error.getCode() == CardFlightError.DEVICE_TIMEOUT.getCode()) {
readerTimedOut(); // Implement this
} else if (error.getCode() == CardFlightError.SWIPE_ERROR.getCode()) {
reswipe(); // Implement this
}
Introduction
CardFlight's API is based around keeping it as simple as possible while keeping the highest level of security at the forefront of all that we do. Take out the pain of PCI-compliance when building your app.
Authentication is done through your API Keys and processing is done through the Account Tokens. All connections to CardFlight's API is done through HTTPS over HSTS.
Setup
Install the library
The recommended method of installing the CardFlight SDK is via
CocoaPods.
Manual installation is also possible by adding the
libCardFlightLibrary.a
and all header files into your application.
Additionally, include the following frameworks:
AVFoundation.framework
AudioToolbox.framework
MediaPlayer.framework
MessageUI.framework
ExternalAccessory.framework
CoreGraphics.framework
libstdc++.6.0.9.dylib
The CardFlight SDK is broken into easy-to-manage components. You
just include the ones that you want to use in the header files of
the classes that need to access those components.
You will also need to set the a delegate for CFTReader to handle
responses from the hardware card reader.
Set Credentials
Description
Sets the API key and account token for the entire session. This only needs to be called once, most likely in applicationDidFinishLaunching, but it can be called multiple times to use different merchant accounts. The emvReady variable will indicate if the merchant account supports EMV. Transactions should not be processed until the completion block is called.
Arguments
cardFlightAccountToken (NSString, required)
cardFlightAccountToken (NSDictionary, required)
completed (Block, required)
Example
Create a swiped/keyed charge
Capture a card
Description
This callback is triggered after a swipe. If a card can be successfully generated the card param is populated, else the error is populated with the resulting error.
Charge the card
Description
Method to charge a card with the details in the chargeDictionary.
Parameters
failure: Block containing NSError, executed on failure
success: Block containing CFTCharge, executed on success
Optional method to set whether reader times out while waiting for a swipe after 20 seconds. Default is YES.
Cancel transaction
Description
Manually cancel the swipe process before the timeout duration has been reached or cancels an EMV transaction.
Tokenize a card
Please note that the tokenization is only supported with Stripe. If you would like to store the credit card data with another merchant account type, please use the vaulting option.
Description
Method to create a card token that can be saved and used later. On success the cardToken variable contains a value that can be stored and used later.
Parameters
success: Block executed on tokenize success
failure: Block containing NSError that is executed on tokenize failure
Vault a card
Description
Method to create a card vault ID that can be saved and used later. On success the cardVaultID variable contains a value that can be stored and used later.
Parameters
success: Block executed on vault success
failure: Block containing NSError that is executed on vault failure
Refund a charge
Description
Refund a charge by passing in the charge token and amount to refund in dollars and cents.
Parameters
token: Charge token to be refunded
amount: NSDecimalAmount of amount to be refunded
success: Block containing CFTCharge, executed on success
failure: Block containing NSError, executed on failure
Void a charge
Description
Void a charge by passing in the charge token to void.
Note: Charges are only available to void until they have been batched. After batching a transaction can only be refunded.
Parameters
success: Block containing CFTCharge, executed on success
failure: Block containing NSError, executed on failure
Create an EMV charge
Please note that EMV charges are only supported by only some of our merchant account type. Please contact support@cardflight.com for an updated list.
Begin EMV transaction
Description
Begin a transaction with the requested amount. If the merchant account is enabled for EMV it will begin an EMV transaction, otherwise a traditional swipe transaction is initiated.
If an EMV transaction is performed, EMV callbacks will be utilized, otherwise traditional swipe callbacks are implemented. Returns an error if an EMV reader is not connected.
If you do not have an EMV-capable reader, use
beginSwipe instead.
An EMV transaction requires frequent communication with the CFTReader instance, that instance must be kept alive for the duration of the transaction.
Parameters
amount: NSDecimalNumber of the amount to charge
chargeDictionary: NSDictionary of charge data for the transaction
description - Optional - NSString of charge description
metadata - Optional - NSDictionary of extra transaction information
EMV Charge Result
Description
This callback is triggered after an EMV transaction completes. It contains a CFTCharge on success (approval) and an NSError if the charge fails or is declined. Required for EMV transactions.
Parameters
charge: CFTCharge object containing the completed charge
error: Contains a NSError if the charge did not complete
Confirm the charge
Description
After recieving the card information for an EMV transaction, send a confirmation to continue processing the transaction.
Parameters
process: BOOL to confirm the card info
Upload a signature
Description
Upload a signature after a charge has been processed. The success or failure of this call does not change the result of the transaction.
Parameters
signatureData: NSData object representation of signature image
success: Block executed on success
failure: Block containing NSError, executed on failure
This callback is triggered when a card is inserted into the reader and the reader is actively processing an EMV transactions. Required for EMV transaction.
Card Removed Callback
Description
This callback is triggered whenever the dipped card is removed from the reader. Useful for ensuring the card is removed at the end of an EMV transaction, but will be called anytime a card is removed. Required for EMV transactions.
Application Selection Callback
Description
This callback is triggered if the ICC card contains more than 1 supported AID. An array is passed for selection by the customer, this array must be displayed in the same order it is returned. Call
application: NSInteger of the index of the preferred application
EMV message callback
Description
This callback is triggered whenever the terminal requests a message be displayed to the user. These messages should be displayed whenever possible. Required for EMV transactions.
Parameters
message: CFTEMVMessage enumeration type to display
Default EMV Message
Description
Can be used to get default text for an EMV message type.
Parameters
message: CFTEMVMessage enumeration type
Card response callback
Description
This callback is triggered when card info from a credit card dipped during an EMV transaction is read. Display to the user and call emvProcessTransaction to accept or reject this card for processing. Required for EMV transactions.
Parameters
cardDictionary: NSDictionary containing first6(NSString), last4 (NSString), and cardType (boxed NSNumber) for display to the user
Error callback
Description
This callback is triggered if a non-fatal error occurs during an EMV transaction. Required for EMV transactions.
Parameters
error: NSError passed from the terminal
Connecting to the reader
Low Battery Callback
Description
This callback is triggered if the battery in the terminal is low. It may still be possible to run a transaction, however the battery should be charged as soon as possible. Required for EMV transactions.
Reader Attached Callback
Description
This callback is triggered when a reader is detected by the SDK, but the reader is not ready to receive commands yet.
Reader Is Connecting Callback
Description
This callback is triggered when the SDK begins the connecting process with the reader.
Reader Connected Callback
Description
This callback is triggered when the connection process is complete. An error is returned if the process did not complete successfully.
Swipe Is Detected Callback
Description
This callback is triggered when a swipe is detected but before it's been processed.
Reader is disconnected
Description
This callback is triggered when an audiojack reader is unplugged or a bluetooth reader loses its connection.
Use Bluetooth reader
Description
Method to set the SDK to connect to Bluetooth readers. The SDK can be set to connect to either Bluetooth or audio jack readers. The default is audio jack. Calling this method with YES will enable Bluetooth readers, calling it with a NO will disable Bluetooth and reenable audio jack readers. Can be called any time a transaction is not in progress.
Get the reader type
Description
Method that returns the currently connected reader type. This value can be saved and passed back into
Initialization method with optional parameter to set the type of reader being used for faster connections. Defaults to auto connect. Can be used with readerType to determine value to pass.
Connect to the supplied Bluetooth reader
Description
After putting the SDK in Bluetooth mode, use this method to attempt connection with the supplied Bluetooth reader. If the connection process fails, additional attempts will not be made until this method is called.
Disconnect the connected Bluetooth reader
Description
When the SDK is in Bluetooth mode and a reader is connected, this method can be used to disconnect the Bluetooth reader safely and completely.
Clear transaction result and disconnect Bluetooth reader
Description
If there is a transaction result, it will clear the result. The bluetooth reader will be disconnected afterwards.
The name of the connected Bluetooth reader
Description
If the SDK is in Bluetooth mode and a reader is connected, this method will return the name of the reader, generally as "BOLD XXXX" where XXXX is the last four digits of the serial number.
Debugging
Logging mode
Description
Pass YES to enable developer logging mode to the console.
Parameters
logging: BOOL to turn on or off logging mode
Log output
Description
Optional callback to reroute logging messages to a file instead of to the console.
Parameters
output: NSString of log message
SDK Version
Description
Convenience method to return the current version number of the SDK.
API Token
Description
Convenience method to return the current API token.
Account Token
Description
Convenience method to return the current Account token.