AstroPay Tokenizer SDK for JavaScript

Official AstroPay Tokenizer SDK for easy product integrations

Overview
Proposal
Getting Started
- Prerequisites
- Installation
Usage
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

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
DASH_16	replace	^(\d{4})(\d{4})(\d{4})(\d{4})$	`$1-$2-$3-$4`
DASH_15	replace	^(\d{4})(\d{6})(\d{5})$	`$1-$2-$3`
DASH_14	replace	^(\d{4})(\d{6})(\d{4})$	`$1-$2-$3`
SPACE_16	replace	^(\d{4})(\d{4})(\d{4})(\d{4})$	`$1 $2 $3 $4`
SPACE_15	replace	^(\d{4})(\d{6})(\d{5})$	`$1 $2 $3`
SPACE_14	replace	^(\d{4})(\d{6})(\d{4})$	`$1 $2 $3`
COPY_NUMBER	replace	' \|-'	`''` (empty string)

`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);
});

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