Display Cards via SDK

This guide explains how to integrate your frontend with Payrails Display SDK to show tokenized cardholder data without receiving any sensitive data on your servers. You’ll be able to display all the fields stored under a card record, such as card number and expiration date, in a customized UI without compromising on security.

The display-sdk is a library for creating and managing display elements for payment forms. It provides a simple API to initialize the SDK, create elements, and customize their styles and translations.

Installation

Install the SDK via npm:

npm install @payrails/display-sdk

Usage

Initialization

To use the SDK, initialize it with a response object and optional configuration options.

import { DisplaySDK, DisplaySDKOptions } from '@payrails/display-sdk';

const initResponse = 'response from /token/client/init';

const options: DisplaySDKOptions = {
  styles: {
    base: {
      color: 'black',
      fontSize: '16px',
    },
    cardNumber: {
      base: {
        color: 'blue',
      },
    },
  },
  translations: {
    base: {
      loading: 'Loading...',
    },
    cardNumber: {
      loading: 'Loading card number...',
    },
  },
};

const sdk = DisplaySDK.init(initResponse, options);

Creating Elements

You can create display elements for different types of input fields, such as card number, expiry date, etc.

import { DisplayElementType } from '@payrails/display-sdk';

const cardNumberElement = sdk.createElement(DisplayElementType.CardNumber);
const expiryMonthElement = sdk.createElement(DisplayElementType.ExpiryMonth);

Destroying Elements

To clean up and unmount all created elements, use the destroy method.

sdk.destroy();

API Reference

DisplaySDK

static init(initResponse: DisplaySDKInitResponse, options?: DisplaySDKOptions): DisplaySDK

Initializes the SDK with the given response and options.

• initResponse: An object containing initialization data.
• options: Optional configuration for styles and translations.

createElement(type: DisplayElementType): DisplayElement

Creates a new display element of the specified type.

• type: The type of the element to create. Possible values are:
  • DisplayElementType.CardNumber
  • DisplayElementType.ExpiryYear
  • DisplayElementType.ExpiryMonth
  • DisplayElementType.SecurityCode
  • DisplayElementType.CardHolderName

destroy(): void

Destroys all created elements and cleans up resources.

DisplaySDKOptions

Configuration options for the SDK.

• styles: An object defining style configurations for elements.
• translations: An object defining translations for elements.

DisplayElementType

An enumeration of possible element types:

• CardNumber
• ExpiryYear
• ExpiryMonth
• SecurityCode
• CardHolderName

Examples

Custom Styles

const options: DisplaySDKOptions = {
  styles: {
    base: {
      fontSize: '14px',
    },
    securityCode: {
      error: {
        color: 'red',
      },
    },
  },
};

Custom Translations

const options: DisplaySDKOptions = {
  translations: {
    base: {
      loading: 'Please wait...',
      error: 'An error occurred',
    },
    expiryYear: {
      loading: 'Loading expiry year...',
    },
    cardNumber: {
      error: 'Error occurred while loading card number',
    },
  },
};

License

This project is licensed under the MIT License.