Introduction

CardConnect Mobile SDKs seamlessly connect your mobile applications to CardSecure for tokenization of customer card data. Tokens and other associated payment details are then retrieved by implementers server and securely transmitted to the CardConnect gateway for authorization.

CardConnect currently offers a CardConnect iOS SDK as well as server-side tool kits to help you get started.

How it Works

The CardConnect Mobile SDK installs alongside your software, adding secure tokenization to your applications. The Mobile SDK can also facilitate communication with a CardPointe Mobile Device to encrypt card data while keeping it separate from your software application or server.

Host Scripts Sdk
  1. The card information is collected from your mobile app, using the swiper or manual entry through the UI.
  2. A token is returned to the SDK from CardSecure.
  3. The token is then retrieved from the Partner/Merchant server.
  4. An authorization request is sent to the CardConnect server.
    • The CardConnect Server-Side Tool Kit is used to handle the REST authentication, request and response.
  5. The CardConnect server returns the authorization response.
  6. An authorization response is passed to your client application.

Client-side & Server-side

You'll need the client-side SDK and the server-side Tool Kit to use the CardConnect Mobile Solution.

The client-side SDK is responsible for the first part of this process - retrieving your customer's card data and returning a token to the mobile app. The Server-side Tool Kit (Python or Node scripts) manages the second half of the process - receiving the payload with a token from the app and sending it to the CardConnect gateway for payment authorization.

The server-side toolkit may also handle other gateway functions such as capture, void, refund, and inquire requests initiated by user in-app activity.

User Types

This solution can be implemented into either merchant or customer-facing applications. Depending on the user type downloading and interacting with your application, different modules can be used to streamline the integration with CardConnect.

A Customer user type downloads and interacts with your application directly, while a Merchant user type uses the application as an extension of their Point-of-Sale (POS) system.

Functionality User Type iOSAndroid Description
Customer Profile UI Customer iOS Customer ProfileAndroid Customer Profile Assists consumers manage their payment methods
Wallet Support Customer Apple Pay IntegrationN/A Adds the option to use Apple Pay wallet credentials
Card Swiper Merchant iOS Swiper ImplementationAndroid Tokenize with Card Reader An integrated, peripheral swiper device to securely encrypt card data prior to tokenization

PCI Compliance

For Both Merchant-facing & Consumer-facing Applications

Use of the CardConnect Mobile SDK can help reduce your PCI scope since the Mobile SDK provides direct tokenization methods that pass your customers sensitive card data to CardConnect without hitting your server.

The token returned from this process is not considered card data and therefore as it moves through a merchant system and then through another “in-line” service provider, like an application server, the token does not cause any of those pathways to be brought into scope for PCI security controls.

iOS

The iOS Mobile SDK makes accepting mobile payments through your iPhone or iPad app easy while keeping your business outside of PCI scope. This SDK also supports the ability to generate a token from data retrieved by Apple Pay.

The iOS CardConnect SDK zip file contains:

  • CCCSDK Integration Guide iOS.docx
  • Docs, including API Reference
  • Framework
  • Obj-C Sample Application
  • Swift Sample Application
  • Theme Guide

Install the SDK

  1. Download and unzip the CardConnectConsumerSDK.
  2. Open the Framework folder.
  3. Add a .framework file to your project's source directory.
Framework Description
Universal This version contains simulator architectures to run the app in any simulator. However, this version is rejected by Apple during the submission process. So, once you're ready to add the SDK to your app, use the Release version.
Release Use this framework for any appstore version.

Prepare for App Store Deployment

A simple script can be added to your code to replace the Universal framework with the Release version once you're ready:

  1. Open your project's root directory. This will be the directory that contains your .xcodeproj file by default.
  2. Create a path from where you added CardConnectConsumerSDK.framework and add both the universal and release version of the framework.
  3. Determine the configuration your application uses for archive builds. By default it is “Production”.
  4. In XCode, in your project inspector, select your build target and then the Build Phases tab.
  5. Click the + button and select New Run Script Phase. This creates a new phase at the end of your build phases. You’ll need to move this under your Target Dependencies phase.
  6. In your run phase, make sure the Shell is set to /bin/sh.
  7. In the text block add:

if [ "${CONFIGURATION}" = "Production" ]; then
    cp -rf "${PROJECT_DIR}/embededFrameworks/Release"/* "${PROJECT_DIR}/"
else
    cp -rf "${PROJECT_DIR}/embededFrameworks/Universal"/* "${PROJECT_DIR}/"
fi
  1. Now when you build, the project will determine which version to use.

Add the Framework

If your application will only accept card-not-present (manual-entry) transactions, then skip to Configuration.

  1. Open the General tab of your project in xCode.
  2. Drag and drop the CardConnectConsumerSDK.framework from your directory to Embedded Binaries.
  3. Click Finish.

Swiper Configuration (optional)

  1. Select the Info tab.
  2. Under Custom iOS Target Properties, click + to add a new key.
  3. Select the Privacy - Microphone Usage Description key.
  4. Add a description for the swiper usage you’d like displayed to users.
  5. Click + to add the Required background modes key.
  6. Enter App plays audio or streams audio/video using AirPlay for item 0 in the array.

SDK Configuration

  1. Import the SDK into your prefix or your source files where you’ll be using it with:
#import <CardConnectConsumerSDK/CardConnectConsumerSDK.h>
  1. Set your endpoint provided by CardConnect on CCCAPI
    Example: “fts.cardconnect.com:9999”
[CCCAPI instance].endpoint = @”<{sitename}.cardconnect.com:{port}>”;

Get a Token

Tokenization is done using the CCCAPI and CCCCardInfo classes within the Headers folder of the framework.

  1. Add your card number, expiration date and CVV to your CCCCardInfo object.
  2. Using your card info object call the CCCAPI function to generate a token.
[CCCAPI instance] generateAccountForCard:<your card object> completion:^(CCCAccount *account, NSError *error){}];
  1. If an account is returned, its value is your generated token.
    CCCAccount can also be used to save an account for a profile in CardConnect using the web SDK or APIs.

Field Formatting and Validation

The SDK provides various classes and functions for field formatting and validation. Documentation for each class can be found within the Docs folder of the SDK Download.

Full field formatting and validation can be accomplished with the following delegate classes:

  • CCCCardFunctions
  • CCCCardFormatterDelegate
  • CCCCVVFormatterDelegate
  • CCCExpirationDateFormatterDelegate
  1. In your .xib file where you’re collecting card information, add an empty object to your controller and set it's class to one of the delegates. In this example, we’ll use CCCCardFormatterDelegate.
  2. Link your UITextField for card number to this class as it’s delegate.
    • If you want callbacks for other UITextFieldDelegate calls sent to your view controller, link the CCCCardFormatterDelegate classes 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.
  4. Your text field will now auto format and provide validation with the CCCCardFormatterDelegate isValidCard method.
    • When you’re ready to generate a token use the CCCCardFormatterDelegate setCardNumberOnCardInfo function to get the card number.
  5. When clearing text fields using the custom delegate classes, be sure to call clearTextField on the delegates themselves to clear internal information.

Implement the Swiper (optional)

Please complete the required Swiper Configuration before proceeding onto the following steps.

The below procedure should only be followed if you wish to use the BBPOS Chipper Mini Swiper to accept card-present swiped (MSR) transactions through your payment application.

See the BBPOS Chipper Mini 2 Device Compatibility List to ensure that your device is compatible.

  1. Add the CCCSwiperDelegate protocol to your view controller.
  2. Add the required methods from CCCSwiperDelegate to your view:
    • swiper:didGenerateTokenWithAccount:completion:
    • swiper:didFailWithError:completion
  3. Create a CCCSwiperController property in your view and initialize it in viewWillAppear:
    • self.swiper = [CCCSwiperController alloc] initWithDelegate:self loggingEnabled:YES];
  4. Set the swiper to nil in viewWillDisappear:
    • self.swiper = nil;
  5. At this point the swiper should initialize when the view appears. You can get the connection status using the optional methods in CCCSwiperDelegate.

iOS Customer Profile UI (optional)

The framework supports an integrated UI to manage user’s accounts, along with a theming class that allows you to customize its look. The integrated UI uses CardConnect's Profile Service to add, delete, edit and display a profile’s accounts with an easy to use interface.

The ThemeGuide folder in the SDK download contains further instructions on how to manipulate the theme of this user interface.

  1. Create a class that conforms to CCCAPIBridgeProtocol. This class will make the calls to your backend to perform the actions required by the UI.
  2. Setup your root view controller. This will be the view that presents and responds to the integrated UI flow. For example, the screen before the user will select their payment method.
  3. In your root view controller, add strong properties for your class that conform to CCCAPIBridgeProtocol and CCCPaymentController. If you wish 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 your API bridge class and the theme class. Initialize the payment controller using either initWithRootView:apiBridge:delegate: or initWithRootView:apiBridge:delegate:theme:.
  6. The payment controller supports two methods of display:
    • If you wish to push the integrated UI flow onto your current navigation stack, call [CCCPaymentController pushPaymentView]. This will require your root view to be contained within a navigation controller.
    • If you wish to present the integrated UI flow modally, call CCCPaymentController presentPaymentView.
  7. At this point the integrated UI will be presented 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.

Apple Pay Integration

The iOS Mobile SDK supports the ability to generate a token from data retrieved by Apple Pay. Clients will need to provision their own Apple Pay Merchant ID (with appropriate Identifier and Profile), and Certificate prior to submitting tokenization requests.

Please note: Apple Pay Device Personal Account Number (DPAN) is uniquely generated per transaction. Tokens generated by CardConnect in this manner should not be stored individually or within customer profiles.

Apple Pay Merchant Configuration

Creating a Merchant ID
  1. Log in to https://developer.apple.com/account
  2. Select Certificates, Identifiers & Profiles link on lefthand navigation bar.
  3. Select Merchant IDs link under Identifiers on lefthand navigation bar.
  4. Select + icon on the top right to create a new Merchant ID.
  5. Enter a description and identifier and hit Continue.
  6. Select Register.
Creating an Apple Pay Certificate and Uploading the CSR
  1. Log in to https://developer.apple.com/account
  2. Select Certificates, Identifiers & Profiles link on lefthand nav bar.
  3. Select All link under Certificates on lefthand nav bar.
  4. Select + icon on the top right to create a new certificate.
  5. Select Apple Pay Certificate radio button and hit Continue.
  6. Select the Merchant ID that was created.
  7. Click Create Certificate in the Payment Processing Certificate section.
  8. Answer questions and/or hit Continue until the Generate Certificate page is reached.
  9. Select the Choose File... button, select the CSR provided by CardConnect ('apple-pay-.csr' from step above), then hit Continue.
  10. Select Download to download the signed public key and hit the "Done" button.
  11. Send the apple_pay.cer file that was downloaded to CardConnect.
Configure the Application
  1. Within your Apple Developer account, enable Apple Pay in your provisioning profile with the merchant ID you configured for CardConnect.
  2. Enable Apple Pay under Capabilities by selecting your merchant ID from the list. If it doesn’t appear, find the {app_name}.entitlements file that was generated and add a string with your merchant ID in the merchant IDs array key.
  3. Ensure your application is set up to run with your provisioning profile and run the application or use the simulator.

Note: Using the simulator with Apple Pay will not generate payment data and the tokenization attempt will fail.

Custom Flow

A new function has been provided in CCCAPI called generateTokenForApplePay:completion:. This function takes the Apple Pay PKPayment object and generates a CardConnect token. Please see Apple’s documentation on implementing Apple Pay within your application here: Apple Pay Programming Guide.

Integrated Flow

The integrated UI supports a very basic Apple Pay flow. It handles display of the Apple Pay UI, token generation, and response of the result. You’ll need to make the authentication request through your API bridge class and forward the response.

  1. Follow the initial setup found in Apple Pay Programming Guide. to enable Apple Pay in your application.
  2. Create a CCCPaymentRequest object and set your merchant ID and amount to applePayMerchantID and Total respectively. An additionalData parameter is provided that can be used to store a reference, typically a transaction or order number.
  3. Before displaying your CCCPaymentController, set your CCCPaymentRequest to its paymentRequest parameter.
  4. In your class that conforms to the CCCAPIBridgeProtocol, implement the following which should use the token provided to make your authentication request and return the result in the completion block:
CCC_authApplePayTransactionWithToken:completion
  1. You can add the optional function paymentController:finishedApplePayWithResult: to your CCCPaymentController delegate for notification of an Apple Pay transaction.
  2. You can also customize how the Apple Pay UI is displayed using your `CCCTheme` class and the parameters:
applePayButtonDescription, applePayButtonStyle and applePayButtonType.

If the Apple Pay button doesn’t appear on the initial payment controller screen, enable debug logging on CCCAPI. When the screen appears, you will see a debug log for why the button isn’t available.

Some examples are:

  • “applePayMerchantID not set.”
  • “total not set or <= $0.”
  • “Device doesn’t support payments.”

Android

The Android SDK is currently in development. New features, such as EMV acceptance and support for new Bluetooth-enabled devices will be available soon. 

For more information, contact integrationdelivery@cardconnect.com.

Host Scripts

Tool Kit Introduction

The host scripts included in this discussion will work with the CardConnect Gateway API calls. These scripts will act as an intermediary between the customer’s application and the CardConnect server. The following sections will describe the activities executed by the host scripts as well as a summary of each file included in the customer host implementation.

These scripts are currently available in the following languages:

  • Python
  • Node

Tokenization timing

The tokens created by this process are long lived tokens generated per Profile and Account. Each account/payment method established for a profile will have its own token and that token will be used to represent the payment method for the duration of the account’s existence. The tokenization is executed when the account is first created. This occurs when the account is added to the profile within the SDK. The SDK will call the CardConnect server to add the account, generate the token, and transmit the token back to the SDK.

Payment Process Overview

The host scripts act as one element in a multi-component suite for executing credit card payments from a CardConnect customer’s application. The host scripts will execute the following actions:

  • Auth
  • Capture
  • Void
  • Refund
  • Funding
  • Profile
  • SigCap

The components of this suite are:

  • CardConnect customer’s mobile application (referred to as Customer Application in this document)
  • CardConnect's payment SDK
  • Host scripts (housed on the partner's server)
  • CardConnect Gateway and CardSecure

The payment process will follow this pattern:

  1. The Customer Application calls the Customer Server for profile information during login or other account setup. The Customer Server via the SDK will offer access to the Profile and associated Accounts via the SDK. The user can Add Account, Edit Account, Delete Account, or select an account for payment. The Customer Application retrieves a Profile ID for all subsequent operations.
  2. Once a transaction is established, the total amount calculated, and a payment method entered, the Customer Application sends the Profile ID and payment method to the CardConnect Server for tokenization (using a mobile SDK, not the Python SDK). The Customer Application then has a token associated to the Profile ID.
  3. Transaction details (except for the payment method) and the token are sent to the partner's server. The partner's server via the SDK performs an Auth, sending the token, amount, currency, and Profile ID. The host scripts executes the Auth with the CardConnect Server.
  4. The CardConnect Server returns a response approving/denying the charge to the partner's server. The partner's server returns an appropriate response to the Customer Application.

Python Toolkit & Details

Files in the CardConnectSDK root directory:

  • setup.py – Generates the Python build products. Used for distribution to places like PyPI.

  • tox.ini – Configures the tests in the SDK for execution inside a container (via Tox automation).

Files in the /cardconnect subdirectory:

  • init.py – Imports all components of the SDK for usage by a third party.

  • api_requestor.py – Classes for making requests to the CardConnect APIs.

  • service.py – Classes for Auth, Capture, Void, Refund ,Funding, Profile and SigCap – the core object types in the SDK.
  • error.py – Classes for error responses out of the SDK:

    • ApiError
    • ApiConnectionError
    • ApiAuthenticationError
    • ApiRequestError
  • http_client.py – Classes for HTTP communication to CardConnect APIs. Used by the API requestor.

  • util.py – Utilities classes for logging, imports, formatting, etc.

Files in the /cardconnect/test subdirectory:

Tox unit tests:
  • test_auth.py
  • test_capture.py
  • test_funding.py
  • test_profile.py
  • test_refund.py
  • test_sigcap.py
  • test_void.py

Files in the /examples subdirectory:

Functional examples for using each SDK component:
  • auth.py
  • capture.py
  • funding.py
  • profile.py
  • refund.py
  • sigcap.py
  • void.py

Node.js Toolkit & Details

Files in the CardConnectSDK root directory:

  • package.json – Sets the default test runner and dependencies that will be installed when NPM install is run.
  • gulpfile.js - Sets up the test functions and linters.

Files in the /cardconnect subdirectory:

  • cardconnect.js – The heart of the SDK. Contains definitions for Auth, Capture, etc.
  • api_requestor.js – Abstract class used by the SDK to send http requests.

Files in the /cardconnect/test subdirectory:

Unit tests:
  • test_auth.js
  • test_capture.js
  • test_funding.js
  • test_profile.js
  • test_refund.js
  • test_sigcap.js
  • test_void.js

Files in the /examples subdirectory:

Functional examples for using each SDK component:
  • auth.js
  • capture.js
  • funding.js
  • profile.js
  • refund.js
  • sigcap.js
  • void.js