PCI SDK

The Apto PCI SDK provides a transparent View that can display the PCI data using a webView.

This document provides an overview of how to:

• PCI SDK
  • Requirements
    • Get the Mobile API key
  • Install the SDK
  • Initialize the SDK
  • Show / Hide the PCI Data
  • Change Card PIN
  • Customize the PCI View
    • Display Card Data Elements
    • Style Card Elements
  • Contributions & Development
  • License

You can access the iOS PCI SDK on GitHub.

To contribute to the SDK development, see Contributions & Development

Requirements

• iOS 10.0 (minimum version)
• Swift 5 (minimum version)
• CocoaPods. No minimum version is required, but version 1.8.3 or higher is recommended.

Get the Mobile API key

A Mobile API Key is required to run the SDK. To retrieve your Mobile API Key see Get the Mobile API Key for the SDKs.

Install the SDK

We suggest using CocoaPods to install the SDK:

1. At the top of your project's Podfile, ensure the platform is set to iOS 10 or higher, and frameworks are enabled:

platform :ios, '10.0'

...

use_frameworks!

2. In the dependency section of your Podfile, add the Apto iOS SDK pod dependency:

def runtimepods

    ...

    pod 'AptoPCI'

    ...

3. Open your Terminal app and navigate to your project's folder where the Podfile is contained:

    cd PATH_TO_PROJECT_FOLDER

4. Install the SDK with the following command:

    pod install

Initialize the SDK

To initialize the PCI SDK:

1. Create a PCIView object:

let pciView = PCIView()

2. Add pciView to your main view:

view.addSubview(pciView)
pciView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
  pciView.topAnchor.constraint(equalTo: topConstraint, constant: 40),
  pciView.leftAnchor.constraint(equalTo: view.leftAnchor, constant: 20),
  pciView.rightAnchor.constraint(equalTo: view.rightAnchor, constant: -20),
  pciView.heightAnchor.constraint(equalToConstant: 240),
])

3. You will need to use the [iOS Mobile SDK/docs/sdks/iOS/mobile_sdk_ios), the Mobile API, or the Core API to retrieve the following values:

   • User Session Token
   • Card account ID

Note: The Core API option is only available to Blue or Orange Programs.

4. Create a PCIConfigAuth object. This manages the authentication configuration settings.

let configAuth = PCIConfigAuth(
    cardId: "ACCOUNT_ID",
    apiKey: "MOBILE_API_KEY",
    userToken: "USER_TOKEN",
    environment: .sbx)

Parameter	Description
apiKey	This value is the Mobile API Key (MOBILE_API_KEY) retrieved from the Apto Developer Portal.
userToken	This value is the user session token (USER_TOKEN) retrieved from the login flow.
cardId	This value is the account ID (ACCOUNT_ID) of the card with the format crd_XXXXXXXXXX.
environment	This value is the environment that you are using for your app. The available values are: PCIEnvironment.SBX - Sandbox PCIEnvironment.PRD - Production

5. (Optional) Create a PCIConfigCard object, passing in the cardholder's name and the last four digits of the card. See Display Card Data Elements for more info.

let configCard = PCIConfigCard(lastFour: "XXXX",
                               nameOnCard: "NAME_ON_CARD")

6. (Optional) Create a PCIConfigStyle object, passing any desired style settings. See Style Card Elements for more info.

val style = PCIConfigStyle(textColor: UIColor.red)

7. Create a PCIConfig object, passing in the configAuth, configCard, and/or style parameters. See Display Card Data Elements for more information about the PCIConfig object.

let config = PCIConfig(configAuth: configAuth,
                       configCard: configCard,
                       style: style)

8. Initialize the PCI view using pciView.initialise, passing in the pciConfig as the PCIConfig object.

pciView.initialise(pciConfig)

Note: Initialization should only be applied once.

Show / Hide the PCI Data

The PCI SDK enables you to:

• Show the card's complete data. To show the card's complete data, use the showPCIData method: pciView.showPCIData().

  The user will receive an SMS or email with a one-time passcode. This passcode must be entered into the displayed dialog box. If the passcode is correct, the PCI data will be shown. When testing in the Sandbox environment, you must use 000000 as the OTP code.

  Note: This method must be called after the pciView is fully initialized to avoid sending multiple SMS / email codes. We suggest requiring the user to click a button or other UI element to initiate the showPCIData() method.

• Show only the card's last four digits (if set). This hides all of the PCI data. To hide all the PCI data except for the card's last four digits, use the hidePCIData method: pciView.hidePCIData().

Change Card PIN

In addition to this, the PCI SDK allows a user to change their card PIN. To initiate this process use the showSetPinForm method: pciView.showSetPinForm().

The user will receive an SMS or email with a one-time passcode. This passcode must be entered into the displayed dialog box. If the passcode is correct, the user will be prompted to enter the new card PIN. When testing in the Sandbox environment, you must use 000000 as the OTP code.

Customize the PCI View

The PCI SDK uses configuration objects to change the default PCI configuration. The following elements can be customized:

• Display Card Data Elements
• Style Card Elements

Display Card Data Elements

The PCIConfigCard object is used to set card configurations. The following configurations are available:

Property	Description
lastFour	String value used as placeholders for the last 4 digits of the card when hidden. The default value is ••••
nameOnCard	String value specifying the name displayed on the card. The default value is an empty string.
labelName	String value specifying the text for the name description label. The default value is an empty string.
labelPan	String value specifying the text for the PAN (Primary Account Number) description label. The default value is an empty string.
labelCvv	String value specifying the text for the CVV description label. The default value is CVV.
labelExp	String value specifying the text for the expiration date description label. The default value is EXP.
otpSubmitButton	String value used for the submit button on the OTP form. The default value is Send.

Style Card Elements

To style the PCIView with a theme, use the setTheme method anytime after initialization. The method can receive one the following values:

Value	Description
dark	Use this value if you have a dark background. The card text will change to white.
light	Use this value if you have a light background. The card text will change to black.

To style the PCIView with specific configurations, use the PCIConfigStyle object:

• When the pciView is initialized.
• In the setTheme method anytime after initialization.

The following configuration options are available for the PCIConfigStyle:

Property	Description
textColor	A String value specifying the color of the card text elements in Hex (i.e. FFFFFF for white)
labelPan	A [String: String] dictionary specifying the style of the card pan elements using a CSS in JS object.
labelName	A [String: String] dictionary specifying the style of the card name elements using a CSS in JS object.
labelCvv	A [String: String] dictionary specifying the style of the card cvv elements using a CSS in JS object.
labelExp	A [String: String] dictionary specifying the style of the card exp elements using a CSS in JS object.
otpSubmitButton	A Map<String, String> dictionary specifying the style of the submit button in the OTP form using a CSS in JS object.

To style the card labelCvv element you can use the following setup:

    let configStyle = PCIConfigStyle(textColor: "#FFFFFF",
                                     labelCvv: [
                                        "color": "#444",
                                        "fontSize": "3.53vw",
                                        "textTransform": "lowercase"
                                     ])

Contributions & Development

We look forward to receiving your feedback, including new feature requests, bug fixes and documentation improvements.

If you would like to help:

1. Refer to the issues section of the repository first, to ensure your feature or bug doesn't already exist (The request may be ongoing, or newly finished task).
2. If your request is not in the issues section, please feel free to create one. We'll get back to you as soon as possible.

If you want to help improve the SDK by adding a new feature or bug fix, we'd be happy to receive pull requests!

License

AptoPCI is available under the MIT license. See the LICENSE file for more info.