Skip to main content

PCI SDK

Version License

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:

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!
  1. In the dependency section of your Podfile, add the Apto iOS SDK pod dependency:
def runtimepods
    ...
    pod 'AptoPCI'
    ...
  1. Open your Terminal app and navigate to your project's folder where the Podfile is contained:
    cd PATH_TO_PROJECT_FOLDER
  1. 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()
  1. Add pciView to your main view:
view.addSubview(pciView)pciView.translatesAutoresizingMaskIntoConstraints = falseNSLayoutConstraint.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),])
  1. 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 Enterprise programs.

  1. 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)
ParameterDescription
apiKeyThis value is the Mobile API Key (MOBILE_API_KEY) retrieved from the Apto Developer Portal.
userTokenThis value is the user session token (USER_TOKEN) retrieved from the login flow.
cardIdThis value is the account ID (ACCOUNT_ID) of the card with the format crd_XXXXXXXXXX.
environmentThis value is the environment that you are using for your app. The available values are:
  • PCIEnvironment.SBX - Sandbox
  • PCIEnvironment.PRD - Production
  1. (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")
  1. (Optional) Create a PCIConfigStyle object, passing any desired style settings. See Style Card Elements for more info.
val style = PCIConfigStyle(textColor: UIColor.red)
  1. 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)
  1. 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#

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

PropertyDescription
lastFourString value used as placeholders for the last 4 digits of the card when hidden. The default value is: ••••
nameOnCardString value specifying the name displayed on the card. The default value is an empty string.
labelNameString value specifying the text for the name description label. The default value is an empty string.
labelPanString value specifying the text for the PAN (Primary Account Number) description label. The default value is an empty string.
labelCvvString value specifying the text for the CVV description label. The default value is CVV.
labelExpString value specifying the text for the expiration date description label. The default value is EXP.

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:

ValueDescription
darkUse this value if you have a dark background. The card text will change to white.
lightUse 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:

PropertyDescription
textColorA String value specifying the color of the card text elements in Hex (i.e. FFFFFF for white)

Style Alerts#

Alerts appear:

  • To prompt the user to enter their SMS / email code
  • When the user incorrectly enters the SMS / email code.

The PCI SDK enables you to:

Style Alert Button Colors#

By default, the alert buttons use a dark text color. To customize the alert button:

  • Use the PCIConfigStyle object to set the alertButtonColor property:
    • When the pciView is initialized.
    • With the setStyle method after initialization is complete.

Style Alert Text#

To customize the text shown in alerts, assign a dictionary to the alertTexts property with the following values:

Text OptionDescription
inputCode.messageA string value specifying the Alert message text.
inputCode.okActionA string value specifying the OK button text.
inputCode.cancelActionA string value specifying the cancel button text.
wrongCode.messageA string value specifying the message displayed, when the user enters a wrong code.

Note: To see the wrong code message window, the user must enter an incorrect code 5 times.

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.