Introduction
This document describes the integration techniques available for customers to embed the SecureCall client into their web application environments. A Web Component or a Low-level API approach can be taken.
When SecureCall is embedded in the customer's web CRM, POS, or PMS environments, the following processes can be automated:
1. Authentication
2. Securing the phone call
3. Passing sales transaction details to SecureCall
4. Customer card entry and payment gateway processing
5. Retrieval of the payment gateway transaction results or tokens from SecureCall
The Web component encapsulates our set of low-level APIs that your developer can embed the SecureCall HTML tags to replace existing or add a new payment page in your web apps.
The low-level APIs are also available for direct integration for the purposes of developing a client user interface, either through a browser or via a CRM integration.
Web Component
What is the SecureCall Web Component
The Web Component is an HTML 5-compliant custom element that allows the encapsulation of SecureCall HTML tags in web pages and web apps.
It builds on the Web Component standards, and will therefore operate across modern browsers, and can be used with any JavaScript library or framework that works with HTML.
The features within the SecureCall web component let web developers white label SecureCall, easily extending their HTML with this new element, encapsulating the styling and behaviour.
It encapsulates basic functionality, wrapping the SecureCall low-level API in a friendly way to allow simple embedding of the SecureCall Client. It handles the status updates from SecureCall as well as gathering input from the user or their CRM to allow payments to be submitted.
How Do I Use the SecureCall Web Component
The SecureCall Web component details that follow, provide the HTML elements required for web pages and web applications.
An integration test page and sequence diagram follows.
Integration Test Page
Your developers can test the functionality of the SecureCall Web Component and APIs here:
Dependency Neutral Client Application:
US PoP https://client.us.securecall.cloud/integration- test.html
UK PoP https://client.uk.securecall.cloud/integration- test.html
EU PoP https://client.eu.securecall.cloud/integration- test.html
AU PoP https://client.au.securecall.cloud/integration- test.html
NO CLIENT INTEGRATION TEST PAGE PROVIDED
Web Component – Sequence Diagram
Here is a sequence diagram of the integration between the SecureCall Web Component and a Web based application like a CRM, POS or PSM system.
NO DIAGRAM PROVIDED
Getting Started
Example of minimal web component code usage:
<html>
<head>
<script src="https://client.au.securecall.cloud/scripts/latest/web/sc-client-web-v1.esm.js">
</script>
</head>
<body >
<securecall-main></securecall-main>
<script>
document.addEventListener('DOMContentLoaded', function () {
const webComponent = document.querySelector('securecall-main'); const username = undefined;
const password = undefined; const useCookieValue = true;
webComponent.authenticate(username, password, useCookieValue);
});
</script>
</body>
</html>
This would result in a web page with the ‘Press to Secure’ button:
NO IMAGE PROVIDED
Once this button is pressed, the call will be secured, using third party call control interactions with the Service Provider supplied voice service.
Only after the call has been successfully secured, the virtual payment terminal capability of the client is presented to the user similar to the below.
NO SAMPLE IMAGE PROVIDED
Three key areas of focus for the user:
1. The type of card transaction
a. Pay
b. Tokenise and
c. Pay and Tokenise
2. Merchant entry fields - manually entered or populated by a CRM or POS application
a. Sales Amount
b. Payment reference
c. Customer Name on Card
3. Customer entry field - to be entered by the customer using the dial pad of their phone
a. Customer card number
b. Customer card expiry date
c. Customer card CVV
The display can be controlled and updated by processes external to the web component such as a CRM. This is detailed in the following sections.
Web Component Script Location
The web component can be loaded by using a <script> tag in the <head> tag of the HTML page. The src location takes the format of:
https://client.<region>.securecall.cloud/scripts/<build>/web/sc-client-web-v1.esm.js
where <region> is one of “au”,"uk","us","eu" and <build> is either a build number or “latest”.
Pick the region closest to where the SecureCall users will be located.
Use the “latest” build if updates aren't an issue. Once a system is going to be rolled into production it would be prudent to lock that down to a build number, so any later releases of the web component don't impact the solution. This way the update to a later build can be carefully managed and tested before releasing a new version of a solution incorporating the web component.
Web Component Properties
Properties control the details of the data and display of the web component as well as the authentication of the APIs. Most of the properties can be used as HTML attributes of the web component when creating the element. They can also be supplied afterwards using a script tag using the property name.
Property name Attribute name Type Default
apiLocation api-location string https://client.au.securecallapi.clo
paymentDetails
object {
transaction_type: {
value: 'pay', readOnly: false, hidden: false
},
amount: {
value: '',
readOnly: false, hidden: false
},
payment_reference: { value: '', readOnly: false, hidden: false
},
token_reference: {
value: '', readOnly: false, hidden: false
},
name_on_card: {
value: '', readOnly: false, hidden: false
},
metadata: {}
}
fieldConfiguration object {
transaction_type: {
readOnly: false, hidden: false
},
amount: {
readOnly: false, hidden: false
},
payment_reference: {
readOnly: false, hidden: false
},
token_reference: {
readOnly: false, hidden: false
},
name_on_card: {
readOnly: false, hidden: false
}
}
theme theme string light / dark / Default = dark
multiPay multi-pay boolean True
displayTransactionErrors display-
transaction- errors boolean false
displayTransactionResult
display- transaction- result
boolean
true
awaitActiveCall await- active-call boolean false
paymentDetails
This property can be used to pass in information to pre-fill the appropriate fields such as amount and payment reference. It is passed via a JavaScript object using a script tag.
The key is the field name and the value is an object consisting of the following fields:
Key Type Description
value string or number See the following table for information on the possible values for each field
readOnly true/false If the field is shown then is the field read only?
hidden true/false Is the field hidden from the user?
The exception is the metadata field. This is just an object with arbitrary key/values that is used to pass information to the payment gateway processor.
Key Type Description
transaction_type “pay”, “pay_and_tokenise”, “tokenise”
amount number Amount in dollars and cents
payment_reference string An arbitrary identifier that
will be submitted with the payment. Used to correlate payments later. For example, an invoice number or account number.
name_on_card string Name on the credit card.
token_reference string An arbitrary identifier that will be submitted with the tokenization request. Used to find the token later to make an offline payment. For example, a customer identifier.
metadata object Any other information that might need to be passed to the payment gateway for this request. The payment gateway needs to support the keys and allow the data to be attached to the request.
See below for core fields that can be supported. Speak to us for any other fields that need to be passed.
Metadata standard fields
Key Value Description
gateway_timeout
integer greater than 10 How long to wait for the payment gateway to respond. Default is 45 seconds.
That may need to be a long time due to the acquirer's processing time.
gateway_name string consisting of a-z, 0-9 or underscore Used with Multi-MID when there is more than one gateway defined for an
organization.
Defaults to “default”
Example of utilising paymentDetails property to define Field Values and enable Read-Only input for an individual transaction:
<script>
const myComponent = document.querySelector('securecall-main'); const paymentDetails = {};
const keys = ['transaction_type', 'amount', 'payment_reference', ‘name_on_card']; keys.forEach(key => {
paymentDetails[key] = {
value: 'field value', // from your system readOnly: true,
hidden: false
};
});
myComponent.paymentDetails = paymentDetails;
</script>
fieldConfiguration
This property changes the default display or behaviour of the fields used for merchant entry. Typically, this is set once when the web component is created with the paymentDetails property used to pass in the information. If a required field can’t accept entry and isn’t passed by paymentDetails then submission of payments can fail.
The format is a map of fields with object values.
Field Default Value
transaction_type {readOnly: false, hidden: false}
amount
{readOnly: false, hidden: false}
payment_reference {readOnly: false, hidden: false}
token_reference
{readOnly: false, hidden: false}
name_on_card
{readOnly: false, hidden: false}
Example of utilising fieldConfiguration property to define Field Values and enable Read-Only input for all subsequent transactions:
<script>
const webComponent = document.querySelector('securecall-main'); const fieldConfig = {
"token_reference": { readOnly: false, hidden: false }, "payment_reference": { readOnly: true, hidden: false },
// ... additional field entries 'transaction_type', 'amount', 'name_on_card'];
};
webComponent.fieldConfiguration = fieldConfig;
</script>
multiPay
This parameter controls the ability to add another payment using the same card details after a successful payment on the same call. By default, multiPay is set to true which displays “Another Payment” button on the Payment Success screen. This button and functionality can be removed by setting multiPay to false.
Example Usage:
<script>
const myComponent = document.querySelector('securecall-main'); myComponent.multiPay = false;
</script>
displayTransactionResult
When set to true (the default) the web component shows the result on a payment success or failure. On success also shows the transaction id and receipt number.
displayTransactionErrors
When set to true shows the transaction failure message from the gateway as well as an error code. This is only displayed if displayTransactionResult is set to true.
awaitActiveCall
When set to true shows “Awaiting Active Call” rather than the secure button. This can be used by systems that know the telephony state to stop the user pressing secure call when there is no call.
Set to false to show the secure button or send the secure method.
Methods
secure()
This method can be called to trigger the securing of the call from outside the web component.
<script>
const myComponent = document.querySelector('securecall-main'); myComponent.triggerSecureEventMethod().then(() => {
// Your actions here
});
</script>
authenticate (username, password, useCookie=false)
Parameters
• username, password
These parameters define the authentication method to use when using the APIs underpinning the web component (see Low Level APIs below).
If username is blank then the other parameters are ignored, useCookie is assumed to be true and the authentication flow will be treated as a Webex authentication with a redirect to the Webex login screen (see description in useCookie below).
Password can be a password gathered from a form, an API Key or a Webex Organisation ID.
<script>
document.addEventListener('DOMContentLoaded', function () {
const webComponent = document.querySelector('securecall-main'); const username = undefined;
const password = undefined; const useCookieValue = true;
webComponent.authenticate(username, password, useCookieValue);
});
</script>
useCookie
This parameter controls the authentication method for the APIs. If set to true, the web component will use the /login API to return a cookie to be used in future API calls.
This is predominately used when a Webex authentication model is to be used without passing in any of the login hints. The merchant would be presented with the Webex login page as a popup and once logged in, would be able to use the web component without further logins until the cookie expires.
The other reason to use this parameter is in the case of using username and password where they are collected by a web page that the web component is embedded into. Use of this property will allow the collection of the username/password infrequently and to use the cookie returned. This will reduce the number of times the merchant would be prompted if they close the browser or refresh the page.
If useCookie is set to false (the default) then username and password need to be provided or the web component won’t be able to authenticate correctly.
submitAnotherPayment(data: IPaymentValues)
Parameters
data - object with the format:
amount: string;
transaction_type: 'pay' | 'tokenise' | 'pay_and_tokenise'; name_on_card?: string;
payment_reference?: string; token_reference?: string; metadata?: Record<string, unknown>;
Used to submit another payment after a payment has already been made by the merchant pressing the submit button. The payment doesn't have to be successful. Typically this is done in an event handler for transactionSuccess event.
It doesn't show the payment details or ask the merchant to press the submit button again (see triggerAnotherPayment for that functionality).
triggerAnotherPayment(resetPaymentDetails = true, resetCardFields = ['cvv'])
Parameters
• resetPaymentDetails(boolean) - when set to true clears all the payment detail values allowing the merchant to enter them again.
• resetCardFields(array) - contains an array of strings of which customer card fields are to be reset. The array can have values from the following: ‘pan’, ‘expiry’, ‘cvv’ or ‘all’
This method by default resets the CVV and payment detail values and sets the component up for another payment to be made.
The resetPaymentDetails and resetCardFields parameter can be used when the payment has failed due to one of the card fields being rejected by the acquirer. Usign the parameters, the appropriate card field can be cleared and the payment retried without losing any of the other data entered.
Events
Events are generated at many points throughout the life of the web component. Standard JavaScript event listeners can be used to capture them and provide customised functionality.
Event Type Description
authenticationFailure string
authenticationSuccess string
callEnded string Sent when the call has ended, and the web component goes back to its idle screen
callSecured string Sent when the call has been successfully secured and the customer can start entering their card details
transactionFailure javascript object (see below) Sent when the transaction has failed to be processed.
transactionSubmitted Sent when the transaction has been submitted to the payment gateway.
transactionSuccess javascript object (see below) Sent when the transaction is successful
Transaction Success and Failure Objects
The responses received after a success or failure of a transaction are to a certain extent configurable. There are some fields which will always be there, other fields can be added per customer and gateway.
Transaction success will always have “transaction_number” and “receipt_number for payments or pay/tokenise requests. It will always have “token” for pay/tokenise or tokenise requests.
Transaction failures will always have “error_code” for all transaction types.
Both type of responses can have additional data taken from the gateway response to be passed back through the events. Typically, these are the raw response and are in an attribute on the object called “raw”. All the data can be returned or just a subset if required. The naming can also be changed.
The following is a successful example for a pay/tokenise request to the gateway in JSON format:
{
"transaction_number": "xxxxxxxxxx", "receipt_number": "xxxxxxxxxxxx", "token": "xxxxxxxxxxxx",
"raw": {
"Action": "payment", "Amount": 19900,
"AmountOriginal": 19900,
"AmountSurcharge": 0, "AuthoriseId": "xxxxxxx", "BankResponseCode": "00", "CVNResult": {
"CVNResultCode": "M"
},
"CardDetails": {
"CardHolderName": "John Smith", "Category": "CLASSIC", "ExpiryDate": "0526", "IssuerCountryCode": "BGR", "Localisation": "international",
"MaskedCardNumber": "498765...769", "SubType": "debit"
},
"CardType": "VC",
"Crn1": "test payment ref", "Crn2": "test token ref", "Currency": "AUD", "DVToken": "xxxxxxxxxxxxx", "FraudScreeningResponse": {
"ResponseCode": "", "ResponseMessage": "", "TxnRejected": false
},
"IsCVNPresent": true, "IsTestTxn": true, "IsThreeDS": false,
"MerchantNumber": "xxxxxxxxxxxxx", "MerchantReference": "test payment ref",
"ProcessedDateTime": "2023-10-13T16:24:32.3200000",
"RRN": "xxxxxxxxxx", "ReceiptNumber": "xxxxxxxxxx", "ResponseCode": "0", "ResponseText": "Approved", "SettlementDate": "20231013", "Source": "api",
"StoreCard": false, "SubType": "single", "TxnNumber": "xxxxxxxxxx", "Type": "ivr"
}
}
authenticationSuccess Event
This event responds with the result of the authenticate() Method on success
Example usage:
<script>
myComponent.addEventListener('authenticationSuccess', (event) => {
// Handle your authenticationSuccess event here
console.debug('>>>> Action Required: authenticationSuccess Received by host application:', JSON.stringify(event));
});
</script>
authenticationFailure Event
This event responds with the result of the authenticate() Method on failure
Example usage:
<script>
myComponent.addEventListener('authenticationFailure', (event) => {
// Handle your authenticationFailure event here
console.log('>>>> Action Alert: authenticationFailure Received by host application:',
JSON.stringify(event));
</script>
callSecured Event
This event responds with the result of the actual securing of the call with an event detail in the form of a JSON String which would need to be parsed.
Example usage:
<script>
const myComponent = document.querySelector('securecall-main'); myComponent.addEventListener('callSecured', (event) => {
// Handle your callSecured event response here
console.log('>>>> Action Alert: callSecured:', JSON.stringify(event.detail));
});
</script>
paymentSuccess Event
This event responds with the result of a successful payment
Example usage:
<script>
myComponent.addEventListener('paymentSuccess', (event) => {
// Handle paymentSuccess event here
console.log('>>>> Action Alert: paymentSuccess Event Received by host application:', JSON.stringify(event.detail));
});
</script>
paymentFailure Event
This event responds with the result of a failed payment
Example usage:
<script>
myComponent.addEventListener('paymentFailure', (event) => {
// Handle paymentFailure event here
console.log('>>>> Action Alert: paymentFailure Event Received by host application:', JSON.stringify(event.detail));
});
</script>
Styling
Styling is performed by using CSS variables. There are 2 themes, light and dark, each with their own variables.
The defaults are shown below:
securecall-main {
/* Dark Theme /*/
--theme-background-color-dark: none;
--theme-primary-color-dark: white;
--theme-secondary-color-dark: #ccc;
--theme-button-color-dark: rgba(4, 156, 196, 0.5);
--theme-button-color-hover-dark: #049cc4;
--theme-button-color-disabled-dark: rgba(4, 156, 196, 0.3);
--theme-text-disabled-color-dark: #049cc4;
--theme-border-color-dark: #ccc;
--theme-border-color-disabled-dark: rgba(4, 156, 196, 0.3);
--theme-input-active-background-dark: white;
--theme-input-inactive-background-dark: #ccc;
--theme-spinner-border-dark: rgba(255, 255, 255, 0.3);
--theme-spinner-color-dark: #049cc4;
/* Light Theme /*/
--theme-background-color-light: none;
--theme-primary-color-light: #333;
--theme-secondary-color-light: #ccc;
--theme-button-color-light: rgba(220, 220, 220, 0.5);
--theme-button-color-hover-light: #049cc4;
--theme-button-color-disabled-light: rgba(4, 156, 196, 0.3);
--theme-text-disabled-color-light: #049cc499;
--theme-border-color-light: #ccc;
--theme-border-color-disabled-light: rgba(4, 156, 196, 0.3);
--theme-input-active-background-light: white;
--theme-input-inactive-background-light: #ccc;
--theme-spinner-border-light: rgba(0, 0, 0, 0.3);
--theme-spinner-color-light: #049cc4;
}
Low Level API
Authentication
There are 2 ways to authenticate to the APIs, using a cookie or using Basic authorization header.
A cookie is obtained by calling the /login API and then passed to each API request. This is used when prompting of some or all of the authentication data is required. Using a cookie means the prompts don’t need to be repeated for the life of the cookie (1 day) if the user refreshes the screen or exits the browser.
Alternatively, the /login API isn’t used, and the Basic Authorization header is passed to each API call. This method is typically used when the authorisation data is known, for example being called from a CRM where the user’s email address and SecureCall apikey can be passed.
Please note that in both cases, a 302 response can be returned in the situation of using the Webex Organization ID as the password. This would redirect to the Webex login page for the user to login using their Webex credentials. We recommend using a popup window to handle the redirect. Once entered, the API request would need to be re-submitted for it to be accepted.
Basic Authorization Header
There are multiple ways to authenticate with SecureCall. Which way to use depends on how SecureCall has been setup for your environment.
• don’t pass a Basic Authorization header in which case a 302 will be returned redirecting to the Webex login page. Please note this is only useful when calling /login first and then passing the cookie for each API call. Otherwise, it will keep sending 302 responses
• pass in 'username:webex org id' base64 encoded in the 'Authorization' header using the 'Basic' prefix. This will be looked up in the SecureCall user database and if there is already an Access Token stored, it will be used. If the token has expired but there is a Refresh Token, it will be used to refresh the Access Token. If neither token exists, a 302 will be returned, redirecting to the webex login page
• pass in 'username:apikey' base64 encoded in the 'Authorization' header using the 'Basic' prefix. The apikey will be provided when signing your organisation up to SecureCall. This can be used with Broadworks telephony platforms when the integration is done with a CRM or with a customer hosted webpage
• pass in 'username:password' base64 encoded in the 'Authorization' header using the 'Basic' prefix. The password will be specific to each user and must have been set before use
POST /login
Logs in and returns the authentication cookie
See the Authentication section of the API specification for details of what can be passed in as authentication data.
Responses
Code Description
200 Successfully authenticated. The session ID is returned in a cookie named securecall.session. You need to include this cookie in subsequent requests.
302 Some authentication types such as Webex can redirect to an OAuth2 login page to enter their credentials. Typically, this is handled by a popup window. It is up to your implementation to handle this redirection.
401 Unauthorized
GET /events
Get the CHD data as events
The endpoint is accessed as Server Sent Events. These are typically consumed using a HTML5 EventSource (https://developer.mozilla.org/en- US/docs/Web/API/EventSource)
Responses
Code Description
200 A stream of events will start. There can be different event types, the main one described below is "status".
Some example javascript for the status event is something like the below:
evtSource.addEventListener("status", (e) => { this.processStatusEvent(e)
})
Content
application/json
{
"timestamp": "2023-08-24T05:40:04.807Z",
"session": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "securing",
"call_data": { "state": "securing",
"error": "string"
},
"secure_data": { "state": "pan", "pan": {
"value": "string", "valid": true,
"brands": [ "visa"
]
},
"expiry": { "value": "string", "valid": true
},
"cvv": {
"value": "string", "valid": true
}
},
"payment_data": { "state": "submitting", "error": 0,
"payment_action": "pay", "amount": 0, "payment_reference": "string", "token_reference": "string",
"name_on_card": "string",
"transaction_id": "string"
}
}
302 Some authentication types such as Webex can redirect to an OAuth2 login page to enter their credentials. Typically, this is handled by a popup window. It is up to your implementation to handle this redirection and re-submit the request once the authentication has been completed.
401 Unauthorized
POST /secure
Secure the currently active call
Starts the process of securing the call to take a payment. Status events will be returned via the /event endpoint.
Responses
Code Description
202 The call will attempt to be secured
302 Some authentication types such as Webex can redirect to an OAuth2 login page to enter their credentials. Typically, this is handled by a popup window. It is up to your implementation to handle this redirection and re-submit the request once the authentication has been completed.
401 Unauthorized
POST /reset
Resets fields in the payment
Resets fields in the secure data. One, some or all the fields can be reset. Status events will be returned via the /event endpoint.
Responses
Code Description
202 The field(s) will attempt to be reset
302 Some authentication types such as Webex can redirect to an OAuth2 login page to enter their credentials. Typically, this is handled by a popup window. It is up to your implementation to handle this redirection and re-submit the request once the authentication has been completed.
401 Unauthorized
POST /submit
Submit a payment
Submits a payment. Status events will be returned via the /event endpoint
Depending on the payment_action different fields will be expected.
• If the payment_action is pay or pay_and_tokenise, then amount, payment_reference and name_on_card are required
• if the payment_action is tokenised or pay_and_tokenise then token_reference will need to be provided.
The payment_reference is typically what the merchant would use to reconcile a payment. For example, an invoice number or customer reference number.
The token_reference is typically used to look up the token at a later time. For example, a customer id or account number.
The metadata field is for transferring information to the payment gateway. This might be extra information to attach to the payment or tokenisation request that is required by the particular gateway used or some extra customer information the merchant wants to collect about the payment.
Responses
Code Description
202 The payment will be submitted
302 Some authentication types such as Webex can redirect to an OAuth2 login page to enter their credentials. Typically, this is handled by a popup window. It is up to your implementation to handle this redirection and re-submit the request once the authentication has been completed.
401 Unauthorized