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 (magnetic stripe) 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.
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.
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.
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.
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.
The following diagram illustrates the tokenization and payment flow using the iOS SDK and server-side REST client.
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.
CardSecure returns a token to the mobile app.
The mobile app sends the token to your server, which is running a CardPointe Gateway REST client.
Your server application uses the token to make an authorization request to the CardPointe Gateway, via the REST client.
The CardPointe Gateway returns the authorization response to your server.
Your server passes the authorization response to the mobile app.
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.
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.
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.
To support iOS 13, you must use Xcode 11 and version 4.3 (or later) of the iOS SDK.
(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.
If you are using an ID TECH VP3300, ensure that the device is running the latest firmware. See the ID TECH VP3300 Integration Guide for more information.
(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.
A customer user downloads and interacts with your application directly, without interacting with a merchant or participating in a card-present transaction.
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:
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.
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.
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:
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.
Select a device to connect to it.
The device is now connected and ready for use.
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:
Tap Add New Account on the Accounts page.
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.
Tap Done then tap Create Account to save the new profile.
To edit a profile, do the following:
Tap Edit on the Accounts page.
Tap the stored payment card that you want to edit.
Alternatively, tap the delete icon to delete the stored payment card.
On the Edit Account page, you can edit the expiration date and set the stored card as the default payment method.
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.
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.
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.
Open your project in Xcode.
In the left pane, select the Project Navigator tab, then click your project to open the Project Editor.
In the left pane of the Project Editor, select the target for your project.
Select the General
tab, scroll down to the Embedded Binaries section and click the plus sign (+).
In the choose items to add window, click Add Other… and browse to CardConnectConsumerSDK.framework.
Select the framework, click Open, and then click Finish.
Select the Build Phases tab, click the plus sign (+), and select New Run Script Phase.
Expand the new Run Script Phase and add the following line:
In the Value column, enter a description to display to users (for example, "Required for swiper usage").
Click the plus sign again to add a new key, and select Required background modes.
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:
In the Project Navigator (left) pane, right-click your project name and select Add files to "<app name>".
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:
Add the CCCSwiperControllerDelegate protocol to your view controller.
Add the required methods from CCCSwiperControllerDelegate and its super protocol CCCSwiperDelegate to your view:
Create a CCCSwiperController property in your view and initialize it in viewWillAppear: as follows:
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:
To start finding devices, call [self.swiper findDevices];.
Found devices will be returned to swiper:foundDevices:.
Once you select a device, call [self.swiper cancelFindDevices];.
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:
Create a class that conforms to CCCAPIBridgeProtocol.
This class calls the backend to perform the actions required by the UI.
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).
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.
In your root view controller, conform to the CCCPaymentControllerDelegate protocol and add paymentController:finishedWithAccount: to your controller.
In viewDidLoad Initialize the payment controller using either initWithRootView:apiBridge:delegate: or initWithRootView:apiBridge:delegate:theme:.
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:
See the API reference documentation, included in the SDK package, for detailed information on using these classes.
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).
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.
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.
Add a card number, expiration date, and CVV to your CCCCardInfo object.
Using your card info object call the CCCAPI function to generate a token as follows: