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 SDKs for the following platforms:

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.

  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 CardConnect Android SDK enables an application to tokenize payment information data through CardConnect’s CardSecure gateway and provides useful custom user interface components with formatting and validation options for payment information.

The Android CardConnect SDK zip file contains: :

  • ccconsumersdk-consumerSwiper-release.aar
  • Javadocs
  • Demo Application
  • Integration Guide.docx
  • Implementation Guide.docx

Import SDK into Payment App

  1. Open your project in Android Studio.
  2. Import the SDK into the project as a new module constructed from the AAR file (ccconsumersdk-consumerSwiper-release.aar).

    To create the new module:

    1. Click File > New > New Module > Import .JAR/.AAR Package.
    2. Locate ccconsumersdk-consumerSwiper-release.aar and click confirm.
  3. Make your created module available to the main payment application:
    1. Locate the build.gradle file pertaining to the application.
    2. Add the newly created module as an additional dependency in the dependencies block. The GSON and design support library dependency is required by the SDK and should be added here if it is not already present.
Sdk Android 1

Once the above steps are completed, classes from the new module will be available to use inside of the payment application after you sync or rebuild the project.

If the SDK has been installed successfully into the current project, the directory structure in Android Studio should look like this:

Sdk Android 3

Notice that there is a build.gradle file created for the newly added module. Also note that the settings.gradle file has an entry for both the main project and the newly added module. Each submodule will have an entry in the settings.gradle file to tell the build system that the module is now available.

Tokenize with a Custom UI

Tokenize the card data with a custom UI via CardSecure.

  1. Obtain the CardSecure URL.
  2. The SDK requires access to the CardSecure gateway to tokenize card information. This access is provided via a URL sent by CardConnect to the application implementer.

    To set this URL, the implementer calls the CCConsumer class which provides a Singleton to facilitate communication with the Consumer API:

CCConsumer._getInstance_().getApi().setEndPoint(""https://url/to/tokenize/data"" ); 
  1. Implement CCConsumerTokenCallback to listen for events from the Consumer API.
public class MainActivity extends AppCompatActivity implements CCConsumerTokenCallback {
    @Override
     protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout. activity\_main);
    }
    @Override
     public void onCCConsumerTokenResponseError(@NonNull CCConsumerError ccConsumerError) {
        //An error occurred trying to tokenize the data
        //Notify user of error
     }
    @Override
     public void onCCConsumerTokenResponse(@NonNull CCConsumerAccount ccConsumerAccount) {
        //Populate third party server request and send api call to proceed with the authorization.
     }}
    @Override
     protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout. **activity\_main** );
    }
  1. Populate information to the CCConsumerCardInfo object.

    There are two ways of populating this object:

    Populate card data information with Consumer SDK custom UI components:
    • CCConsumerCreditCardNumberEditText
    • CCConsumerCvvEditText
    • CCConsumerExpirationDateEditText

    If used, these components provide format options that are configurable. Check code documentation for more information.

    Card information through these components is not accessible from the implementer side, therefore the implementer needs to pass the CCConsumerCardInfo object to every component to populate internally. Check the Demo application for an example of how to populate this object.

    OR

    Populate CCConsumerCardInfo object manually.
    In this case, real card information should be set in the object. Check Documentation for more information.

  1. Process API Token GenerationAfter the CCConsumerCardInfo object is populated, call the generateTokenWithCard API:
CCConsumer._getInstance_().getApi().generateAccountForCard( **mCCConsumerCardInfo**** this**); 

Tokenize with Card Reader

Tokenization generation occurs internally within the consumer SDK together with the card reader implementation.

To generate the token using a card reader, an implementation of SwiperControllerListener interface must be provided by the implementer.

  1. Instantiate an implementation of the SwiperControllerListener.
SwiperControllerListener swiperControllerListener = new SwiperControllerListener() {
        @Override
        public void onTokenGenerated(CCConsumerAccount ccConsumerAccount, CCConsumerError ccConsumerError) {
            //Dismiss loading indicator in case was shown from onStartTokenGeneration()
            //Check ccConsumerError object != null first in case there was an error.
            //Populate third party server request and send api call to proceed with the payment.
        }
        @Override
        public void onError(SwipeError s) {
            //SwiperControllerListener callback: A Toast or some sort of other visual indicator can be displayed in the
            //event of a reader error or other transaction-related error.
        }
        @Override
        public void onSwiperReadyForCard() {
            //SwiperControllerListener callback: It is recommended that a visual indicator be shown here
            //notifying that the reader is ready for a card swipe.
        }
        @Override
        public void onSwiperConnected() {
            //SwiperControllerListener callback: It is recommended that a visual indicator be shown here
        }
        @Override
        public void onSwiperDisconnected() {
            //SwiperControllerListener callback: It is recommended that a visual indicator be shown here
            // notifying that the reader was disconnected.
        }
        @Override
        public void onStartTokenGeneration() {
            //Should use this callback to show some sort of loading indicator.
        } 
        @Override
        public void onBatteryState(BatteryState batteryState) {
            //Should use this callback to notify the user swiper is running out of battery_
        }
    };
}
  1. Inside of the onCreate() method of the payment Activity, instantiate a SwiperController object.
SwiperController mSwiper ;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout. activity\_main );
     //Initialize the swiper using the CCSwiperControllerFactory.
     mSwiper = ( new CCSwiperControllerFactory()).create( this , SwiperType. BBPosDevice , mSwiperControllerListener );
     //Optional enable debugging to print debug info generated inside the swiper class
     mSwiper.setDebugEnabled( true );
} 
  1. When the Activity corresponding to the payment screen is destroyed, the card reader resources must be cleaned up. In the Activity's onDestroy() lifecycle callback method, cleanup the resources.
@Override
protected void onDestroy() {
     super.onDestroy();
     //release() must be called in the Activity life cycle onDestroy() method
     mSwiper.release();
}

Android Pay Integration

Methods for accepting Android Pay are not available within the SDK at this time. The Android Pay integration will be available soon. We apologize for this inconvenience.

Android Customer Profile UI (optional)

The Consumer SDK also provides a built-in and configurable UI flow for account handling which allows the following operations:

  • List all consumer accounts
  • Delete specified consumer account
  • Update specified consumer account
  • Create specific account with token generation either to manual entry or MSR

The implementer can specify format options and UI elements theme configuration.

To integrate this UI custom flow implementer:

  1. Declare Built-in Activities in consumer application. This allows the consumer application to specify a desired theme configuration.
<!--Declare Consumer Sdk Activities in order to be able to change themes-->
<activity android:name="com.cardconnect.consumersdk.views.payment.accounts.PaymentAccountsActivity"
    android:theme="@style/ConsumerAppImplementer.Theme" />
<activity android:name="com.cardconnect.consumersdk.views.payment.createaccount.CreateAccountActivity"
    android:theme="@style/ConsumerAppImplementer.Theme" />
<activity android:name="com.cardconnect.consumersdk.views.payment.editaccount.EditAccountActivity"
    android:theme="@style/ConsumerAppImplementer.Theme" />
  1. Declare a specific theme that inherits from AppConsumerTheme.NoActionBar. For specific information regarding Theme configuration attributes, check Theme configuration resources included in the download.
<style name="ConsumerAppImplementer.Theme" parent="AppConsumerTheme.NoActionBar">
    <!--//TODO Override Attributes-->
</style>
  1. Implement CCConsumerApiBridge interface class to populate the Payments UI flow and perform operations with accounts.
public class ApiBridgeImpl implements CCConsumerApiBridge, Parcelable {
    //Parcelable implementation required for passing this object to Consumer SDK
    public static final Creator<ApiBridgeImpl> CREATOR = new Creator<ApiBridgeImpl>() {
        @Override
        public ApiBridgeImpl createFromParcel(Parcel in) {
            return new ApiBridgeImpl(in);
        }
        @Override
        public ApiBridgeImpl[] newArray(int size) {
            return new ApiBridgeImpl[size];
        }
    };
    public ApiBridgeImpl() {
    }
    protected ApiBridgeImpl(Parcel in) {
        //unused
    }
    @Override
    public void getAccounts(@NonNull final CCConsumerApiBridgeCallbacks apiBridgeCallbacks) {
        final CCConsumerApiBridgeGetAccountsResponse response = new CCConsumerApiBridgeGetAccountsResponse();
        //TODO Implement get Accounts from Third party server here
        //TODO provide result through apiBridgeCallbacks object
    }
    @Override
    public void saveAccountToCustomer(@NonNull final CCConsumerAccount account,
            @NonNull final CCConsumerApiBridgeCallbacks apiBridgeCallbacks) {
        final CCConsumerApiBridgeSaveAccountResponse response = new CCConsumerApiBridgeSaveAccountResponse();
        //TODO Implement add Account to Profile from Third party server here
        //TODO provide result through apiBridgeCallbacks object
    }
    @Override
    public void deleteCustomerAccount(@NonNull CCConsumerAccount accountToDelete,
            @NonNull final CCConsumerApiBridgeCallbacks apiBridgeCallbacks) {
        final CCConsumerApiBridgeDeleteAccountResponse response = new CCConsumerApiBridgeDeleteAccountResponse();
        //TODO Implement remove Account to Profile from Third party server here                //TODO provide result through apiBridgeCallbacks object
    }
    @Override
    public void updateAccount(@NonNull CCConsumerAccount account,
            @NonNull final CCConsumerApiBridgeCallbacks apiBridgeCallbacks) {
       //TODO Implement update Account to Profile from Third party server here
       //TODO provide result through apiBridgeCallbacks object
    }
    @Override
    public int describeContents() {
        return 0;
    }
    @Override
    public void writeToParcel(Parcel dest, int flags) {
        //unused
    }
}
  1. Start PaymentsActivity and pass CCConsumerApiBridge implementation object.
ApiBridgeImpl apiBridgeImpl = new ApiBridgeImpl();
Intent intent = new Intent(this, PaymentAccountsActivity.class);
intent.putExtra(PaymentAccountsActivity.API_BRIDGE_IMPL_KEY, apiBridgeImpl);
startActivityForResult(intent, PaymentAccountsActivity.PAYMENT_ACTIVITY_REQUEST_CODE);
  1. In addition to theme attributes, mask options can be specified through CCConsumerCardFormatter together with API Bridge implementation class.
ConsumerCardFormatter formatter = new CCConsumerCardFormatter();
formatter.setCCConsumerMaskFormat(CCConsumerMaskFormat.CARD_MASK_LAST_FOUR);
formatter.setMaskCharacter('*');
formatter.setCCConsumerExpirationDateSeparator(CCConsumerExpirationDateSeparator.DASH);
formatter.setCCConsumerCardMaskSpacing(CCConsumerCardMaskSpacing.CARD_MASK_SPACING_EVERY_CHARACTER);
intent.putExtra(PaymentAccountsActivity.CARD_FORMAT_OPTIONS_KEY,formatter);
startActivityForResult(intent, PaymentAccountsActivity.PAYMENT_ACTIVITY_REQUEST_CODE);
  1. Receive Account from Payments UI if selected.
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    //Get Account selected by integrated UI flow
    if (requestCode == PaymentAccountsActivity.PAYMENT_ACTIVITY_REQUEST_CODE && resultCode == RESULT_OK) {
        //Example of displaying account selected
        CCConsumerAccount selectedAccount =
                data.getParcelableExtra(PaymentAccountsActivity.PAYMENT_ACTIVITY_ACCOUNT_SELECTED);
        Log.d(TAG, "Selected Account: " + selectedAccount.getAccountType().toString() + ", " +
                selectedAccount.getLast4());
    }
}

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