AstroPay Tokenizer SDK for JavaScript

Official AstroPay Tokenizer SDK for easy product integrations

Table of Contents

• Overview
• Proposal
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Initialization
  • Methods
    • Create secure component
    • Render secure component
    • Create copy button
    • Render copy button
    • Unmount components
  • Events
• Support
• License

Overview

The AstroPay Web Tokenizer SDK for JavaScript is a powerful tool designed to facilitate easy integration of AstroPay's secure payment solutions into your web applications. This SDK provides a streamlined way to tokenize and reveal sensitive payment information, ensuring that your transactions are both secure and efficient.

Proposal

The primary goal of this SDK is to provide developers with a simple yet robust method to integrate payment tokenization into their products. By using this SDK, developers can easily create and manage secure components for handling payment data, thereby reducing the complexity and overhead associated with PCI compliance.

Getting Started

Prerequisites

To use this SDK, you'll need the following:

• LTS Node version (v16 or higher)
• npm or yarn

Installation

The Astropay Tokinizer Web SDK can be added to your project in two ways:

• Directly in the web application in a script tag or as an import
• As part of your project build as a library imported from NPM

To benefit from the latest features and patches released by Astropay, more security and minimize the size of the script used, it is highly recommended to use an integration method that leverages the Astropay Tokenizer CDN, as detailed in the following sections.

Note that while Astropay Tokenizer hosts the CDN and ensures the script availability at runtime, any project using the Astropay Web Tokenizer SDK library from NPM would require its hosting.

Direct CDN integration

The quickest and simplest way to integrate the Astropay Tokenizer Web SDK is to use the Astropay hosted library.

The version number you subscribe to can vary, depending on your needs:

• subscribing to a major release (e.g. v1) means Tokenizer will update to the latest available patch and minor release
• subscribing to a minor level release (e.g. v1.1) means Tokenizer will update to the latest available patch release
• subscribing to a specific patch release (e.g. v1.1.2) will fix the library files to that SDK release

Importing the SDK in an html script tag

<!-- 
 Replace "<version>" with the actual Astropay Tokenizer Web SDK 
  version do you want to use, example: v1.0.0 
-->
  <script
    src="https://tokenizer-web.astropay.com/tokenizer-sdk/<version>/astropay-tokenizer.min.js"
    integrity="sha256-0IZ4FGb7Sl8EPFgYoSTsxIrPhtJL2Bfa3El0wZgP/KU="
    crossorigin="anonymous"
  ></script>

const APTokenizer = window.APTokenizer;

Integrating with an NPM package

The npm Registry is a public collection of packages of open-source code for Node.js, front-end web apps, mobile apps, robots, routers, and countless other needs of the JavaScript community. Using your favorite package manager, install @astropay/tokenizer package.

npm install @astropay/tokenizer

or

yarn add @astropay/tokenizer

The @astropay/tokenizer package by default, be connected to the Astropay CDN. In addition to the benefits of using a CDN and the library being directly in your build process, core functions will also be typed when used with Typesript.

Importing the SDK with a JavaScript import directive

The library can also be invoked directly within an object or component:

// ES6 module import
import APTokenizer from '@astropay/tokenizer';

// commonjs style require
var APTokenizer = require('@astropay/tokenizer')

Note: The library is Browser only, it does not support the Node Context.

Usage

Initialization

Initialization To load the Astopay Web Tokenizer, add an empty HTML element for the secure element interface to mount itself on:

<div id="secure-card"></div>

const APRevealer = APTokenizer.initRevealer({
  environment: "sandbox",
  version: "latest",
});

Methods

create

Create the secure frame to be used for revealing content.

const fieldFrame = Tokenizer.create({ 
  name: "<FIELD_NAME>", 
  token: "<SECRET_TOKEN>", 
  auth: "<ACCESS_TOKEN>",
  formatters: [
            Tokenizer.formatters.DASH_14,
            Tokenizer.formatters.DASH_15,
            Tokenizer.formatters.DASH_16,
          ],
});

Parameters of create

|Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------------------------| | name | string | required | The name of the field to reveal. | | token | string | required | The secret token for authentication. | | auth | string | required | The access token for authorization. | | formatters| array | optional | An array of formatters to apply to the value before rendering. |

Formatters

Has to be an array of objects with strategy and params keys. The params key is an object with the three keys search, replacer, and count. The strategy key is an string, now we support 'replace' only.

• here is an example of a formatter object:

{
  "strategy": "replace",
  "params": {
    "search": "^(\\d{4})(\\d{4})(\\d{4})(\\d{4})$",
    "replacer": "$1-$2-$3-$4",
    "count": 0
  }
}

Note: We strongly recomment use the predefined values inside the Tokenizer instance. Example of use here

Predefined formatters

| Key | Strategy | Search Pattern | Replacer | Count | |-----------------------|----------|---------------------------------------|----------------|-------| | DASH_16 | replace | ^(\d{4})(\d{4})(\d{4})(\d{4})$ | $1-$2-$3-$4 | 0 | | DASH_15 | replace | ^(\d{4})(\d{6})(\d{5})$ | $1-$2-$3 | 0 | | DASH_14 | replace | ^(\d{4})(\d{6})(\d{4})$ | $1-$2-$3 | 0 | | SPACE_16 | replace | ^(\d{4})(\d{4})(\d{4})(\d{4})$ | $1 $2 $3 $4 | 0 | | SPACE_15 | replace | ^(\d{4})(\d{6})(\d{5})$ | $1 $2 $3 | 0 | | SPACE_14 | replace | ^(\d{4})(\d{6})(\d{4})$ | $1 $2 $3 | 0 | | COPY_NUMBER | replace | ' |-' | '' (empty string) | 0 |

render

Renders the frame inside the specified container.

fieldFrame.render(container, {
  padding: '10px',
  fontSize: '14px',
  display: 'block',
  background: 'black',
  borderRadius: '4px',
});

copy

Creates a secure component for copy the value of the specified frame.

You have twice way to create a copy component

// using the Tokenizer instance
const copyFrame = Tokenizer.copy(fieldFrame, { 
  text: "Copy card number", 
}, ({ status }) => {
  console.log("copy callback:", status);
});

or

// using the secure component
const copyFrame = fieldFrame.copy({ 
  text: "Copy card number", 
});

Parameters of copy

|Option | Type | Required | Description | |-----------|--------|----------|-----------------------------------------| | targetFrame | SecureFrame | required | Only when the copy is create using the Tokenizer instance. | | options | object | optional | An object with keys text and formatters | | callback | function | optional | The callback function for the copy button |

options |Option | Type | Required | Description | |-----------|--------|----------|-----------------------------------------| | text | string | optional | The text inside de HTML button.| | formatters| array | optional | An array of formatters to apply to the value before rendering. see here|

To render copy button

Same as field, see render method

tearDown

Destroys all the frames created by the Astropay Web Tokenizer.

// using the Tokenizer instance
Tokenizer.tearDown();

// using the secure component
fieldFrame.tearDown();

Events

The .on() method of Secure Component you can listen to events and handle different states in callback functions. Multiple event handlers can be added for the same event of the field.

fieldFrame.on("request", function ({status}) {
  console.log(`the request finish with status: ${status}`);
});

The .off() method of Secure Component removes event handlers that were attached with .on() method.

fieldFrame.off("request", function ({status}) {
  console.log(`the request finish with status: ${status}`);
});

Event types

|Event|Parameters|Description| |---|--- |---| |request|{ status: "success" | "error", message?: string}| Triggers when the request of reveal was successfully completed, or when the request of reveal was completed with error and send the message of reason.| |reveal|{ status: "success" | "error", message?: string}|Triggers when the field was successfully revealed, or failed and send the message of reason.| |copy| { status: "success" | "error", message?: string}|Triggers when the revealed field was successfully copy to the clipboard, or failed the operation|

Support

We provide detailed documentation on the AstroPay Developer Guide. Please check it for more information that might be necessary for developers.

If you need more technical support, please contact support

License

Copyright © 2023 AstroPay. All rights reserved.