PCI SDK

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

This document provides an overview of how to:

Install the SDK
Initialize the SDK
Show / Hide the PCI Data
Check if the PCI Data is Visible
Set the PIN
Customize the PCI View

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.

In order to initialize the SDK you'll need to supply both Mobile API credentials: an API key and a Session Token.

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 either by:

Following the authentication process for the Mobile API (involves few calls)
Calling the get_session_token endpoint from the Core API (single call)
Using our Mobile SDKs
- on iOS
- on Android

info

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:

Retrieve a cardholder ID from the Core API’s list_cardholders endpoint.
Use the cardholder ID to retrieve a card ID from the Core API’s list_cardholder_cards endpoint.

info

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
Install using CDN

Install using NPM

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

npm i @apto-payments/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 3.0.0.

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

tip

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

Initialize the SDK

To initialize the SDK:

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>

info

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.

Create an OptionsObject. The example below shows what it looks like. Replace the values of the properties as desired. See OptionsObject Properties for a complete overview and details on optional properties and possible values.
Ensure you replace the following with the appropriate values:
- USER_SESSION_TOKEN
- UNIQUE_CARD_ID
- MOBILE_API_KEY

caution

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',
  },
  element: document.getElementById('apto-pci-sdk'),
  networkLogo: {
    symbol: 'visa-white',
  },
  theme: 'light',
  values: {
    lastFour: '****',
    labelPan: 'Card Number',
    labelCvv: 'CVV',
    labelExp: 'Exp Date',
    labelName: 'Full Name',
    nameOnCard: 'Jane Doe',
  },
};

Invoke the AptoPCISdk.init method and pass in the options object:

AptoPCISdk.init(options);

OptionsObject Properties

The OptionsObject has the following properties:

Property	Required?	Description
`auth`	Yes	The 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)
`element`	No	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`.
`networkLogo`	No	The object used to display the card's network logo. If `networkLogo` is not specified, the card network logo won't be displayed. Contains the following properties: `position` (Optional): To place the logo in one of the four corners of the container. The default value is `bottom-right`. The values can be: `top-right` to position the logo in the top-right `bottom-right` to position the logo in the bottom-right `bottom-left` to position the logo in the bottom-left `top-left` to position the logo in the top-left `size` (Optional): To change the default size of the symbol. The default size is designed to display correctly on a horizontal card layout. If you are using the Web PCI SDK to render another layout, you can use this option to adjust the size, as the default size is probably unbalanced. It is recommended to use `vw` units so that the logo scales proportionally on all screen sizes. `symbol`: To select among several brand marks from our partner networks. The values can be: `mastercard` `visa-blue` `visa-white`
`theme`	No	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.
`values`	No	The object defining the text information on the card. This object can have the following properties: `codePlaceholderMessage` (Optional): String value used as placeholders OTP code input. The default value is `Enter the code`. `expiredMessage` (Optional): String value used for the message displayed when the OTP session expired. The default value is `Process expired. Start again.`. `failed2FAPrompt` (Optional): String value used for the message displayed when the OTP inserted is invalid. The default value is `Wrong code. Try again.`. `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. `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. `lastFour` (Optional): String value used as placeholders for the last 4 digits of the card when hidden. The default value is `••••`. `nameOnCard` (Optional): String value specifying the cardholder's name displayed on the card. The default value is an empty string. `otpSubmitButton` (Optional): String value used for the submit button on the OTP form. The default value is `Send`. `pinPlaceholderMessage` (Optional): String value used as placeholders for the change PIN input. The default value is `Enter your new PIN`. `pinUpdatedMessage` (Optional): String value used for the message displayed when the PIN is changed. The default value is `Pin successfully updated`. `setPinSubmitButton` (Optional): String value used for the submit button on the prebuilt form to change the pin. The default value is `Update`. `tooManyAttemptsMessage` (Optional): String value used for the message displayed when too many OTP attempts are performed. The default value is `Too many attempts. Start again.`.

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. This method returns a Promise.

const isDataVisible = await AptoPCISdk.getIsDataVisible();

Set the PIN

We provide a prebuilt form to allow cardholders to be able to change their card's PIN. You only need to display the form and the SDK will handle everything for you.

caution

This feature was introduced in PCI SDK Web 3.4.X. Make sure you are using the correct version of the SDK.

You can display this form invoking the showSetPinForm method:

AptoPCISdk.showSetPinForm();

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 PIN will be updated.

You can customize the placeholder of the input specifying a pinPlaceholderMessage when initializing the SDK.

Customize the PCI View

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

tip

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 light backgrounds, and the dark theme is best used against dark backgrounds.

Apply a Custom Style

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

tip

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.

Create an ITheme object. Both the container with the PCI data and the inline form can be styled. See ITheme object for more detailed info.

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
  },
  inlineForm: {
    container: {
      display: 'flex',
      flexWrap: 'wrap',
    },
    input: {
      marginTop: '7.06vw', //24px
      borderRadius: '3.53vw', //'12px',
    },
    submit: {
      borderRadius: '3.53vw', //'12px',
    },
  },
  notification: {
    positive: {
      backgroundColor: '#33DE71',
    },
    negative: {
      backgroundColor: '#DE5233',
    },
  },
};

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.

info

All the ITheme properties are optional.

Property	Object Type	Description
`extends`	`IThemeName`	Use this to specify an existing theme to extend. Available values are `light` or `dark`. See Extend a Theme for more information.
`container`	`CSSProperties`	Use this to style the entire PCI card data container.
`shared`	`CSSProperties`	Use this to style the areas containing the card data. For example, the card number, CVV, expiration date, etc.
`groups`	`CSSProperties`	Use 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.
`groupName`	`CSSProperties`	Use this to style the area surrounding the cardholder's name and its associated label.
`groupPan`	`CSSProperties`	Use this to style the area surrounding the PAN and its associated label.
`groupCvv`	`CSSProperties`	Use this to style the area surrounding the CVV and its associated label.
`groupExp`	`CSSProperties`	Use this to style the area surrounding the expiration date and its associated label.
`labels`	`CSSProperties`	Use this to style the name, PAN, CVV, and expiration date labels.
`labelName`	`CSSProperties`	Use this to style the cardholder's name label.
`labelPan`	`CSSProperties`	Use this to style the PAN label.
`labelCvv`	`CSSProperties`	Use this to style the CVV label.
`labelExp`	`CSSProperties`	Use this to style the expiration date label.
`name`	`CSSProperties`	Use this to style the cardholder's name.
`pan`	`CSSProperties`	Use this to style the PAN text.
`cvv`	`CSSProperties`	Use this to style the CVV text.
`exp`	`CSSProperties`	Use this to style the expiration date.
`inlineForm`	`{[key: string]: CSSProperties}`	Use this to style the inline form used to change the pin or set the 2FA code. This object can have the following properties: `container` (Optional): Use this to override default styles on the form container with your own. `input` (Optional): Use this to override default styles on the form input with your own. `submit` (Optional): Use this to override default styles on the submit button with your own.
`notification`	`{[key: string]: CSSProperties}`	Use this to style the notification message appearing at the bottom of the card. This object can have the following properties: `positive` (Optional): Use this to override default styles on the positive notifications with your own. `negative` (Optional): Use this to override default styles on the negative notifications with your own.

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:

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

PCI SDK

Requirements​

Get the Mobile API key​

Get a User Session Token​

Get a Cardholder’s Card ID​

Install the SDK​

Install using NPM​

Install using CDN​

Initialize the SDK​

OptionsObject Properties​

Show / Hide the PCI Data​

Check if the PCI Data is Visible​

Set the PIN​

Customize the PCI View​

Set the Theme​

Apply a Custom Style​

ITheme Object​

Extend a Theme​

Contributions & Development​

Requirements

Get the Mobile API key

Get a User Session Token

Get a Cardholder’s Card ID

Install the SDK

Install using NPM

Install using CDN

Initialize the SDK

OptionsObject Properties

Show / Hide the PCI Data

Check if the PCI Data is Visible

Set the PIN

Customize the PCI View

Set the Theme

Apply a Custom Style

ITheme Object

Extend a Theme

Contributions & Development