Skip to main content

PCI SDK

https://img.shields.io/maven-central/v/com.aptopayments.sdk/pci.svg?style=flat

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 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()

...

}
}
  1. 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>
  1. 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.

  1. 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
)
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 in which you are using your app. The available values are:
  • PCIEnvironment.SBX - Sandbox mode
  • PCIEnvironment.PRD - Production mode
  1. (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.

  2. (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")
  1. (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)
  1. 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)
  1. 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

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. (This feature will be available soon.)
labelPanString 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.)
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.
otpSubmitButtonString 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:

PropertyDescription
textColorAn 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.
labelPanA Map<String, String> dictionary specifying the style of the card pan elements using a CSS in JS object.
labelNameA Map<String, String> dictionary specifying the style of the card name elements using a CSS in JS object.
labelCvvA Map<String, String> dictionary specifying the style of the card cvv elements using a CSS in JS object.
labelExpA Map<String, String> dictionary specifying the style of the card exp elements using a CSS in JS object.
otpSubmitButtonA 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.