Get started

CdeTerminalSDK - is a tool for working with the CDE terminal. SDK provides communicating with the downloaded application in iframe tag (event subscriptions, triggering of submitting data to CDE, changing of the interface language and etc.).

SDK script endpoint

https://sdk.cde.cloud/iframe/sdk-v1.0.4.js

Embedding in an iframe

Create an empty block with a unique ID attribute inside the body of the HTML document (within the body tag). Then download the script by placing a <script> tag with the relevant SDK version link at the end of the document. After loading the script, the CdeTerminalSdk constructor will be available, which expects as required parameters a session token and a unique ID of the HTML block where the terminal should be loaded. There is also an additional optional third parameter with settings described in the table below.

        
<html>
  <body>
    <!-- Add HTML-container -->
    <div id="cde_terminal"></div>

    <!-- Add script of SDK -->
    <script type="text/javascript"
                  src="https://sdk.cde.cloud/iframe/sdk-v1.0.4.js"
                  integrity="sha384-I0qNl4ogKez0CNyBsdmucHGgwLsiou3eq/bwdBq1bJumX22uFs9tQhIASrQFImmA"
                  crossorigin="anonymous"></script>

    <!-- Run SDK constructor for initialization and loading of the card terminal session -->
    <script type="text/javascript">
      const token = '32100f701dc83477772ba589b905aaa3';
      const idHtmlElement = 'cde_terminal';

      const terminal = new CdeTerminalSdk(token, idHtmlElement);
    </script>
  </body>
</html>

Constructor parameters

Property	Type	Description
token	string	Project makes a request to get card payment session token. Get card payment session token
idHtmlElement	string	HTML-element ID, where the IFRAME will embed.
options	object	(optional) Additional settings of the card terminal interface.
options.lang	string	(optional - default 'en') initial language on an iframe. Available values: 'en'\|'ru'\|'tr'\|'es'\|'pt'.
options.theme	string	(optional - default: 'light') initial theme 'light'/'dark'.
options.tabindex	number	(optional) tab index of iframe element to control the focus of elements.
options.customization	object	(optional) User interface customization settings like colors.
options.customization.colors	object	(optional) set of CSS variables for customization of UI colors `{[name_var]: <value_var>}` See available colors here

Language setting

The initial value is set in the options.lang parameter of the CdeTerminalSdk constructor. To change the language in the terminal iframe at runtime, use the useLang(lang) method. Possible values are 'en' (English), 'es' (Spanish), 'pt' (Portuguese), 'tr' (Turkish), 'ru' (Russian).

Default: en.

        
const token = '32100f701dc83477772ba589b905aaa3';
const idHtmlElement = 'cde_terminal';

// Initial language is turkish
const options = {
  lang: 'tr'
}
const terminal = new CdeTerminalSdk(token, idHtmlElement, options);

// Change UI language to spanish
terminal.useLang('es');

UI Theme

There are two themes: light, dark. The initial value is set in the options.theme parameter of the CdeTerminalSdk constructor. To switch the theme at runtime, use switchTheme method of CdeTerminalSdk instance, as shown in the example below.

Default: light.

        
const token = '32100f701dc83477772ba589b905aaa3';
const idHtmlElement = 'cde_terminal';

// Initial UI theme is dark
const options = {
  theme: 'dark'
};
const terminal = new CdeTerminalSdk(token, idHtmlElement, options);

// change UI to another theme
terminal.switchTheme();

Custom of UI colors

Changing the UI colors is only set through the constructor. There is a strictly set of CSS variables that is passed in the options.customization.colors constructor parameter. CSS variable must be HEX-color format or one of the literals transparent, white or black. The available names of CSS variables are obtained in the code example below. If you specify variable names that are not expected, the terminal will just ignore them.

        
const token = '32100f701dc83477772ba589b905aaa3';
const idHtmlElement = 'cde_terminal';
const options = {
  customization: {
    colors: {
      // color of labels
      "cde-label-color": "#656565",
      // color of control text
      "cde-control-color": "black",
      // color of control background
      "cde-control-bg-color": "white",
      // color of control background on hover state
      "cde-control-bg-color-hover": "black",
      // color of control background on focus state
      "cde-control-bg-color-focused": "black",
      // color of disabled control background
      "cde-control-bg-color-disabled": "black",
      // color of control border
      "cde-control-border-color": "#E5E5E5",
      // border color of control fields on hover
      "cde-control-border-color-hover": "#CCCCCC",
      // border color of control fields on focus
      "cde-control-border-color-focused": "#855AFF",
      // color of placeholder text of control fields
      "cde-control-placeholder-color": "#A9A9A9",
      // font color of invalid control
      "cde-control-color-invalid": "black",
      // background color of invalid control
      "cde-control-bg-color-invalid": "white",
      // background color of invalid controls on hover
      "cde-control-bg-color-invalid-hover": "white",
      // background color of invalid controls on focus
      "cde-control-bg-color-invalid-focused": "white",
      // border color of invalid controls
      "cde-control-border-color-invalid": "#E5E5E5",
      // border color of invalid controls on hover
      "cde-control-border-color-invalid-hover": "#CCCCCC",
      // border color of invalid controls on focus
      "cde-control-border-color-invalid-focused": "#855AFF",
      // text color on page without internet connection
      "cde-connection-screen-color": "#656565",
      // background color of skeletons
      "cde-skeleton-bg-color": "#EBEBEB",
      // right color of skeleton gradient
      "cde-skeleton-gradient-color-right": "#FFFFFF99",
      // central color of skeleton gradient
      "cde-skeleton-gradient-color-center": "#FFFFFF99",
      // left color of skeleton gradient
      "cde-skeleton-gradient-color-left": "#FFFFFF99",
      // color of selected checkbox border
      "cde-checkbox-border-color-checked": "transparent",
      // color of selected checkbox background
      "cde-checkbox-bg-color-checked": "#855AFF",
      // color of foreground card background
      "cde-card-bg-color": "#F5F5F5",
      // color of foreground card border
      "cde-card-border-color": "white",
      // color of background card background
      "cde-card-back-bg-color": "#EFEFEF",
      // color of background card border
      "cde-card-back-border-color": "white",
      // color of strip of background card
      "cde-card-strip-bg-color": "#292A35",
      // color of icons
      "cde-icon-color": "#656565",
      // color of icon on hover state
      "cde-icon-color-hover": "#656565",
      // color of icons on focus state
      "cde-icon-color-focused": "#656565",
      // color of border of the card list
      "cde-card-list-border-color": "#EBEBEB",
      // color of background of the card list
      "cde-card-list-bg-color": "white",
      // color of scrollbar of the card list
      "cde-card-list-scrollbar-color": "#E4E4E4",
      // color of text of selection items
      "cde-card-list-item-color": "black",
      // color of text of selection items on hover
      "cde-card-list-item-color-hover": "black",
      // color of text of selection items on focus
      "cde-card-list-item-color-focused": "black",
      // color of border of selection items
      "cde-card-list-item-border-color": "transparent",
      // color of border of selection items on hover
      "cde-card-list-item-border-color-hover": "transparent",
      // color of border of selection items on focus
      "cde-card-list-item-border-color-focused": "transparent",
      // color of background of selection items
      "cde-card-list-item-bg-color": "transparent",
      // color of background of selection items on hover
      "cde-card-list-item-bg-color-hover": "#f5f5f5",
      // color of background of selection items on focus
      "cde-card-list-item-bg-color-focused": "#EFEFEF",
      // color of text of tooltips
      "cde-tooltip-color": "white",
      // color of background of tooltips
      "cde-tooltip-bg-color": "#000000E5",
      // color of text of the validation's tooltips color
      "cde-tooltip-color-invalid": "white",
      // color of background of the validation's tooltips
      "cde-tooltip-bg-color-invalid": "#000000E5"
    }
  }
};

const terminal = new CdeTerminalSdk(token, idHtmlElement, options);

Methods

Props and methods

Property	Type	Description
iframe	Property (HTMLIFrameElement)	Reference to iframe DOM element where the terminal was loaded.
submit()	() => void	Submit the completed form. Form of the terminal is a set of fields for entering the secured data without buttons. When the client has entered all the data and the form is valid, the terminal informs that it is ready to submit the data and waits the event from the outside window.
switchTheme()	() => void	See UI theme
useLang(string)	(string) => void	See Languages
refreshHeight()	() => void	Refresh the height of iframe by content. This is method-helper if you have any troubleshoots with height of iframe. Iframe automatically sets the height of internal content after getting of session data. To refresh the height of iframe by content again, use refreshHeight().
onInputPending(callback)	(() => void) => {unsubscribe: () => void}	An auxiliary method for subscribing to a form state change from valid to invalid. For example, if there was an attempt to submit a form but incorrect data was entered. The callback in argument is also called when the form is initially loaded.
onInputReady(callback)	(() => void) => {unsubscribe: () => void}	An auxiliary method for subscribing to the event of changing from invalid form to valid form. For example, if the client has entered correct data and the form is ready to submit.
onInputSubmitted(callback)	(() => void) => {unsubscribe: () => void}	An auxiliary method for subscribing to the successful submitting of the form to CDE. The callback in the method argument is called if the card data is submitted to CDE and the successful response is received.
onError(callback)	(e: 500 \| 501 \| 504) => void) => {unsubscribe: () => void}	An auxiliary method to subscribe to an error event. The method callback receives an error code. Error are final and payment session must be restarted from the beginning. The error code can be: 500 - internal error; 501 - session with specified token was not found; 504 - session has expired.
onTimeout(callback)	(() => void) => {unsubscribe: () => void}	An auxiliary method for subscribing to the timeout event. The callback in the method argument is called if the session lifetime is over and the session expired.
subscribe(callback, eventName)	(object) => void, string) => {unsubscribe: () => void}	General method for subscribing to the events. The first callback in arguments is called when an event with the name in the second argument is received. The argument eventName is passed without known prefix cde_terminal., so here will be the following valid values: 'language', 'stateChanged', 'submit', 'timeout', 'theme'; See Events
unsubscribe()	() => void	Unsubscribe from all events of terminal. See Events

SDK and Terminal events

SDK has auxiliary and general methods for connecting and disconnecting of events from the loaded terminal.

        
const terminal = new CdeTerminalSdk('32100f701dc83477772ba589b905aaa3', 'cde_terminal');

const subscription = terminal.onInputPending(() => {
   /* Form filled incorrectly */
});
subscription.unsubscribe();

terminal.onInputReady(() => {
   /* Card data entered correctly and is ready to be sent */
});

terminal.onInputSubmitted(() => {
   /* Form sent and received a successful response  */
});

terminal.onError((code) => {
   /*
     Form sent and received error. Error codes:
     500 - Internal error.
     501 - Session with specified token was not found.
     504 - Session has expired.
   */
});

terminal.onTimeout(() => {
   /* Session lifetime expired */
});

terminal.subscribe((data) => {
   console.log(data);
   /* All the terminal events about states */
}, 'stateChanged');

// Remove all the created subscriptions above
terminal.unsubscribe();

Terminal Events

Terminal and SDK communicate with each other via window.postMessage(). The events are the outgoing and incoming MessageEvent. The SDK has ready methods for that but the client can send and receive the events independently. Each of them has own name inside and has a prefix 'cde_terminal.'. Outgoing and incoming events send and get data in the same format.

          
// Event data structure

interface CdeMessageEvent {
  event: 'cde_terminal.language' |
         'cde_terminal.stateChanged' |
         'cde_terminal.submit' |
         'cde_terminal.timeout' |
         'cde_terminal.theme';
  data?: string |
        {
          state: 'inputPending' |
                 'inputReady' |
                 'inputSaved' |
                 'error';
          error?: number;
        };
};

Only 'cde_terminal.stateChanged' has the event data as an object with the certain state.

Available events are given in the table below:

Event Name	Description	Event Data
cde_terminal.language	Event is sent by SDK when language is set.	Code of language (en, ru, te, es, pt)
`SDK sends { "event": "cde_terminal.language", "data": "tr" }`
cde_terminal.stateChanged	Event is received by SDK when the form status inside iframe has changed.	One of the following statuses: 'inputPending' - the session is valid and not submitted, the card is not entered; 'inputReady' - the session is valid, the card is entered and ready to be sent; 'inputSaved' - the card for this session was saved successfully, you need to continue the payment flow or save the card; 'error' - fatal error status. This session cannot be used to continue the payment procedure.
`SDK receives something like { "event": "cde_terminal.stateChanged", "data": { "state": "error", "error": 501 } } or { "event": "cde_terminal.inputReady" }`
cde_terminal.submit	Event is sent by SDK when the form successfully submitted and no errors occurred.	-
`SDK sends { "event": "cde_terminal.submit" }`
cde_terminal.timeout	Event is received by SDK when the session has expired.	-
`SDK receives { "event": "cde_terminal.timeout" }`
cde_terminal.theme	Event is received and sent by SDK when the UI theme switched by SDK API.	'light' \| 'dark'
`SDK sends { "event": "cde_terminal.theme", "data": "dark" }`
cde_terminal.size	Event is received and sent by SDK for changing of the terminal height by content. If you send the event to the terminal, you receive a counter event with the content height which SDK automatically applies on iframe element.	-
`SDK sends { "event": "cde_terminal.size" } and than receives something like { "event": "cde_terminal.size", "data": "272px" }`

TS typings

Global TypeScript types of the SDK package. Typings is mainly about adding types to JavaScript, there are information of the types when use the package as external library. Create declaration file with extension .d.ts (like cde_sdk_typings.d.ts) and add it in your tsconfig.json files. The TypeScript compiler will understand that external code and you will be able to use the package.

        
// content of cde_sdk_typings.d.ts

declare type CdTerminalTheme = 'dark' | 'light';
declare type CdeMessageEventType = 'cde_terminal.language' | 'cde_terminal.stateChanged' | 'cde_terminal.submit' | 'cde_terminal.timeout' | 'cde_terminal.size' | 'cde_terminal.theme';

declare type CdeStateType = 'inputPending'|'inputReady'|'inputSaved'|'error';
declare type CdeEventType = 'stateChanged' | 'timeout' | 'size' | 'theme';

declare interface CdeMessageState {
  state: CdeStateType;
  error?: number;
}

declare interface CdeMessageEvent {
  event: CdeMessageEventType;
  data?: string | CdeMessageState;
}

declare interface CdTerminalSdkSubscription {
  unsubscribe: () => void;
}

declare interface CdeColorCustomization {
  [key: string]: string
}

declare interface CdTerminalSdkOptions {
  lang?: string;
  tabindex?: number;
  theme?: CdTerminalTheme;
  customization?: {
    colors?: CdeColorCustomization;
  }
}

declare class CdeTerminalSdk {
  constructor(token: string, id: string, options: CdTerminalSdkOptions);
  public iframe: HTMLIFrameElement;
  public onInputPending(handler: () => void): CdTerminalSdkSubscription;
  public onInputReady(handler: () => void): CdTerminalSdkSubscription;
  public onError(handler: (e: 500 | 501 | 504) => void): CdTerminalSdkSubscription;
  public onInputSubmitted(handler: () => void): CdTerminalSdkSubscription;
  public onTimeout(handler: () => void): CdTerminalSdkSubscription;
  public useLang(lang: string): void;
  public refreshHeight(): void;
  public switchTheme(): void;
  public submit(): void;
  public subscribe(handler: (e: CdeMessageEvent) => unknown, eventName: CdeEventType): CdTerminalSdkSubscription;
  public unsubscribe(): void;
}