@securecall/client-component

v1.2.0

Published

22 days 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 the following

provides visual feedback to a user for secure data entry
allows data entry of other fields required to submit transactions
interfaces with the SecureCall Client API
emits Events on session, authentication and configuration updates
has helper functions for each of the APIs
allows customisation via functions called on the component

Install

NOTE: It is important to specify a version when using this component in a 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 making it live for your agents.

If you are developing a project using NPM then you can install the component using npm

npm install --save @securecall/client-component@<version>

If you are wrapping the component in a web page, then you can include it using something like the following:

<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/client-component/dist/client-component/client-component.esm.js"></script>

This would use the latest version from the jsdelivr CDN. As stated above, pinning a version would be a better strategy for production like this:

<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/[email protected]/dist/client-component/client-component.esm.js"></script>

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

Usage

Minimal Example

<!DOCTYPE html>
<html lang="en-AU">
  <head>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/client-component/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.securcallapi.cloud"></securecall-client>
    </div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const securecall = document.getElementById('securecall');
        securecall.addEventListener('authenticationSuccess', () => {
          console.log('Authentication success');
        });
        securecall.addEventListener('authenticationFailure', () => {
          console.log('Authentication failed');
        });
      })
    </script>
  </body>
</html>

The minimal example will make connection to the SecureCall Client API and will show authenticationFailure in the console log.

Client Component

Properties

| Property | Attribute | Description | Type | Default | |----------------------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|-----------------| | apiLocation | api-location | The URL of the SecureCall Client API for your region. This would be 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 | boolean | false | | hideSecureButton | hide-secure-button | Set to true to hide the secure button. Typically used if the secure method will be called instead | boolean | false | | displayTransactionResult | display-transaction-result | Set to false to not show the transaction result view at all | boolean | true | | theme | theme | Sets the theming of the component | "dark" \| "light" | 'light' | | switchHint | switch-hint | Suggests to SecureCall what type of telephony to use. Only relevant at the moment for WebexCC where it should be set to 'webexcc' when using the securecall-webexcc-telephony widget in the desktop layout | string | |

Events

| Event | Description | Type | |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------| | authenticationFailure | Authentication with SecureCall has failed. The reason and numbers of times it has failed are passed in the event. This will be the first event thrown and usually where the authenticate method is called from. | CustomEvent<object> | | authenticationSuccess | Authentication with SecureCall has succeeded. The component is now live. | CustomEvent<string> | | configurationChanged | A configuration event was sent by SecureCall. | CustomEvent<string> | | callEnded | A secured call has ended. | CustomEvent<string> | | callSecured | The current call has been secured (true) or unsecured (false) | CustomEvent<boolean> | | loggedOut | The user has logged out of SecureCall | CustomEvent<boolean> | | transactionSubmitted | The transaction has been submitted to the backend. | CustomEvent<ITransactionValues> | | transactionSubmitting | The backend has sent the transaction to the payment gateway. | CustomEvent<ITransactionData> | | transactionSuccess | The transaction has succeeded. The result is in the event detail. | CustomEvent<ITransactionData> | | transactionFailure | The transaction has failed. The reason is in the event detail. | CustomEvent<ITransactionData> |

Methods

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

Authenticate the user to SecureCall. This is required before any of the functionality will work.

Parameters

| Name | Type | Description | |-------------|-----------|---------------------------------------------------------------------------------------------------------------------| | username | string | The email address of the user | | password | string | The API key, telephony organisation ID, or password of the user. Which one to use depends on your SecureCall setup. | | useCookie | boolean | Do you want to use a cookie to keep the authentication active? Typically this is false |

Returns

Type: Promise<void>

`logout() => Promise<void>`

Logs the user out of SecureCall

Returns

Type: Promise<void>

`secure() => Promise<void>`

Secures the current active call. This can be used when integrating with a CRM rather than using the button in the component.

Returns

Type: Promise<void>

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

This allows another transaction to be submitted without user input.

For example, you may need to submit two transactions, one after another. The user can use the submit button to trigger the first transaction, and the second could use this method in the transactionSuccess event handler.

Parameters

| Name | Type | Description | |--------|----------------------|-------------------------| | data | ITransactionValues | The transaction details |

Returns

Type: Promise<boolean>

`triggerAnotherTransaction(resetTransactionDetails?: boolean, resetCardFields?: string[]) => Promise<void>`

Resets the component back to the transaction screen for the user to input a new transaction. Which fields are reset can be controlled by the parameters.

Parameters

| Name | Type | Description | Defaults | |---------------------------|------------|------------------------------------------------------------------------------------------------------------------|----------| | resetTransactionDetails | boolean | Resets all the transaction fields when true | false | | resetCardFields | string[] | A list of secure fields to reset. Set to an empty array to not reset any of them or ['all'] to reset all of them | ['cvv'] |

Returns

Type: Promise<void>

`updateRequestFields(updates: (arg0: any) => void) => Promise<void>`

Changes field configuration for the instance. These changes will be persistent for the duration this instance of the component is loaded.

Typically, this will be used to set the fields that won't change between calls or transactions.

For example, to add a new field called currency which is a drop-down box and is available for every transaction. This also sets the amount and paymentReference fields to readOnly so they can be set by an external process for each transaction using updateTransactionRequestFields()

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;
  })

Parameters

| Name | Type | Description | | --------- | --------------------- | ----------- | | updates | (arg0: any) => void | |

Returns

Type: Promise<void>

`updateSessionRequestFields(updates: (arg0: any) => void) => Promise<void>`

Does the same as updateRequestFields but the changes wont last once the call has ended

Parameters

| Name | Type | Description | | --------- | --------------------- | ----------- | | updates | (arg0: any) => void | |

Returns

Type: Promise<void>

`updateTransactionRequestFields(updates: (arg0: any) => void) => Promise<void>`

Does the same as updateRequestFields but affects the current transaction

Following the example in updateRequestFields, this sets the currency, amount and paymentReference

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

Parameters

| Name | Type | Description | | --------- | --------------------- | ----------- | | updates | (arg0: any) => void | |

Returns

Type: Promise<void>

`updateResponseFields(updates: (arg0: any) => void) => Promise<void>`

Set the configuration for the fields shown once a transaction is successful or unsuccessful.

If you dont want to show the "Another Transaction" button, you can use this method to do that

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

Parameters

| Name | Type | Description | |-----------|-----------------------|-------------| | updates | (arg0: any) => void | |

Returns

Type: Promise<void>

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

Called within one of the updateRequestField functions to add a new field to be displayed and possibly entered. The configuration can be passed in the config object or manipulated later

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'}
  })
})

Parameters

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

Returns

Type: void

Field Names

These are the standard field name, new ones can be added using the addNewField function or configured in the SecureCall admin portal.

| Name | Description | |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | amount | The amount of the transaction | | currency | The currency of the transaction | | paymentReference | A reference for the transaction. This will be used to match the transaction with the payment gateway transaction. Typically this will be a unique reference for the transaction. | | tokenReference | A reference for a tokenise transaction. Usually this will be a customer number used to store the token against and to lookup the token at a later time. | | nameOnCard | The name on the card | | gatewayName | The name of the payment gateway used for the transaction | | metadata | A place to store any additional data that will be submitted to the payment gateway. |

Field Attributes

| Name | Type | Description | |-------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | order | number | The order of the field in the display | | value | string | The value that will be used to submit to SecureCall | | readOnly | boolean | Is the field readOnly or can the user enter data into it? | | hidden | boolean | Is the field visible? Hidden fields dont count toward form validity so they should have the correct value applied or the transaction may fail | | valid | boolean | This attribute is set by the field entry so there is little point setting it | | possibleValues | Record<string, string> | An object with potential values to choose from. The key is the value that will be used and the value is the label that will be displayed to the user. The select and radio fields expect an object | | mapping | string | Helps construct the submission request to SecureCall. Typically this will be "metadata.xxx" for a new field. |
| label | string | The label for the field displayed to the User |
| component | string | The type of field to display. The choices are radio, string, currency and select. |
| min | number | If the field supports it, this is the minimum value or length to be considered valid |
| max | number | If the field supports it, this is the maximum value or length to be considered valid |
| active | boolean | This is only used by the secure fields to show which one is active at this point in time. Dont bother setting this. |
| placeholder | string | Displays a placeholder in the field if the field supports it | | hideRelatedFields | Record<string, object> | This can be used to change which fields are displayed when another value is chosen. Used by the radio field type. | | secure | boolean | Flags this field is a secure field where the data entry will come from the customer | | optional | boolean | Flags this field is optional and will validate if empty. Only applies to string fields currently |

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

Called within one of the updateRequestField functions to add a new field to be displayed and possibly entered. The configuration can be passed in the config object or manipulated later

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

SecureCall Client Web Component

Install

Usage

Minimal Example

Client Component

Properties

Events

Methods

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

Parameters

Returns

logout() => Promise<void>

Returns

secure() => Promise<void>

Returns

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

Parameters

Returns

triggerAnotherTransaction(resetTransactionDetails?: boolean, resetCardFields?: string[]) => Promise<void>

Parameters

Returns

updateRequestFields(updates: (arg0: any) => void) => Promise<void>

Parameters

Returns

updateSessionRequestFields(updates: (arg0: any) => void) => Promise<void>

Parameters

Returns

updateTransactionRequestFields(updates: (arg0: any) => void) => Promise<void>

Parameters

Returns

updateResponseFields(updates: (arg0: any) => void) => Promise<void>

Parameters

Returns

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

Parameters

Returns

Field Names

Field Attributes

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

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

`logout() => Promise<void>`

`secure() => Promise<void>`

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

`triggerAnotherTransaction(resetTransactionDetails?: boolean, resetCardFields?: string[]) => Promise<void>`

`updateRequestFields(updates: (arg0: any) => void) => Promise<void>`

`updateSessionRequestFields(updates: (arg0: any) => void) => Promise<void>`

`updateTransactionRequestFields(updates: (arg0: any) => void) => Promise<void>`

`updateResponseFields(updates: (arg0: any) => void) => Promise<void>`

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

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