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

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();
}

Example Response

{
    "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"=>[]
}

Setup Keyed Entry

Description

Add a PaymentView to your layout file to key in card details.

Example

<com.getcardflight.views.PaymentView
    android:id="@+id/paymentview"
    android:layout_width="wrap_content"
    android:layout_height="50dp"
    android:background="@color/white" />

Capture Keyed Card Details

Description

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.

Example

<com.getcardflight.views.PaymentView
    android:id="@+id/paymentview"
    android:layout_width="wrap_content"
    android:layout_height="50dp"
    android:background="@color/white" />

Detect the swipe

Description

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.

Parameters

  • context: Application context
  • tokenizationHandler: CardFlightTokenizationHandler interface implementation

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

  • context: Application context
  • vaultHandler: CardFlightCardVaultHandler interface implementation

Refund a charge

Description

Refund a charge by passing in the charge token and amount to refund in dollars and cents.

Parameters

  • token: (String) doubleCharge token to be refunded
  • amount: (Double) Amount to be refunded
  • paymentHandler: CardFlightPaymentHandler interface implementation

Example request

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();
        }
});

Example response

{
    "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

Description

Void a charge by passing in the charge token to void.

Parameters

  • chargeToken: String containing charge token to be voided
  • paymentHandler: CardFlightPaymentHandler interface implementation

Example

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.

Parameters

  • logging: boolean to turn on or off logging mode

CardFlight Errors Class

Errors

  • CARDFLIGHT_GENERAL_ERROR
  • ACCOUNT_TOKEN_NOT_SET
  • API_KEY_NOT_SET
  • CARD_NUMBER_NOT_VALID
  • DEVICE_NOT_SUPPORTED
  • DEVICE_TIMEOUT
  • CHARGE_TOKEN_MISSING
  • TRANSACTION_ERROR
  • TRANSACTION_AMOUNT_CANNOT_BE_ZERO
  • CHARGE_NOT_REFUNDED
  • CHARGE_NOT_CAPTURED
  • CHARGE_NOT_VOIDED
  • CURRENCY_NOT_SUPPORTED
  • TOKENIZATION_NOT_SUPPORTED
  • READER_ERROR
  • READER_BUSY
  • EMV_READER_NOT_CONNECTED
  • CRC_ERROR
  • SWIPE_ERROR
  • SWIPE_TIMEOUT
  • SWIPE_INVALID
  • AMOUNT_NOT_INCLUDED
  • UNENCRYPTED_READER
  • UNABLE_TO_READ_VALID_CREDIT_CARD_DATA
  • DIP_NOT_SUPPORTED
  • UNKNOWN_ERROR
  • BAD_RESPONSE_FROM_SERVER
  • DECLINED
  • COMMUNCATION_ERROR
  • NO_INTERNET_CONNECTION

Methods

CardFlightError error = CardFlightError.DEVICE_TIMEOUT;

String errorString = error.toString();
String errorMessage = error.getMessage();
int errorCode = error.getCode();

Example

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
  • chargeDictionary: NSDictionary containing charge details
  • chargeDictionary Parameters:
    • amount - NSDecimalNumber containing amount to charge
    • callback_url - Optional - NSURL of callback URL to trigger
    • description - Optional - NSString of charge description
    • customer_id - Optional - NSString of customer ID being charged
    • currency - Optional - NSString ofcurrency code, defaults to USD
    • merchant_id - Optional - NSString of MID
    • service_fee - Optional - NSDecimalNumber containing the fee to charge

Setup Keyed Entry

Description

Add a PaymentView to your layout file to key in card details.

Example

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];

Capture Keyed Card Details

Description

Required protocol method that gets called whenever the keyed entry receives enough valid input to generate a credit card object.

Example

- (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;
    }
}

Invalid Keyed Response

Description

Optional protocol method that gets called whenever the currently entered keyed information can not create a valid card.

Example

- (void)invalidKeyedResponse {

    self.card = nil;
    self.processButton.enabled = NO;
}

Upload a signature

Description

Upload a signature after a charge has been processed.

Parameters

  • token: NSString containing the token of the previously approved charge
  • signatureData: NSData object representation of signature image
  • success: Block executed on success
  • failure: Block containing NSError, executed on failure

Example

[CFTCharge attachSignatureWithToken:self.histTransaction.cardFlightChargeToken
                signatureData:UIImagePNGRepresentation(signature)
                success:^{
                    NSLog(@"%s - SIGNATURE UPLOADED", __PRETTY_FUNCTION__);
                }
                failure:^(NSError *error){
                    NSLog(@"%@", error.localizedDescription);
                }];

Detect the swipe

Description

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.

Swipe timeout

Description

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

Example

[self.reader emvTransactionSignature:UIImagePNGRepresentation(signature)
                success:^{
                    NSLog(@"%s - SIGNATURE UPLOADED", __PRETTY_FUNCTION__);
                }
                failure:^(NSError *error){
                    NSLog(@"%@", error.localizedDescription);
                }];

Card Dipped Callback

Description

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

emvSelectApplication to select an AID. Required for EMV transactions.

Parameters

  • applicationArray: NSArray of application names, sorted by priority

Select Application

Description

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.

Parameters

  • 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

initWithReader to shorten the connection time.

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