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.
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.
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.
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.
@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();
}
}
Method to charge a card with the details in the chargeDetails HashMap.
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();
}{
"id"=>29074,
"amount"=>10000,
"token"=>"ch_ihnKTubivHFQV_pj4nP1cw",
"card"=> {
"last4"=>"4242",
"card_type"=>"visa",
"exp_month"=>6,
"exp_year"=>2017
},
"reference_id"=>"ch_2jEBTXWmjrcM8h",
"refunded"=>false,
"amount_refunded"=>0,
"refunds"=>[]
}
Add a PaymentView to your layout file to key in card details.
<com.getcardflight.views.PaymentView
android:id="@+id/paymentview"
android:layout_width="wrap_content"
android:layout_height="50dp"
android:background="@color/white" />
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.
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);
}
});
}
});
Add a PaymentView to your layout file to key in card details.
<com.getcardflight.views.PaymentView
android:id="@+id/paymentview"
android:layout_width="wrap_content"
android:layout_height="50dp"
android:background="@color/white" />
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.Optional method to set timeout period in seconds. Default is TRUE.
Manually cancel the swipe process before the timeout duration has been reached or cancels an EMV transaction
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.
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.
Refund a charge by passing in the charge token and amount to refund in dollars and cents.
Charge.processRefund(
mCharge.getToken(), refund,
new CardFlightPaymentHandler() {
@Override
public void transactionSuccessful(Charge charge) {
Toast.makeText(mContext, "Charge refunded",
Toast.LENGTH_SHORT).show();
}
@Override
public void transactionFailed(CardFlightError error) {
Toast.makeText(mContext, error.toString(), Toast.LENGTH_SHORT)
.show();
}
});{
"id"=>34097,
"amount"=>10000,
"token"=>"ch_ihnKTubivHFQV_pj4nP1cw",
"card"=> {
"last4"=>"4242",
"card_type"=>"visa",
"exp_month"=>6,
"exp_year"=>2017
},
"reference_id"=>"ch_2jEBTXWmjrcM8h",
"refunded"=>true,
"amount_refunded"=>10000,
"refunds"=>[
{
"amount"=>10000,
"token"=>"rf_ugrWyNg50_taklS_4-1ciw",
"reference_id"=>null,
"date_created"=>Mon, 18 Nov 2013 22:25:53 UTC +00:00
}
]
}Void a charge by passing in the charge token to void.
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();
}
});
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 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.
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.
@Override
public void emvTransactionResult(Charge charge, boolean requiresSignature,
CFEMVMessage message) {
if (charge != null) {
// Approval flow
} else {
switch (message) {
// add cases for each outcome
}
}
}
After recieving the card information for an EMV transaction, send a confirmation to continue processing the transaction.
Upload a signature after a charge has been processed.
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();
}
});
This callback is triggered when a card is inserted into the reader when an EMV transaction is active.
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.
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.
@Override
public void emvRequestApplicationSelection(ArrayList appList) {
int selection = selectAID(appList); // Implement method to select AID
Reader.getDefault(mContext)
.emvSelectApplication(selection);
}
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.
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.
@Override
public void emvMEssage(CFEMVMessage message) {
Toast.makeText(mContext, message.getMessage(),Toast.LENGTH_SHORT)
.show();
}
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:This callback is triggered if a non-fatal error occurs during an EMV transaction. Required for EMV transactions.
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.
This callback is triggered when a reader is detected by the SDK, but the reader is not ready to receive commands yet.
This callback is triggered when the SDK begins the connecting process with the reader.
This callback is triggered when the connection process is complete. An error is returned if the process did not complete successfully.
This callback is triggered when a swipe is detected but before it's been processed.
This callback is triggered when a reader is unplugged.
Initialization method with optional parameter to set the type of reader being used for faster connections. Defaults to auto connect.
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.
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.
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.
Optional callback to reroute logging messages to a file instead of to the console.
Convenience method to return the current version number of the SDK.
Convenience method to return the current API token.
Convenience method to return the current Account token.
Pass true to enable developer logging mode to the console.
CardFlightError error = CardFlightError.DEVICE_TIMEOUT;
String errorString = error.toString();
String errorMessage = error.getMessage();
int errorCode = error.getCode();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
}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.
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:
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.
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.
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.
Method to charge a card with the details in the chargeDictionary.
Add a PaymentView to your layout file to key in card details.
self.paymentView = [[CFTPaymentView alloc] initWithFrame:CGRectZero
enableZip:YES];
self.paymentView.delegate = self;
self.paymentView.translatesAutoresizingMaskIntoConstraints = NO;
[self.paymentView useKeyboardAppearance:UIKeyboardAppearanceDark];
[self.view addSubview:self.paymentView];
Required protocol method that gets called whenever the keyed entry receives enough valid input to generate a credit card object.
- (void)keyedCardResponse:(CFTCard *)card {
if (card) {
[[Log sharedInstance] append:[NSString stringWithFormat:
@"%s - Last 4: %@", __PRETTY_FUNCTION__, card.last4 ?:
[NSNull null]]];
self.card = card;
self.processButton.enabled = YES;
}
}
Optional protocol method that gets called whenever the currently entered keyed information can not create a valid card.
- (void)invalidKeyedResponse {
self.card = nil;
self.processButton.enabled = NO;
}
Upload a signature after a charge has been processed.
[CFTCharge attachSignatureWithToken:self.histTransaction.cardFlightChargeToken
signatureData:UIImagePNGRepresentation(signature)
success:^{
NSLog(@"%s - SIGNATURE UPLOADED", __PRETTY_FUNCTION__);
}
failure:^(NSError *error){
NSLog(@"%@", error.localizedDescription);
}];
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 beginEMVTransactionWithAmount instead.Optional method to set whether reader times out while waiting for a swipe after 20 seconds. Default is YES.
Manually cancel the swipe process before the timeout duration has been reached or cancels an EMV transaction.
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.
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.
Refund a charge by passing in the charge token and amount to refund in dollars and cents.
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.
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 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.
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.
After recieving the card information for an EMV transaction, send a confirmation to continue processing the transaction.
Upload a signature after a charge has been processed. The success or failure of this call does not change the result of the transaction.
[self.reader emvTransactionSignature:UIImagePNGRepresentation(signature)
success:^{
NSLog(@"%s - SIGNATURE UPLOADED", __PRETTY_FUNCTION__);
}
failure:^(NSError *error){
NSLog(@"%@", error.localizedDescription);
}];
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.
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.
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
emvSelectApplication to select an AID. Required for EMV transactions.Use this method to select the application of the chip to process the transaction with. Call after recieving
emvApplicationSelection callback and getting the preferred application index.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.
Can be used to get default text for an EMV message type.
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.
This callback is triggered if a non-fatal error occurs during an EMV transaction. Required for EMV transactions.
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.
This callback is triggered when a reader is detected by the SDK, but the reader is not ready to receive commands yet.
This callback is triggered when the SDK begins the connecting process with the reader.
This callback is triggered when the connection process is complete. An error is returned if the process did not complete successfully.
This callback is triggered when a swipe is detected but before it's been processed.
This callback is triggered when an audiojack reader is unplugged or a bluetooth reader loses its connection.
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.
Method that returns the currently connected reader type. This value can be saved and passed back into
initWithReader to shorten the connection time.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.
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.
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.
If there is a transaction result, it will clear the result. The bluetooth reader will be disconnected afterwards.
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.
Pass YES to enable developer logging mode to the console.
Optional callback to reroute logging messages to a file instead of to the console.
Convenience method to return the current version number of the SDK.
Convenience method to return the current API token.
Convenience method to return the current Account token.
