@lightspeed/cts-client

Lightspeed Card Tokenization Service Module

About

This project is a module to handle generating credit card tokens in a way that limits exposure of the module client to credit card information. This has the affect of limiting a client's scope with regard to PCI compliance.

The module provides a facility for generating an iFrame which refers to an application hosted on the Card Tokenization Service (CTS). It also provides a facility for on-demand generation of the any card information entered into the fields provided by the CTS application.

Basic Usage

Install the project's dependencies:

yarn install

Run the unit tests. This will produce coverage files in the jest/coverage directory. This is the command that would typically be used on the CI server:

yarn test

Run the unit tests in a watch mode. This allows for quick iteration while developing tests:

yarn test:dev

Builds the assets (rolled-up) for development:

yarn build

To bump the version of the package and automatically update the CHANGELOG:

yarn bump

Prepares the package for publishing:

yarn prepublish

CTS Client API

CTSClient.renderCardFields(options)

The CTSClient.renderCardFields generates an iFrame linking to the CTS and returns a CTSClient instance. The generated instance may later be used to generate card tokens via the generateToken method.

The options parameter is an object which accepts the following attributes:

attribute	type	description
token	string	The JWT obtained by the client to authenticate with the CTS (see above). If the JWT was generated with the tst field set to true then the card token will be generated using the gateway providers test environment otherwise the gateway providers production environment will be utilized.
orderID	string	A unique ID representing the order (or sale) for the transaction. It is the responsibility of the client application to ensure that this ID is unique.
customerID	string	An ID that uniquely identifies the customer associated with a transaction. It is the responsibility of the client application to ensure that this ID is unique.
elementID	string	A DOM id of an element with the client's application where the CTS iFrame is to be attached.
gatewayConfigID	string	The ID of the gateway that will be used to generate the transaction token. The ID would come from the Payment Service.
environment	string	May be one of the following: local, staging or production. The value used will indicate under which environment the CTS iFrame will be generated. For example, if local is used the iFrame will link to the local environment.
...additionalGatewayAttributes	object	If you need provide any additional attributes such as the cardholder information simply add those as single key:value pair or provide a complex structured object (max depth limit 5). These attributes are optional and might not be supported for all gateway services. These are typically for fraud prevention. Any unsupported attribute will be ignored. Any name collision with the attributes stated before might result in unexpected behavior, you have been warned.

Since there are asynchronous operations that need to occur to generate the iFrame, the CTSClient instance will be returned once the Promise returned by a call to the CTSClient.renderCardFields method resolves. If there was an error generating then the promise will reject with an appropriate error message:

error	description
'AUTHENTICATION_ERROR'	The supplied token and/or gatewayConfigID was invalid.
'INVALID_PARAMETERS'	One or more required parameters was invalid.
'UNKNOWN'	An unexpected error has occurred.

Example:

import CTSClient from '@lightspeed/cts-client';

let ctsClient = null;

CTSClient.renderCardFields({
  token: 'some-valid-token',
  orderID: 'uinque-order-id',
  customerID: 'totally-unique-customer-id',
  elementID: 'my-container', // assumes that an HTML element with the id #my-container exists
  gatewayConfigID: 'legit-gateway-config-id', // obtained from the payment service
  environment: 'local', // use the local environment for token generation
})
  .then((client) => {
    ctsClient = client; // store the client for later use
  })
  .catch((error) => {
    // do something useful with the error
  });

generateToken(reportGroup, clientTransactionID)

The generateToken instance method is a method used to generate a token with fields rendered and maintained by the CTS. It requires two parameters:

parameter	description
reportGroup	A client-specified ID used to categorize the merchant transactions. Most likely would be the same ID as used by the client to identify the Lightspeed customer.
clientTransactionID	A client-specified ID used to identify the transaction.

Th generateToken method resolves with a Promise when the operation is complete (whether it is is successful or not). The Promise response is an object which takes the following form:

attribute	type	description
token	string	The generated card token. This token may be used to perform the transaction in lieu of card data. The client application back-end is responsible for providing proper support to allow forwarding the token to the Payment Service when performing a transaction. If token was not successfully generated then this attribute will not be provided in the response.
error	string	The general error that has occurred generating the token. Only provided if there was an error.
additionalParameters	object	The original response returned by the third-party token generation API. This may be used by the client application to show gateway-specific status messages, transaction information, etc.

Example:

ctsClient.generateToken('merchantId', 'some-unique-transaction-id').then((response) => {
  const { token, error } = response;

  if (token) {
    console.log('Congratulateions!  Your token is:', token);
  } else if (error) {
    console.log('The following error has occurred:', error);
  } else {
    console.log('Something went horribly wrong.');
  }
});