@astropay/tokenizer-sdk

# AstroPay Tokenizer SDK for JavaScript ![AstroPay](https://getapp.astropay.com/img/astropay/2023/logo-black.svg) ## **Official AstroPay Tokenizer SDK for easy product integrations** [npm]: https://img.shields.io/npm/v/@astropay/tokenizer [npm-url]: https://www.npmjs.com/package/@astropay/tokenizer [size]: https://packagephobia.now.sh/badge?p=@rastropay/tokenizer [size-url]: https://packagephobia.now.sh/result?p=@astropay/tokenizer [prettier]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg [prettier-url]: https://github.com/prettier/prettier [typescript]: https://img.shields.io/npm/types/typescript.svg [typescript-url]: https://www.typescriptlang.org [downloads]: https://img.shields.io/npm/dm/@astropay/tokenizer.svg [downloads-url]: https://www.npmjs.com/package/@astropay/tokenizer [![npm][npm]][npm-url] [![downloads][downloads]][downloads-url] [![size][size]][size-url] [![typescript][typescript]][typescript-url] [![prettier][prettier]][prettier-url] ## Table of Contents - [Overview](#overview) - [Proposal](#proposal) - [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Usage](#usage) - [Initialization](#initialization) - [Methods](#methods) - [Create secure component](#create) - [Render secure component](#render) - [Create copy button](#copy) - [Render copy button](#to-render-copy-button) - [Unmount components](#teardown) - [Events](#events) - [Support](#support) - [License](#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](https://github.com/nodejs/Release) 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](https://www.npmjs.com/package/@astropay/tokenizer) To benefit from the latest features and patches released by [Astropay](https://astropay.com), 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 ```html  <script src="https://tokenizer-web.astropay.com/tokenizer-sdk/<version>/astropay-tokenizer.min.js" integrity="sha256-0IZ4FGb7Sl8EPFgYoSTsxIrPhtJL2Bfa3El0wZgP/KU=" crossorigin="anonymous" ></script> ``` ```javascript 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. ```bash npm install @astropay/tokenizer ``` or ```bash 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](https://www.typescriptlang.org/). ### Importing the SDK with a JavaScript `import` directive The library can also be invoked directly within an object or component: ```javascript // 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: ```html <div id="secure-card"></div> ``` ```javascript const APRevealer = APTokenizer.initRevealer({ environment: "sandbox", version: "latest", }); ``` ### Methods ### `create` Create the secure frame to be used for revealing content. ```javascript 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: ```json { "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](#create) #### 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. ```javascript 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 ```javascript // using the Tokenizer instance const copyFrame = Tokenizer.copy(fieldFrame, { text: "Copy card number", }, ({ status }) => { console.log("copy callback:", status); }); ``` or ```javascript // 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](#formatters)| ### To render copy button Same as field, see [render method](#render) ### `tearDown` Destroys all the frames created by the Astropay Web Tokenizer. ```javascript // using the Tokenizer instance Tokenizer.tearDown(); ``` ```javascript // 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. ```javascript 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. ```javascript 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](https://developers.astropay.com/docs/partners/tokenizer-partners-api). Please check it for more information that might be necessary for developers. If you need more technical support, please [contact support](https://astropay.com/contact/?lang=en) ## License Copyright © 2023 AstroPay. All rights reserved.