@securecall/client-component

v1.4.0

Published

a day ago

SecureCall Core Web Component

0High
0Medium
0Low

securecall-dev

securecall pci

SecureCall Client Web Component

This component provides the client user interface for taking secure payments with SecureCall. It:

Provides visual feedback to the agent during secure data entry
Allows data entry of fields required to submit transactions
Interfaces with the SecureCall Client API
Emits events on session, authentication, configuration, and telephony updates
Exposes methods for each API operation
Supports customisation via configuration functions and CSS variables

Install

Important: Always pin a version in production environments. We make every effort to ensure backwards compatibility, but versions may include or remove features. Ensure your production environments are stable by specifying a version and testing any new release thoroughly before deploying to agents.

CDN (jsDelivr)

<!-- Pinned version (recommended for production) -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/[email protected]/dist/client-component/client-component.esm.js"></script>

<!-- Latest (not recommended for production) -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/client-component/dist/client-component/client-component.esm.js"></script>

You can also download the package and host it locally for the best speed and reliability.

npm

npm install --save @securecall/[email protected]

Usage

Minimal Example

<!DOCTYPE html>
<html lang="en-AU">
  <head>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/[email protected]/dist/client-component/client-component.esm.js"></script>
  </head>
  <body>
    <div id="web-component">
      <securecall-client id="securecall" theme="dark" api-location="https://client.au.securecallapi.cloud"></securecall-client>
    </div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const securecall = document.getElementById('securecall');

        // authenticationFailure fires immediately on load (count=1, message='initialising').
        // This is the signal to call authenticate().
        securecall.addEventListener('authenticationFailure', (event) => {
          console.log('Authentication failure — call authenticate()', event.detail);
        });
        securecall.addEventListener('authenticationSuccess', () => {
          console.log('Authentication success');
        });
      });
    </script>
  </body>
</html>

Client Component

Properties

| Property | Attribute | Description | Type | Default | |----------------------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|-----------------| | apiLocation | api-location | The URL of the SecureCall Client API for your region. One of https://client.au.securecallapi.cloud, https://client.us.securecallapi.cloud or https://client.uk.securecallapi.cloud | string | window.origin | | awaitActiveCall | await-active-call | Set to true to disable the Secure button. Used by telephony integrations that control when securing occurs. | boolean | false | | hideSecureButton | hide-secure-button | Set to true to hide the Secure button entirely. Typically used when secure() will be called programmatically instead. | boolean | false | | displayTransactionResult | display-transaction-result | Set to false to suppress the transaction result view entirely. | boolean | true | | theme | theme | Sets the visual theme of the component. | "dark" \| "light" | "light" | | switchHint | switch-hint | Hints to SecureCall which telephony platform is in use. Set to "webexcc" when using the securecall-webexcc-telephony widget in the Webex CC desktop layout. | string | | | disableLoginPopup | disable-login-popup | Set to true to stop the login popup opening automatically when a login is required. authenticationFailure is emitted with loginPopupRequired instead, and openLoginPopup() should then be called from a user gesture. | boolean | false | | customLogger | — | Overrides the default console logger. Must implement debug, info, warn, and error methods. Set as a property (not an attribute). | object | console | | clientName | client-name | The name of the client calling the component to show in the log. | string | undefined |

Events

Session and Authentication

| Event | Description | Type | |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| | authenticationFailure | Authentication with SecureCall has failed. Always fires once on load with count=1, message='initialising' — this is the signal to call authenticate(). Subsequent events indicate real failures. If a login popup is needed but was not opened automatically (disableLoginPopup is set, or the browser blocked it), the detail has loginPopupRequired set and openLoginPopup() should be called from a user gesture. | CustomEvent<IAuthenticationFailure> | | authenticationSuccess | Authentication has succeeded. The component is now live and the Secure button is shown. | CustomEvent<void> | | loggedOut | The user has been logged out of SecureCall. | CustomEvent<boolean> | | configurationChanged | A configuration update was received from SecureCall. The event detail contains the current field configuration. | CustomEvent<IConfigurationUpdate> | | callSecured | The current call has been secured (true) or unsecured (false). | CustomEvent<boolean> | | callEnded | A secured call has ended. The detail contains an error message if the call ended in error, or "call ended successfully". | CustomEvent<string> |

Transaction

| Event | Description | Type | |-------------------------|-----------------------------------------------------------------------------------------------------------------|-----------------------------------| | transactionSubmitted | The transaction has been submitted to the SecureCall backend. | CustomEvent<ITransactionValues> | | transactionSubmitting | The backend has forwarded the transaction to the payment gateway. Use this to prevent duplicate submissions. | CustomEvent<ITransactionData> | | transactionSuccess | The transaction was accepted. The result (transaction ID, receipt, etc.) is in the event detail. | CustomEvent<ITransactionData> | | transactionFailure | The transaction was declined or failed. The reason and error code are in the event detail. | CustomEvent<ITransactionData> |

Telephony

These events are emitted when SecureCall sends a telephony command. Use them to bridge SecureCall with your softphone or telephony SDK. After handling each event, respond with updateTelephony().

| Event | Description | Type | |---------------------|--------------------------------------------------------------------------|-----------------------------------| | telephonyHold | SecureCall has requested the call be placed on hold. | CustomEvent<ITelephonyEventData> | | telephonyRecover | SecureCall has requested the call be taken off hold. | CustomEvent<ITelephonyEventData> | | telephonyLegA | Leg A of the call (agent audio) has been established. Includes dnis. | CustomEvent<ITelephonyEventData> | | telephonyLegB | Leg B of the call (customer IVR) has been established. Includes dnis. | CustomEvent<ITelephonyEventData> | | telephonyValidate | SecureCall is requesting confirmation that the call is still active. | CustomEvent<ITelephonyEventData> |

Methods

`authenticate(username?, password?, useCookie?) => Promise<void>`

Authenticates the agent with SecureCall. Must be called before any other functionality is available. Typically called in response to the authenticationFailure event.

| Parameter | Type | Description | |-------------|-----------|---------------------------------------------------------------------------------------------------------------------| | username | string | The email address of the user. | | password | string | The API key, telephony organisation ID, or password. Which one to use depends on your SecureCall setup. | | useCookie | boolean | Whether to use a cookie to maintain the authentication session. Typically false. |

Returns: Promise<void>

`logout() => Promise<void>`

Logs the agent out of SecureCall. Listen for loggedOut to update your UI.

Returns: Promise<void>

`openLoginPopup() => Promise<void>`

Opens the login popup after an authenticationFailure event with loginPopupRequired set. Must be called directly from a user gesture (a click handler with no awaits before the call) so the browser's popup blocker allows the window to open. Rejects if there is no pending login or the browser blocked the popup.

Returns: Promise<void>

`secure() => Promise<void>`

Secures the current active call. Use this when integrating with a CRM or telephony platform rather than relying on the Secure button in the component. Can only be called when the component is in Idle state.

Returns: Promise<void>

`release() => Promise<void>`

Releases the current secured call back to normal telephony.

Returns: Promise<void>

`updateTelephony(data: ITelephonyUpdate) => Promise<void>`

Sends a telephony status update back to SecureCall. Call this after handling each telephony* event to confirm success or report failure.

| Parameter | Type | Description | |-----------------|------------------|-----------------------------------------------------------------------------------------| | data.session | string | The session ID from the triggering telephony event. | | data.state | string | The state being reported: 'held', 'leg_a', 'leg_b', 'recover', or 'validate'. | | data.success | boolean | Whether the telephony action was completed successfully. | | data.message | string | Optional message, typically used to describe a failure reason. |

Returns: Promise<void>

`triggerAnotherTransaction(resetTransactionDetails?, resetCardFields?) => Promise<void>`

Resets the component back to the transaction input screen for the agent to submit another payment. Can only be called when the component is in Success or Failure state.

| Parameter | Type | Description | Default | |---------------------------|------------|-----------------------------------------------------------------------------------------------------------------------|------------| | resetTransactionDetails | boolean | When true, clears all non-secure transaction fields (amount, reference, etc.). | false | | resetCardFields | string[] | Secure fields to reset. Pass ['cvv'] to clear only CVV, ['all'] to clear all card fields, or [] for none. | ['cvv'] |

Returns: Promise<void>

`submitAnotherTransaction(data: ITransactionValues) => Promise<boolean>`

Submits another transaction programmatically without requiring agent input. Useful for chained transactions (e.g. payment + surcharge). Can only be called when the component is in Success or Failure state.

Returns true if the transaction was submitted, false if the component is in an incompatible state.

| Parameter | Type | Description | |-----------|----------------------|-------------------------| | data | ITransactionValues | The transaction details. |

Returns: Promise<boolean>

`updateRequestFields(updates: (fields) => void) => Promise<void>`

Configures fields at the instance level. Changes persist for the entire lifetime of the component — across all calls and transactions.

Use this for fields that are the same for every call, such as a locked gateway or a persistent currency dropdown.

await myComponent.updateRequestFields(f => {
  f.addNewField('currency', {
    order: 15,
    mapping: 'metadata.currency',
    label: 'Currency',
    component: 'select',
    readOnly: false,
    hidden: false,
    possibleValues: { gbp: 'GBP', usd: 'USD', eur: 'EUR' }
  });
  f.amount.readOnly = true;
  f.paymentReference.readOnly = true;
});

Returns: Promise<void>

`updateSessionRequestFields(updates: (fields) => void) => Promise<void>`

Configures fields at the session level. Changes persist for the duration of the current call, then reset automatically when the call ends.

Use this for fields that are set from call data delivered by your CRM or telephony platform.

Returns: Promise<void>

`updateTransactionRequestFields(updates: (fields) => void) => Promise<void>`

Configures fields at the transaction level. Changes apply to the current transaction only and reset after each transaction.

Use this to pre-populate per-transaction values (amount, reference) from your CRM.

await myComponent.updateTransactionRequestFields(f => {
  f.currency.value = 'eur';
  f.amount.value = 13.45;
  f.paymentReference.value = 'ref-' + Date.now();
});

Returns: Promise<void>

`updateResponseFields(updates: (fields) => void) => Promise<void>`

Configures the fields shown on the success or failure screen after a transaction.

await myComponent.updateResponseFields(f => {
  f.anotherTransaction.showOnSuccess = false;
  f.anotherTransaction.showOnFailure = false;
});

Returns: Promise<void>

`addNewField(name: string, config?: object) => void`

Called inside one of the updateRequestFields callbacks to add a new field to the transaction form.

await myComponent.updateRequestFields(f => {
  f.addNewField('currency', {
    order: 15,
    mapping: 'metadata.currency',
    label: 'Currency',
    component: 'select',
    readOnly: false,
    hidden: false,
    possibleValues: { gbp: 'GBP', usd: 'USD', eur: 'EUR' }
  });
});

| Parameter | Type | Description | |-----------|----------|----------------------------------------------------------------------------------------------| | name | string | The name of the new field. | | config | object | Initial configuration using the attributes in the Field Attributes section below. |

Returns: void

`version() => Promise<string>`

Returns the version string of the loaded component.

Returns: Promise<string>

Field Names

These are the built-in field names. New fields can be added with addNewField() or configured in the SecureCall admin portal.

| Name | Description | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | amount | The transaction amount. | | paymentReference | A reference for the transaction. Used to match against the payment gateway record. Should be unique per transaction. | | tokenReference | A reference for tokenise transactions. Typically a customer number used to store and retrieve the token. | | nameOnCard | The cardholder name. | | gatewayName | The payment gateway to use. Hidden by default; shown when multiple gateways are configured in the SecureCall admin portal. | | metadata | A container for additional data submitted to the payment gateway. | | pan | Card number — a secure field populated by the customer, not the agent. | | expiry | Card expiry date — a secure field populated by the customer. | | cvv | Card CVV — a secure field populated by the customer. |

Field Attributes

These attributes apply when configuring fields via updateRequestFields, updateSessionRequestFields, updateTransactionRequestFields, or addNewField.

| Attribute | Type | Description | |---------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | order | number | Display order. Lower numbers appear first. | | value | string | The field value submitted to SecureCall. | | readOnly | boolean | When true, the field is displayed but the agent cannot edit it. | | hidden | boolean | When true, the field is not shown. Hidden fields are excluded from form validation — ensure they have a value set or the transaction may fail. | | valid | boolean | Set internally by the field component. No need to set this manually. | | possibleValues | Record<string, string> | Options for select and radio fields. Keys are submitted values; values are the labels shown to the agent. | | mapping | string | Controls how the value is placed in the submission request. Use "metadata.xxx" for custom fields, or a top-level key like "amount" for standard fields. | | label | string | The label shown above the field. | | component | string | The field type: "string", "currency", "select", or "radio". | | min | number | Minimum value (currency fields) or minimum length (string fields) for validation. | | max | number | Maximum value (currency fields) or maximum length (string fields) for validation. | | placeholder | string | Placeholder text shown when the field is empty. | | hideRelatedFields | Record<string, object> | Used by radio fields to show or hide other fields depending on the selected value. Keys are option values; object values are field visibility maps. | | secure | boolean | Marks the field as a secure field (PAN, expiry, CVV). Data entry comes from the customer via the secure IVR, not the agent. | | optional | boolean | When true, the field passes validation even when empty. Currently applies to string fields only. | | active | boolean | Set internally by secure fields to indicate which field the customer is currently entering. No need to set this manually. |

CSS Variables

The component uses Shadow DOM, so host-page CSS does not apply directly. Use CSS custom properties to customise the appearance.

Variables are set on the <securecall-client> element:

securecall-client {
  --theme-button-color-light: rgba(0, 120, 200, 0.7);
  --theme-button-color-hover-light: rgba(0, 120, 200, 1);
  --spinner-circle-size: 28px;
}

Theme colour variables

Each variable has a -light and -dark variant. The active theme (light or dark) is selected via the theme prop.

| Variable | Description | Default (light) | Default (dark) | |-------------------------------------------|-------------------------------------------------------|------------------------------------|------------------------------------| | --theme-background-color-light/dark | Background colour of the component wrapper. | none | none | | --theme-primary-color-light/dark | Primary text and icon colour. | #333 | white | | --theme-secondary-color-light/dark | Secondary / muted colour used for borders. | #ccc | #ccc | | --theme-button-color-light/dark | Default button background. | rgba(4, 156, 196, 0.6) | rgba(4, 156, 196, 0.6) | | --theme-button-color-hover-light/dark | Button background on hover. | rgba(4, 156, 196, 1) | rgba(4, 156, 196, 1) | | --theme-button-color-disabled-light/dark| Button background when disabled. | rgba(4, 156, 196, 0.3) | rgba(4, 156, 196, 0.3) | | --theme-text-disabled-color-light/dark | Text colour on disabled buttons. | rgba(4, 156, 196, 0.6) | rgba(4, 156, 196, 1) | | --theme-border-color-light/dark | Default border colour. | #ccc | #ccc | | --theme-border-color-disabled-light/dark| Border colour for disabled elements. | rgba(4, 156, 196, 0.3) | rgba(4, 156, 196, 0.3) | | --theme-input-active-background-light/dark | Background of an active (focused) input. | white | white | | --theme-input-inactive-background-light/dark | Background of an inactive input. | #ccc | #ccc | | --theme-spinner-border-light/dark | The track colour of the loading spinner. | rgba(0, 0, 0, 0.3) | rgba(255, 255, 255, 0.3) | | --theme-spinner-color-light/dark | The active arc colour of the loading spinner. | rgba(4, 156, 196, 1) | rgba(4, 156, 196, 1) |

Spinner sizing variables

| Variable | Description | Default | |---------------------------|-----------------------------------------------------------|----------| | --spinner-container-size | Height of the spinner container div. | 50px | | --spinner-circle-size | Diameter of the spinner circle. | 20px |

Icon variables

These control the SVG icons used for field validation states. The defaults are inline SVGs that can be replaced with any valid url() value.

| Variable | Description | |-----------------|------------------------------------------| | --icon-valid | Icon shown when a field is valid. | | --icon-invalid| Icon shown when a field is invalid. | | --icon-reset | Icon shown on the field reset button. |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

SecureCall Client Web Component

Install

Usage

Minimal Example

Client Component

Properties

Events

Session and Authentication

Transaction

Telephony

Methods

authenticate(username?, password?, useCookie?) => Promise<void>

logout() => Promise<void>

openLoginPopup() => Promise<void>

secure() => Promise<void>

release() => Promise<void>

updateTelephony(data: ITelephonyUpdate) => Promise<void>

triggerAnotherTransaction(resetTransactionDetails?, resetCardFields?) => Promise<void>

submitAnotherTransaction(data: ITransactionValues) => Promise<boolean>

updateRequestFields(updates: (fields) => void) => Promise<void>

updateSessionRequestFields(updates: (fields) => void) => Promise<void>

updateTransactionRequestFields(updates: (fields) => void) => Promise<void>

updateResponseFields(updates: (fields) => void) => Promise<void>

addNewField(name: string, config?: object) => void

version() => Promise<string>

Field Names

Field Attributes

CSS Variables

Theme colour variables

Spinner sizing variables

Icon variables

`authenticate(username?, password?, useCookie?) => Promise<void>`

`logout() => Promise<void>`

`openLoginPopup() => Promise<void>`

`secure() => Promise<void>`

`release() => Promise<void>`

`updateTelephony(data: ITelephonyUpdate) => Promise<void>`

`triggerAnotherTransaction(resetTransactionDetails?, resetCardFields?) => Promise<void>`

`submitAnotherTransaction(data: ITransactionValues) => Promise<boolean>`

`updateRequestFields(updates: (fields) => void) => Promise<void>`

`updateSessionRequestFields(updates: (fields) => void) => Promise<void>`

`updateTransactionRequestFields(updates: (fields) => void) => Promise<void>`

`updateResponseFields(updates: (fields) => void) => Promise<void>`

`addNewField(name: string, config?: object) => void`

`version() => Promise<string>`