PCI SDK for the web

Apto Web PCI SDK#

https://img.shields.io/npm/v/@apto-payments/pci-sdk-web?label=%40apto-payments%2Fpci-sdk-web&style=flat-square https://img.shields.io/npm/v/@apto-payments/pci-sdk-iframe?label=%40apto-payments%2Fpci-sdk-iframe&style=flat-square

The Apto Web PCI SDK enables developers to display protected PCI data using an iFrame.

This document provides an overview of how to:

You can access the Web PCI SDK on GitHub.

To contribute to the SDK development, see Contributions & Development.

Requirements#

  • HTML
  • JavaScript
  • CSS - Optional, but required for custom styling.

Note: The Web PCI SDK does not create user sessions or retrieve general user information. Instead it consumes an existing user session token and an existing card ID.

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.

Get a User Session Token#

The Web PCI SDK does not generate its own user session token. Therefore you must obtain a token using one of the mobile SDKs or the Core API.

To obtain a token from the CoreAPI, use the get_session_token endpoint.

Note: USER_SESSION_TOKEN is used throughout this document to represent your user session token. Ensure you replace USER_SESSION_TOKEN with the user session token you obtained.

Get a Cardholder’s Card ID#

The Web PCI SDK consumes a card ID from an existing cardholder.

You can obtain a card ID from the Core API:

  1. Retrieve a cardholder ID from the CoreAPI’s list_cardholders endpoint.

  2. Use the cardholder ID to retrieve a card ID from the CoreAPI’s list_cardholder_cards endpoint.

    Note: UNIQUE_CARD_ID is used throughout this document to represent the card ID for the card displayed in the PCI view. Ensure you replace UNIQUE_CARD_ID with the card ID you retrieved.

Install the SDK#

There are two methods for installing the Web PCI SDK:

Install using NPM#

To install the SDK using NPM, open your terminal application and install the SDK using the following command:

npm i @apto/pci-sdk-web

Install using CDN#

To install the SDK using CDN, include the following script in your HTML file.

<script src="https://cdn.jsdelivr.net/npm/@apto-payments/pci-sdk-web@VERSION_NUMBER/dist/umd/apto-pci-sdk.min.js"></script>

Ensure you replace VERSION_NUMBER with the SDK version you'd like to use. The current version available is listed at the top of this document. For example version 2.0.0.

<script src="https://cdn.jsdelivr.net/npm/@apto-payments/pci-sdk-web@2.0.0/dist/umd/apto-pci-sdk.min.js"></script>

Note: We use a semantic versioning scheme for the Web PCI SDK.

Initialize the SDK#

To initialize the SDK:

  1. Create an HTML element to contain the PCI SDK iFrame. Ensure you specify your custom element ID. For example:
<div id="apto-pci-sdk"></div>

Note: The element's ID will be used in the next step, to pass into the SDK. Use the apto-pci-sdk id for your element to avoid specifying the optional element property in the OptionsObject.

  1. Create an OptionsObject. See OptionsObject Properties for more info.

    Ensure you replace the following with the appropriate values:

    • USER_SESSION_TOKEN
    • UNIQUE_CARD_ID
    • MOBILE_API_KEY
    • apto-pci-sdk (Optional: Only required if using a custom HTML element ID)

    Note: Ensure you set the correct apiKey for the correct environment. See Get the Mobile API Key for the SDKs for more information.

var options = {
auth: {
userToken: 'USER_SESSION_TOKEN',
cardId: 'UNIQUE_CARD_ID',
apiKey: 'MOBILE_API_KEY',
environment: 'sbx', // Accepted values: 'sbx' | 'prd'
},
theme: 'light', // (Optional) Accepted values: 'light' | 'dark'
element: document.getElementById('apto-pci-sdk'), // (Optional) Default id: 'apto-pci-sdk'
values: {
// (Optional)
lastFour: '****', // (Optional) Default: '****'
labelPan: 'Card Number', // (Optional) Default: 'Card number'
labelCvv: 'CVV', // (Optional) Default: 'CVV'
labelExp: 'Exp Date', // (Optional) Default: 'EXP'
labelName: 'Full Name', // (Optional) Default: 'Name'
nameOnCard: 'Jane Doe', // (Optional) Default: ''
},
};
  1. Invoke the AptoPCISdk.init method and pass in the options object:
AptoPCISdk.init(options);

OptionsObject Properties#

The OptionsObject has the following properties:

Property NameDescription
authThe authentication object containing the following properties:
  • userToken: The user session token USER_SESSION_TOKEN. See Get a User Session Token for more info.
  • cardId: The ID for the card UNIQUE_CARD_ID. See Get a Cardholder’s Card ID for more info.
  • apiKey: The mobile API key provided by Apto MOBILE_API_KEY. See Get the Mobile API key for more info.
  • environment: The deployment environment. The values can be:
    • sbx (Sandbox)
    • prd (Production)
theme (Optional)The name of a predefined theme. By default, the PCI view has a transparent background. The theme values can be:
  • light: This theme is best used over a light background.
  • dark: This theme is best used over a dark background.
Note: Both themes expect the iFrame to have an ID-1 aspect ratio.
element (Optional)The HTML element for mounting the iFrame. If element is not specified, the PCI SDK will attempt to mount the iFrame to an element with the id apto-pci-sdk.
values (Optional)The object defining the text information on the card. This object can have the following properties:
  • lastFour (Optional): String value used as placeholders for the last 4 digits of the card when hidden. The default value is: ••••
  • labelPan (Optional): String value specifying the text for the PAN (Primary Account Number) description label. The default value is Card number.
    Note: This field is hidden by default.
  • labelCvv (Optional): String value specifying the text for the CVV description label. The default value is CVV.
  • labelExp (Optional): String value specifying the text for the expiration date description label. The default value is EXP.
  • labelName (Optional): String value specifying the text for the name description label. The default value is Name.
    Note: This field is hidden by default.
  • nameOnCard (Optional): String value specifying the name displayed on the card. The default value is an empty string.

Show / Hide the PCI Data#

The PCI data can be displayed or hidden.

To show the complete card data, use the showPCIData method:

AptoPCISdk.showPCIData();

If the client is not PCI-compliant, an SMS / email message will be sent to the user with a one-time code.

  • This code must be entered into the dialog display. When testing in the Sandbox environment, you must use 000000 as the OTP code.
  • If the code entered is correct, the PCI data will be displayed.

To hide the card data, use the hidePCIData method:

AptoPCISdk.hidePCIData();

Check if the PCI Data is Visible#

To check if the PCI data is visible, use the getIsDataVisible method.

Note: This method returns a Promise.

const isDataVisible = await AptoPCISdk.getIsDataVisible();

Customize the PCI View#

The PCI View can be customized with a theme and/or custom style.

Note: For security/legal reasons Apto custom content may not be injected into the secured iFrame. Therefore if you want to add a logo to a card, we suggest adding the logo into the PCI SDK div element as a CSS background. For example:

<div
id="apto-pci-sdk"
style="
background-color: white;
background-image: url(https://example.com/logo.jpg);
background-repeat: no-repeat;
background-position: 10% 90%;
background-size: 48px;
background-position-x: 90%;
"
></div>

Set the Theme#

To set the PCI theme to a light or dark theme, use the setTheme method:

AptoPCISdk.setTheme('dark');

By default, the PCI view has a transparent background. The light theme is best used against dark backgrounds, and the dark theme is best used against light backgrounds.

Apply a Custom Style#

To apply custom style settings to the PCI View, use the setStyle method.

Note: The setStyle method overwrites any previously set ITheme objects. If you'd like to create multiple styles, you can store your ITheme objects as stored variables and apply them as needed using the setStyle method.

  1. Create an ITheme object. See ITheme object for more detailed info about elements that can be styled.
const style = {
extends: 'dark',
labels: {
color: '#444',
fontSize: '3.53vw', //'12px',
textTransform: 'uppercase',
},
labelCvv: {
display: 'initial',
marginRight: '2.94vw', //'10px',
},
labelExp: {
display: 'initial',
marginRight: '2.94vw', //'10px',
},
labelName: {
display: 'block',
},
labelPan: {
display: 'block',
},
pan: {
fontSize: '7.06vw', //24px
},
};
  1. Pass the style parameter into setStyle:
AptoPCISdk.setStyle(style);

ITheme Object#

The ITheme object contains a set of controlled set of elements to that can be styled. Each element can be styled using a CSS in JS object.

Note: All the ITheme properties are optional.

PropertyObject TypeDescription
extendsIThemeNameUse this to specify an existing theme to extend. Available values are light or dark. See Extend a Theme for more information.
containerCSSPropertiesUse this to style the entire PCI container.
sharedCSSPropertiesUse this to style the areas containing the card data. For example, the card number, CVV, expiration date, etc.
groupsCSSPropertiesUse this to style the areas containing the card data and its associated label. For example, the PAN and PAN label, CVV and CVV label, expiration date and expiration date label, etc.
groupNameCSSPropertiesUse this to style the area surrounding the cardholder's name and its associated label.
groupPanCSSPropertiesUse this to style the area surrounding the PAN and its associated label.
groupCvvCSSPropertiesUse this to style the area surrounding the CVV and its associated label.
groupExpCSSPropertiesUse this to style the area surrounding the expiration date and its associated label.
labelsCSSPropertiesUse this to style the name, PAN, CVV, and expiration date labels.
labelNameCSSPropertiesUse this to style the cardholder's name label.
labelPanCSSPropertiesUse this to style the PAN label.
labelCvvCSSPropertiesUse this to style the CVV label.
labelExpCSSPropertiesUse this to style the expiration date label.
nameCSSPropertiesUse this to style the cardholder's name.
panCSSPropertiesUse this to style the PAN text.
cvvCSSPropertiesUse this to style the CVV text.
expCSSPropertiesUse this to style the expiration date.

Extend a Theme#

PCI themes can be extended. If desired, you can extend one of the themes Apto provides. This enables you to change only the properties you want to adapt for the design, without having to style all the elements that appear in the PCI View. To make the most of this feature, ensure you take the following into account:

  • The PCI View mounts an iFrame that scales to the width of the parent container. This means the Web PCI themes:

    • Express font-size in vw to enable proper scaling across all device sizes.
    • Use a reference viewport of 340px to calculate these units.

    If you want to change the font size of elements in the Web PCI themes, we advise you account for the vw font and viewport size, to ensure you maintain the proportions in your design.

  • The Web PCI themes use CSS Flexbox to position the elements. This enables you to easily change the position by modifying the CSS rules of the container and grouping elements.

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.