@lightspeed/cts-client
v1.0.0
Published
CTS Client API
Downloads
253
Keywords
Readme
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.');
}
});