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 Android PCI SDK on GitHub.

To contribute to the SDK development, see Contributions & Development

Requirements

• Android SDK, minimum API Level 23 (Marshmallow)
• One of the following for testing:
  • Android device running Android 6.0 (API Level 23) or higher.
  • Android emulator running Android 7.0 (API Level 24) or higher.
• Kotlin, minimum version 1.5.21
• Gradle, minimum version 7.0.0

Note: The SDK is built using Kotlin, but is fully interoperable with Java. Code adjustments may be needed, if used within a Java project.

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

1. In your project's build.gradle file, add the Apto repository:

allprojects {
  repositories {

    ...

    mavenCentral()

    ...

  }
}

2. In your app's build.gradle, add the following dependency:

implementation 'com.aptopayments.sdk:pci:3.1.0'

Initialize the SDK

To initialize the PCI SDK:

1. Add a PCIView to your layout.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools" android:id="@+id/main" android:layout_width="match_parent" android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.cardview.widget.CardView
      android:id="@+id/cardView"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:layout_gravity="center"
      android:layout_margin="20dp"
      app:cardCornerRadius="8dp"
      app:layout_constraintTop_toTopOf="@id/main">

        ...

        <com.aptopayments.sdk.pci.PCIView
            android:id="@+id/pci_view"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />
    </androidx.cardview.widget.CardView>

    ...

</androidx.constraintlayout.widget.ConstraintLayout>

2. You will need to use the Android Mobile SDK, 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.

3. In a class that can access your pci_view component, create a PCIConfigAuth object. This manages the authentication configuration settings.

val configAuth = PCIConfigAuth(
    apiKey = "MOBILE_API_KEY",
    userToken = "USER_TOKEN",
    cardId = "ACCOUNT_ID",
    environment = PCIEnvironment.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 in which you are using your app. The available values are: PCIEnvironment.SBX - Sandbox mode PCIEnvironment.PRD - Production mode

4. (Optional) Create a theme object, passing either light or dark to define the style of the views that will be seen in the card when asking for the OTP code.

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.

val configCard = PCIConfigCard(nameOnCard = "NAME_ON_CARD", lastFour = "1234")

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

val color = resources.getColor(R.color.card_text_color, null)
val style = PCIConfigStyle(textColor = color)

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

val pciConfig = PCIConfig(configAuth = configAuth, configCard = configCard, style = style)

8. Initialize the PCI view using pci_view.init, passing in the pciConfig as the PCIConfig object.

pci_view.init(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: pci_view.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 pci_view 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: pci_view.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: pci_view.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. (This feature will be available soon.)
labelPan	String value specifying the text for the PAN (Primary Account Number) description label. The default value is an empty string. (This feature will be available soon.)
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:

• Use the PCIConfigStyle object:
  • When the pci_view is initialized.
  • In the setStyle method anytime after initialization.
• Override the values in the colors.xml file.

The following configuration options are available:

Property	Description
textColor	An Int value specifying the color of the card text elements. This will override the default color value set for the pcisdk_text_color property in the colors.xml file.
labelPan	A Map<String, String> dictionary specifying the style of the card pan elements using a CSS in JS object.
labelName	A Map<String, String> dictionary specifying the style of the card name elements using a CSS in JS object.
labelCvv	A Map<String, String> dictionary specifying the style of the card cvv elements using a CSS in JS object.
labelExp	A Map<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.

Note: Colors must be specified with the resources.getColor() method. For example, useresources.getColor(R.color.quantum_googred, theme: null) instead of the standalone R.color.quantum_googred.

Note: For more information about the styling options for the Map<String,String> object, see the Web PCI iTheme object. Example:

val style = PCIConfigStyle(
    labelCvv = mapOf(
        "color" to "#444",
        "fontSize" to "3.53vw",
        "textTransform" to "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

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