The iOS SDK v4 is currently being validated in a private beta test. 

Additionally, note the following updates regarding supported devices:

  • BBPOS Chipper Mini 2 - this device is supported for existing integrations, however new integrations should include the ID TECH VP3300. 
  • ID TECH VP3300 - This device is currently in validation alongside the updated SDK. The VP3300 is a Bluetooth card reader that provides support for MSR (swipe) and EMV (chip) payments. Support for NFC (contactless) payments is planned for a future update to the SDK.
  • ID TECH VP3600 - Support for this device is currently in development. The VP3600 includes the same features as the VP3300, with the addition of a built-in PIN pad. Support for this device is planned for a future update to the SDK.

Introduction

The CardConnect iOS SDK seamlessly connects your iOS applications to CardSecure for tokenization of customer card data. Tokens and other associated payment details are then retrieved by your server and securely transmitted to the CardPointe Gateway for authorization, using a server-side REST client. 

See the iOS SDK Release Notes for a summary of the recent updates to the SDK.

What's New?

Version 4.1.2

This release includes the following updates:

  • Added a beepSetting property to the CCCSwiperController class to control the tone that the card reader device emits to prompt the user remove the card.

    The default setting is a single, 800ms long tone.

  • A new enumeration has been added for the device beep setting called CCCDeviceBeepSetting.

Overview

A complete mobile payment solution consists of two components: 

  • Tokenization is handled by the iOS SDK integrated with your mobile application. 
  • Authorization is handled by host scripts integrated with your server application.

Tokenization (Client-side)

The iOS SDK installs alongside your mobile application, and uses CardSecure to tokenize and encrypt payment card data. Card data can be manually entered in the application or captured, using a supported mobile payment reader device. Payment card data is encrypted and tokenized while being kept separate from your software application or server.

Additionally, tokens can be stored in customer profiles for use in subsequent transactions. See Integrating the Customer Profile UI for more information on adding this feature to your application.

See About Our Tokens for detailed information about how CardConnect tokens are created and used.

Authorization (Server-side)

The CardPointe Gateway REST clients install on your application server to integrate your solution to the CardPointe Gateway.

Using a REST client, your sever authenticates with the CardPointe Gateway, makes authorization requests using tokens retrieved from the mobile app, and handles responses from the Gateway.

See Toolkit Introduction for information on using the CardPointe Gateway REST clients.

See the CardPointe Gateway API documentation for more information on the features and capabilities of the CardPointe Gateway.

Tokenization and Payment Flow 

The following diagram illustrates the tokenization and payment flow using the iOS SDK and server-side REST client.

  1. Your mobile app collects payment card data from a connected mobile payment reader or by manual entry in the app and sends the data to CardSecure via the iOS SDK.
  2. CardSecure returns a token to the mobile app.
  3. The mobile app sends the token to your server, which is running a CardPointe Gateway REST client.
  4. Your server application uses the token to make an authorization request to the CardPointe Gateway, via the REST client.
  5. The CardPointe Gateway returns the authorization response to your server.
  6. Your server passes the authorization response to the mobile app.

PCI Compliance

Integrating the iOS SDK can help reduce your PCI scope. The SDK provides direct tokenization methods that pass your customers' sensitive card data to CardConnect without ever sending the clear or unencrypted card data to your server.

The token returned from this process is not considered card data; therefore, as the token moves between your client application and your application server, the token does not bring any of those systems or data paths into scope for PCI security controls.

Supported Devices

If you are developing an application to accept card present payments, you must integrate a mobile payment reader (swiper) device with your solution. Currently, the iOS SDK includes support for the following devices:

  • BBPOS Chipper Mini 2 

    The Chipper Mini 2 is a magnetic stripe reader (MSR) device that connects to the phone or tablet using the audio jack. The Chipper Mini 2 is supported for existing integrations, however new integrations should include the ID TECH VP3300.

  • ID TECH VP3300 

    The VP3300 is a Bluetooth-enabled mobile payment reader device that supports MSR (swipe) and EMV (chip) transactions. The VP3300 connects to your phone or tablet using Bluetooth 4.0, which supports Bluetooth Low Energy and automatic pairing.

    For more information on using the VP3300, see the ID TECH VP3300 Support Guide.

Support for NFC (contactless) transactions on the VP3300 and support for the VP3600, which features a built-in PIN pad, is planned for a future update of the iOS SDK.

Getting Started

If you are a developing a new integrated application, see the iOS SDK Integration Guide for detailed information.

If you are updating or migrating an existing integration to the latest version of the iOS SDK, see the iOS SDK Migration Guide.

Download the latest version of the SDK to get started:

The CardConnect iOS SDK includes the following resources :

  • Docs - Contains an API reference that provides a detailed description of each component of the SDK.
  • Framework - Contains the CardConnectConsumerSDK framework.
  • SampleApp - Contains an Objective-C sample application.
  • SwiftSampleApp - Contains a Swift sample application.
  • ThemeGuide - Contains a series of diagrams that illustrate the relationship of theme properties to UI elements in the sample application.

Requirements

Before you begin, ensure that you have the following:

  • CardConnect iOS SDK - See Getting Started to download the SDK.
  • CardConnect iOS Sample App - Review the included sample applications to better understand the SDK integration.
  • CardConnect Merchant ID and API credentials - Contact integrationdelivery@cardconnect.com if you do not already have an account.
  • CardSecure Tokenization URL - Your merchant ID must be associated with a CardSecure URL to send requests to CardSecure. 
  • Xcode IDE - The iOS SDK and related documentation support the Xcode integrated development environment.  
  • (Optional) Mobile Payment Reader Device - If you are integrating a mobile payment reader (swiper) device, you must us a device that has been provisioned and provided by CardConnect. 
  • (Optional) iPhone or iPad Device - If you are using a mobile payment reader (swiper) device, you will need a physical iPhone or iPad device to test the integration. The Xcode device emulator does not support these connected devices.

Customer and Merchant-Facing Applications

This solution can be integrated with both merchant and customer-facing applications. Depending on the type of application you are developing, you can include specific modules tailored to your specific audience and integration needs.

Customer-Facing Applications

A customer user downloads and interacts with your application directly, without interacting with a merchant or participating in a card-present transaction.

Merchant-Facing Applications

A merchant user interacts with the application as an extension of the integrated point-of-sale (POS) system, and might accept both card present and card not present payments.

iOS SDK Features

The following table provides an overview of the features that you might want to integrate with your application, depending on your audience:

Functionality User Type Component Description
Stored Customer Profiles Customer Integrated Customer Profile UI Integrates the CardPointe Gateway Profile service, allowing customers to securely store and manage their payment accounts.

See the CardPointe Gateway Profile service documentation for more information on the profile service. 

See Integrating the Customer Profile UI for information on adding this feature to your application. 
Apple Pay Wallet Support Customer Apple Pay Integration Adds the option to use Apple Pay wallet credentials and stored payment methods.

See the Apple Pay Developer Guide for more information.
Mobile Payment Reader Devices Merchant iOS Swiper Implementation An integrated mobile payment reader (swiper) device used to securely capture and encrypt card data prior to tokenization.

See Supported Devices for information on the devices that are currently supported.

See the iOS SDK Integration Guide for instructions for integrating mobile payment reader devices.

iOS Sample App User's Guide

Before you begin your integration, you should review the sample app, which includes demos of the features provided by the SDK.

The sample app includes the following demos:

  • Configure Swiper - Connect to a BBPOS Chipper Mini 2 or ID TECH VP3300 device.
  • Tokenization Methods - Tokenize card data obtained from the swiper device, or manual entry.
  • Modal Profile Flow - Create and manage stored customer profiles using the CardPointe Gateway Profile service.
  • Stack Profile Flow - Create and manage stored customer profiles using the CardPointe Gateway Profile service.
  • Theming - Customize the colors used throughout the app.
  • Signature - Capture a signature in the format required for the CardPointe Gateway Signature Capture service. 

Tokenization URL

The sample app includes an editable URL field. This url is used to connect to CardSecure to tokenize the payment card data. Ensure that you enter the URL provided by CardConnect.

Configure Swiper

The configure swiper demo allows you to find and connect to a mobile payment reader (swiper) device that is properly configured and ready to connect to the app. 

The phone or tablet cannot be connected to any other devices using Bluetooth or the 3.5mm headphone jack when attempting to use a swiper device.

To connect to a mobile payment reader, do the following:

  1. Select BBPOS to find and connect to a Chipper Mini 2 device or select IDTech VP3300 to connect to a VP3300 device.

    The app displays a list of available devices. 
  2. Select a device to connect to it.

    The device is now connected and ready for use.

Tokenization Methods

This demo allows you to manually enter or use a connected mobile payment reader device to capture and tokenize payment card data. 

Using a Mobile Payment Reader

If a mobile payment reader device is connected, the app prompts you to insert or swipe a card. When you insert or swipe the payment card, the app captures the card data and immediately sends it to CardSecure. The app retrieves the generated token, and returns it in a confirmation message.

Manually Entering Card Data

To manually enter card data, tap the input fields and enter the card information.

When finished, tap Generate Token to send the card data to CardSecure and generate a token. The app retrieves the generated token, and returns it in a confirmation message.

Additionally, you can select the following methods used to display the input in the Card Number field:

  • Masked Last4 - Masks each digit with the selected character (*, &, or -) except for the last four digits of the card number. For example, ************1111.
  • Last4 - hides each digit of the card number, displaying only the last four.  For example, 1111.
  • FirstandLast4 - Masks each digit with the selected character (*, &, or -), except for the first four digits and last four digits. For example, 4444********1111.

Modal and Stack Profile Flows

The sample app includes two implementations of the Customer Profile UI, the Modal Profile View and the Stack Profile View. 

The Modal Profile View presents the Profile UI in a new modal object, which renders as a new window on top of the existing application window.

The Stack Profile View presents the Profile UI in a new stack in the existing application window.

Both versions of the demo include sample profile data, and the ability to add, edit, and delete profiles.

To add a new profile, do the following:

  1. Tap Add New Account on the Accounts page.
  2. Enter the Card Number and Expiration Date, and any optional details that you want to include in the profile. The Card Number and Expiration Date fields automatically format the input.
  3. Tap Done then tap Create Account to save the new profile. 

To edit a profile, do the following:

  1. Tap Edit on the Accounts page.
  2. Tap the stored payment card that you want to edit.

    Alternatively, tap the delete icon to delete the stored payment card.
  3. On the Edit Account page, you can edit the expiration date and set the stored card as the default payment method.  
  4. Click Save to save your changes.

When you integrate the SDK with your application, you can extend the Profile UI to edit the customer billing information and make an update profile request to the CardPointe Gateway.

Theming

The sample app includes a theming demo, that allows you to change the colors used throughout the app to match your custom theme. 

The ThemeGuide folder, included in the SDK package, includes diagrams to help you map the theme parameters to their associated UI components.

Signature

The sample app includes a demo interface for capturing signatures. 

The demo presents a touch input field that you can use to draw a signature. Click Test to capture the signature, or click Clear to clear the input. Note that the signature data is not stored in this demo.

iOS SDK Integration Guide

This guide provides information for integrating the iOS SDK with your application. 

See the API reference documentation, included in the SDK package, for detailed information on using the classes and methods described in this guide.

If you already integrated an older version of the iOS SDK and want to migrate to the latest version, see the iOS SDK Migration Guide.

Integrating the SDK

The following topics provide information for integrating the iOS SDK with your application, using the Xcode integrated development environment (IDE).

Adding the Framework to your Project

Do the following to add the CardConnectConsumerSDK framework to your project.

  1. Open your project in Xcode. 
  2. In the left pane, select the Project Navigator tab, then click your project to open the Project Editor.
  3. In the left pane of the Project Editor, select the target for your project.
  4. Select the General tab, scroll down to the Embedded Binaries section and click the plus sign (+).
  5. In the choose items to add window, click Add Other… and browse to CardConnectConsumerSDK.framework
  6. Select the framework, click Open, and then click Finish.
  7. Select the Build Phases tab, click the plus sign (+), and select New Run Script Phase.
  8. Expand the new Run Script Phase and add the following line:

    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/CardConnectConsumerSDK.framework/strip-frameworks.sh"

Configuring your Project

Do the following to configure your project:

  1. Import the SDK into your prefix or source files:
    #import <CardConnectConsumerSDK/CardConnectConsumerSDK.h>
  2. Set your endpoint provided by CardConnect on CCCAPI (for example, <host>.cardconnect.com:<port>)
    [CCCAPI instance].endpoint = @”<endpoint provided by CardConnect>”;

Adding Support for Mobile Payment Readers

If you are integrating support for a mobile payment reader (swiper) device, do the following to configure your project:

  1. Select the Info tab on the Project Editor
  2. Under Custom iOS Target Properties, hover over the table and click the plus sign (+) to add a new key.
  3. Select Privacy - Microphone Usage Description key.
  4. In the Value column, enter a description to display to users (for example, "Required for swiper usage").
  5. Click the plus sign again to add a new key, and select Required background modes.
  6. Expand the Required background modes key and select App plays audio or streams audio/video using AirPlay for item 0 in the array.

Adding Support for the VP3300 Device

To integrate an ID TECH VP3300, do the following to add the required bundle to your project:

  1. In the Project Navigator (left) pane, right-click your project name and select Add files to "<app name>".
  2. Browse to the directory that includes the CardConnectConsumerSDK.framework and add the IDTech.bundle file to your project at the path <project directory>/CardConnectConsumerSDK.framework/IDTech.bundle.

Integrating the Mobile Payment Reader

To use a mobile payment reader (swiper) device, perform the following steps to integrate the device with your application:

  1. Add the CCCSwiperControllerDelegate protocol to your view controller.
  2. Add the required methods from CCCSwiperControllerDelegate and its super protocol CCCSwiperDelegate to your view:
    • swiper:didGenerateTokenWithAccount:completion:
    • swiper:didFailWithError:completion:
    • swiper:foundDevices:
    • swiper:displayMessage:canCancel:
  3. Create a CCCSwiperController property in your view and initialize it in viewWillAppear: as follows:

    self.swiper = [CCCSwiperController alloc] initWithDelegate:self swiper:{CCCSwiperType} loggingEnabled:YES];
  4. Release the swiper and set it to nil in viewWillDisappear: as follows:
    [self.swiper releaseDevice];
    self.swiper = nil;

    The swiper should initialize when the view appears. You can get the connection status using the optional methods in CCCSwiperDelegate.
  5. If you are using a VP3300 device, continue to Integrating a VP3300 Device.

Integrating a VP3300 Device

The following topics provide information for integrating the ID TECH VP3300.

Validating and Updating the Device Configuration

When the application connects to the VP3300, by calling connectToDevice:mode:, it validates the device's configuration. If this is the first time the device is connected, or if a new device configuration is available, the VP3300 automatically enters configuration mode. In configuration mode, the application updates the VP3300 with the current valid configuration. When the process completes, the device automatically begins waiting for card input.

You can use the swiper:configurationProgress delegate callback to monitor the configuration process.

To save time in the payment flow, it is a best practice to configure a view that finds and connects to the device prior to accepting a payment, to ensure that the device is updated and ready for use. 

In this view, once the device is found using [swiper findDevices];, connect to using connectToDevice:mode:. You can suppress the displayMessage callback. Additionally, when swiperDidStartCardRead is called you can cancel the transaction and check the error code for "canceled" in swiper:didFailWithError: to finish your connection flow. 

Note that you should delay the call to cancel the transaction to allow adequate time for the device time to initialize.  See SwiperConfigurationViewController.m or the .swift class in the sample application for an example of this workflow. 

Selecting Card Read Methods

The SDK provides two modes to connect to a mobile payment reader device, CCCCardReadModeSwipe and CCCCardReadModeSwipeDip.

Use CCCCardReadModeSwipe to force the reader to only accept the swipe (MSR) card read method. In this mode, attempting to insert a card will result in an error.

Use CCCCardReadModeSwipeDip to accept both swipe (MSR) and dip/insert (EMV) card read methods. In this mode, attempting to swipe an EMV card results in an error.

Connecting the Device

Do the following to find and connect to the VP3300:

  1. To start finding devices, call [self.swiper findDevices];.

    Found devices will be returned to swiper:foundDevices:.
  2. Once you select a device, call [self.swiper cancelFindDevices];.
  3. To connect to the device, call [self.swiper connectToDevice:device.uuid];.

    Once connected, the swiper will begin waiting for a card and swiper:displayMessage:canCancel will be called.

All messages from swiper:displayMessage:canCancel: must be displayed. If the cancelable parameter is set to true, you can use [self.swiper cancelTransaction]; to include a cancel function.

Integrating the Customer Profile UI

The SDK framework supports an integrated user interface for managing user accounts. The integrated UI allows you to use the CardPointe Gateway's profile service to add, delete, edit, and display a profile’s accounts with an easy to use interface. The integrated UI also includes a custom theming class that allows you to modify the look and feel.

To use the integrated UI, do the following:

  1. Create a class that conforms to CCCAPIBridgeProtocol.

    This class calls the backend to perform the actions required by the UI.
  2. Set up your root view controller.

    This will be the view that presents and responds to the integrated profile UI flow (for example, the screen that appears before the user selects a payment method).
  3. In your root view controller, add strong properties for your class that conform to CCCAPIBridgeProtocol and CCCPaymentController. Additionally, if you want to use a custom theme, create a property for it.
  4. In your root view controller, conform to the CCCPaymentControllerDelegate protocol and add paymentController:finishedWithAccount: to your controller.
  5. In viewDidLoad Initialize the payment controller using either initWithRootView:apiBridge:delegate: or initWithRootView:apiBridge:delegate:theme:.
  6. The payment controller supports two display methods: integrated with your current stack, or in a separate modal. Depending on which design you want to integrate, do the following:
    • To push the integrated profile UI flow onto your current navigation stack, call
      [CCCPaymentController pushPaymentView].

      Note: This requires your root view to be contained within a navigation controller.

    • To present the integrated UI flow modally, call [CCCPaymentController presentPaymentView].
    The integrated profile UI is now configured to display in the method you selected and use your API bridge class to supply data to the user. When the user finishes and selects a payment method, the controller is dismissed and the account is returned to your root view.

Integrating Field Formatting and Validation

The SDK includes the following delegate classes, which provide functions for field formatting and validation:

  • CCCCardFunctions
  • CCCCardFormatterDelegate
  • CCCCVVFormatterDelegate
  • CCCExpirationDateFormatterDelegate

See the API reference documentation, included in the SDK package, for detailed information on using these classes.

  1. In the .xib file, where you collect card information, add an empty object to your controller and set its class to one of the delegates (for example, CCCCardFormatterDelegate).
  2. Link your UITextField for card number to this class as its delegate.

    If you want callbacks for other UITextFieldDelegate calls sent to your view controller, link the CCCCardFormatterDelegate class originalDelegate property to your view controller.
  3. If you want to modify the masking of the text field, set a reference outlet to your view controller as well.

    The text input field will now auto-format user input and provide validation using the CCCCardFormatterDelegate method isValidCard.

    To generate a token, use the CCCCardFormatterDelegate function setCardNumberOnCardInfo: to get the card number.

When clearing text fields using the custom delegate classes, call clearTextField on the delegates themselves to clear internal information.

Generating a Token

You use the CCCCardInfo and CCCAPI classes to send a payment card data to CardSecure in a tokenization request. See the API reference documentation, included in the SDK package, for detailed information on these classes.

  1. Add a card number, expiration date, and CVV to your CCCCardInfo object.
  2. Using your card info object call the CCCAPI function to generate a token as follows:

    [CCCAPI instance] generateAccountForCard:<your card object> completion:^(CCCAccount *account, NSError *error){}];

    A token is generated for the account and returned to your application.
  3. Optionally, you can use CCCAccount to save an account for a profile in CardConnect using the iOS SDK Integrated Customer Profile UI or CardPointe Gateway API.

iOS SDK Migration Guide

This guide provides information for migrating from a previous version of the iOS SDK to the current version (v4).

Integrating the New Framework

Perform the following steps to replace the existing release and universal frameworks with the new universal framework:

  1. Remove the existing framework files from your project's root directory (for example, remove ${PROJECT_DIR}/embeddedFrameworks).
  2. In the Project Editor, select the Build Phases tab and remove the Run Script phase used to copy the SDK from the release or universal folder.
  3. Replace the CardConnectConsumerSDK.framework in your project directory with the new one.

Adding the strip-frameworks Script

The SDK includes a script that strips out unnecessary architectures at build time. 

Do the following to add the script to your project:

  1. Select the Build Phases tab, click the plus sign (+), and select New Run Script Phase.
  2. Expand the new Run Script Phase and add the following line:

    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/CardConnectConsumerSDK.framework/strip-frameworks.sh"

Updating the Swiper Connection Settings

If your application includes support for a mobile payment reader (swiper) device, do the following to update the connection settings:

  1. Change your swiper delegate from CCCSwiperDelegate to CCCSwiperControllerDelegate.
  2. Add the following required callbacks:
    • swiper:foundDevices:
    • swiper:displayMessage:canCancel:
  3. In viewWillDisappear, add [self.swiper releaseDevice]; before self.swiper = nil.
  4. Replace
    self.swiper = [[CCCSwiperController alloc] initWithDelegate:loggingEnabled:]
    with
    self.swiper = [[CCCSwiperController alloc] initWithDelegate:swiper:{CCCSwiperType} loggingEnabled:]

Adding a VP3300 Device

To add support for the ID TECH VP3300 mobile payment reader, do the following to add the required bundle to your project:

  1. In the Project Navigator (left) pane, right-click your project name and select Add files to "<app name>."
  2. Browse to <project directory>/CardConnectConsumerSDK.framework/IDTech.bundle and add the IDTech.bundle file to your project.
  3. See Integrating a VP3300 Device above for information for integrating and using the VP3300 with your application.