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
- Customize the PCI View
You can access the Web PCI SDK on GitHub.
To contribute to the SDK development, see Contributions & Development.
- CSS - Optional, but required for custom styling.
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.
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
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.
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 CoreAPI’s
Use the cardholder ID to retrieve a card ID from the CoreAPI’s
UNIQUE_CARD_IDis used throughout this document to represent the card ID for the card displayed in the PCI view. Ensure you replace
UNIQUE_CARD_IDwith the card ID you retrieved.
There are two methods for installing the Web PCI SDK:
To install the SDK using NPM, open your terminal application and install the SDK using the following command:
To install the SDK using CDN, include the following script in your HTML file.
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
Note: We use a semantic versioning scheme for the Web PCI SDK.
To initialize the SDK:
- Create an HTML element to contain the PCI SDK iFrame. Ensure you specify your custom element ID. For example:
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. See OptionsObject Properties for more info.
Ensure you replace the following with the appropriate values:
apto-pci-sdk(Optional: Only required if using a custom HTML element ID)
Note: Ensure you set the correct
apiKeyfor the correct
environment. See Get the Mobile API Key for the SDKs for more information.
- Invoke the
AptoPCISdk.initmethod and pass in the
OptionsObject has the following properties:
|The authentication object containing the following properties:|
|The name of a predefined theme. By default, the PCI view has a transparent background. The theme values can be:|
|The HTML element for mounting the iFrame. If |
|The object defining the text information on the card. This object can have the following properties:|
The PCI data can be displayed or hidden.
To show the complete card data, use the
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
000000as the OTP code.
- If the code entered is correct, the PCI data will be displayed.
To hide the card data, use the
To check if the PCI data is visible, use the
Note: This method returns a Promise.
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:
To set the PCI theme to a
dark theme, use the
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.
To apply custom style settings to the PCI View, use 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
- Create an ITheme object. See ITheme object for more detailed info about elements that can be styled.
- Pass the
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.
|Use this to specify an existing theme to extend. Available values are |
|Use this to style the entire PCI container.|
|Use this to style the areas containing the card data. For example, the card number, CVV, expiration date, etc.|
|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.|
|Use this to style the area surrounding the cardholder's name and its associated label.|
|Use this to style the area surrounding the PAN and its associated label.|
|Use this to style the area surrounding the CVV and its associated label.|
|Use this to style the area surrounding the expiration date and its associated label.|
|Use this to style the name, PAN, CVV, and expiration date labels.|
|Use this to style the cardholder's name label.|
|Use this to style the PAN label.|
|Use this to style the CVV label.|
|Use this to style the expiration date label.|
|Use this to style the cardholder's name.|
|Use this to style the PAN text.|
|Use this to style the CVV text.|
|Use this to style the expiration date.|
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:
vwto enable proper scaling across all device sizes.
- Use a reference viewport of
340pxto calculate these units.
If you want to change the font size of elements in the Web PCI themes, we advise you account for the
vwfont 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.
We look forward to receiving your feedback, including new feature requests, bug fixes and documentation improvements.
If you would like to help: