PCI SDK

caution

These are the docs for PCI SDK Web 3.5.1. We highly recommend to use the latest version of the PCI SDK Web.

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.

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 Core API, 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 Core API’s list_cardholders endpoint.

2. Use the cardholder ID to retrieve a card ID from the Core API’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
• 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>

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.

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

   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',
  },
  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',
  },
};

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

Note: 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.

note

This feature has been 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 and 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. See the example down below.

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

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. Both the container with the PCI data and the OTP 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
  },
  formOTPSubmit: {
    backgroundColor: '#212121',
  },
  notification: {
    color: '#ECEFF1',
  },
};

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

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.
formOTP	CSSProperties	Use this to style the OTP form container.
formOTPInput	CSSProperties	Use this to style the text input in the OTP form.
formOTPSubmit	CSSProperties	Use this to style the submit button in the OTP form.
notification	CSSProperties	Use this to style the notification message appearing at the top of the card.

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.