Connect-E - Standard
This section describes how to add Connect-E to your site with custom styling.
Process Flow
- Access token is requested from the Connect-E REST API.
- User loads the page with the JavaScript package, and the access token is passed in.
- iFrame is initialised to collect payment details.
- Once the payment form is filled out and the user clicks submit. The execute function is called and a JavaScript promise is returned.
- If 3D secure is required, a modal is displayed for the user to enter their details.
- The promise resolves with the outcome of the transaction, including status code and auth code.
- Confirm the status of the transaction via the Connect-E REST API
Web Payment Example
Payment Complete
- Status Code
- Auth Code
<div id="demo-payment"></div>
<div id="errors"></div>
<button id="testPay" class="btn-primary btn pull-right"
data-loading-text="Processing...">Pay</button>
<div id="demo-result" style="display: none">
<h5>Payment Complete</h5>
<dl>
<dt>Status Code</dt>
<dd id="status-code"></dd>
<dt>Auth Code</dt>
<dd id="auth-code"></dd>
</dl>
</div>
const payConfig = {
paymentDetails: {
paymentToken: /*access token here*/
},
containerId: "demo-payment",
fontCss: ['https://fonts.googleapis.com/css?family=Do+Hyeon'],
styles: {
base: {
default: {
color: "black",
textDecoration: "none",
fontFamily: "'Do Hyeon', sans-serif",
boxSizing: "border-box",
padding: ".375rem .75rem",
boxShadow: 'none',
fontSize: '1rem',
borderRadius: '.25rem',
lineHeight: '1.5',
backgroundColor: '#fff',
},
focus: {
color: '#495057',
borderColor: '#80bdff',
},
error: {
color: "#B00",
borderColor: "#B00"
},
valid: {
color: "green",
borderColor: 'green'
},
label: {
display: 'none'
}
},
cv2: {
container: {
width: "25%",
float: "left",
boxSizing: "border-box"
},
default: {
borderRadius: "0 .25rem .25rem 0"
}
},
expiryDate: {
container: {
width: "25%",
float: "left",
borderRadius: '0rem',
},
default: {
borderRadius: "0",
borderRight: "none"
},
},
cardNumber: {
container: {
width: "50%",
float: "left",
},
default: {
borderRadius: ".25rem 0 0 .25rem",
borderRight: "none"
},
}
}
}
const connectE = new Connect.ConnectE(payConfig, displayErrors);
const btnTestPay = document.getElementById("testPay");
btnTestPay.onclick = () =>{
btnTestPay.innerText = 'loading';
btnTestPay.setAttribute("disabled", "true");
connectE.executePayment()
.then(function(data) {
document.getElementById("demo-payment").hidden = true;
btnTestPay.remove();
document.getElementById("demo-result").hidden = false;
document.getElementById("status-code").innerText = data.statusCode;
document.getElementById("auth-code").innerText = data.authCode;
}).catch(function(data) {
console.log('Payment Request failed: ' + data);
btnTestPay.innerText = 'Pay';
btnTestPay.removeAttribute("disabled");
if (typeof data === 'string') {
document.getElementById("errors").innerText = data;
}
if (data && data.message) {
document.getElementById("errors").innerText = data.message;
}
}
);
};
function displayErrors(errors) {
const errorsDiv = document.getElementById('errors');
errorsDiv.innerHTML = '';
if (errors && errors.length) {
const list = document.createElement("ul");
for (const error of errors){
const item = document.createElement("li");
item.innerText = error.message;
list.appendChild(item);
}
errorsDiv.appendChild(list);
}
}
#demo-payment iframe { width: 100%; }
#demo-result, #demo-payment, #recurring-demo-payment, #recurring-payment { padding: 5px; }
#errors li { color: #B00; }
iframe.threeDs {
width: 400px;
height: 400px;
margin: 100px 0 0 -175px;
position: fixed;
top: 0;
left: 50%;
box-shadow: 0 0 15px rgba(0, 0, 0, 0.6);
background-color: white;
}
Setup Connect-E Standard
Load
Connect-E can be loaded directly from our servers, this is the recommended way of loading our JavaScript to ensure the latest bug-fixes/patches. Any breaking changes will be released under a different url.<script src="https://web.e.test.connect.paymentsense.cloud/assets/js/client.js"></script>
Initialise
To initialise an instance of connect-E Standard callConnect.ConnectE
and pass in the configuration object with an optional reference to a callback to handle validation errors.
const connectE = new Connect.ConnectE(config, displayErrorsCallback, onSubmitTriggered, onBlur);
Parameter | Description |
---|---|
config
required rootConfig
|
Config containing details of this payment and the styling of the payment form. |
displayErrorsCallback
function
|
An optional callback to display text validation errors. The supplied function is called when there is a validation state change. This function is passed an array of validationError objects. |
onSubmitTriggered
function
|
An optional callback that is called when the submit event on the payment form is fired. This allows the payment to be submitted or extra validation done when the user presses the enter key on the payment form. |
onBlur
function(isValid: boolean)
|
An optional callback that is called when focus is lost from any field in the form. The parameter isValid will be true when all fields are completed and there are no validation errors. |
Validation Error
Property | Description |
---|---|
errorType
string
|
The type of validation error that has occured. This can be one of the following: cardNameRequired , cardNameInvalid , cardNumberRequired , cardNumberInvalid , expiryDateRequired , expiryDateInvalid , expiryDateMustBeInFuture , cv2Required , cv2Invalid |
message
string
|
Message detailing the validation error for displaying to the user. |
Execute Payment
To execute the payment callexecutePayment
on the object returned from the call to initialise Connect-E. This will consume the access token even if the payment is declined, another access token will need to be generated from the REST API and Connect-E will need to be reinitialized if another payment is needed.
The promise will be rejected if there is an error returned by the server or if the transaction is already processing. The promise will still be fulfilled if the payment is declined (just with non 0 status code).
connectE.executePayment(additionalInfo)
.then(function(data){
/*handle response here*/
}).catch(function(data){
/*handle failure here*/
}
When the promise is fulfilled the following object will be passed.
Transaction Result
Property | Description |
---|---|
statusCode
number
|
Indicated the status of the transaction. 0 for a successful transaction. |
authCode
string
|
If the transaction was successful, then the auth code is passed out here. |
message
string
|
This gives a more detailed description of the status of the transaction. |
Status Code
Status Code | Result | Description |
---|---|---|
0 | Successful | The transaction was successful |
3 | Authorizing | The card holder has not completed 3DS, this status will only be seen on the REST API. |
4 | Referred | The card issuer has parked the transaction awaiting contact with the customer before proceeding to authorise or decline the transaction. |
5 | Declined | The transaction was declined by the card issuer or acquiring bank. |
20 | Duplicate Transaction | The transaction which was processed was a duplicate. Ensure each transaction has a unique OrderId. |
30 | Failed | Error executing transaction. |
40 | Processing | The transaction is currently being processed, please check status again. This status will only be seen from the REST API if called before the JavaScript promise resolves or the Webhook is called. |
90 | Revoked | The access token was revoked while the cardholder was completing 3DS authentication. The transaction was stopped before being sent for processing. |
99 | Waiting Pre-execute | The transaction has been paused pre-execution using the waitPreExecute flag; a call to resume the transaction is expected within 15 minutes. |
400 | Invalid Request | The request has failed validation by our servers and the transaction has not been submitted to the gateway. Possible causes for this are invalid transaction type or other data in the request. |
401 | Issue with Access Token | The access token being used is not valid, the transaction has not been submitted to the gateway. This can be caused if the access token has already been used or the 30 minute expiry time has elapsed. |
404 | No Access Token Supplied | No access token has been supplied to Connect-E. Transaction has not been submitted to the gateway |
500 | Internal Server Error | There's been an error submitting the transaction, please check the REST API for the status of the transaction. |
Additional Info
The user's email address and billing address can be passed as the optional additionalInfo
object as defined below. These values will override those set when the access token was created.
Property | Description |
---|---|
userEmailAddress
string
|
This email will be checked with the card issuer to provide additional security. |
userPhoneNumber
string
|
The cardholder's phone number. |
billingAddress | This address will be checked with the card issuer to provide additional security. |
shippingDetails | Shipping details for the order. |
metaData
Map<string, string>
|
Meta data to be passed at execution time. This will be merged into MetaData passed via the REST API. This can be represented as a JSON object with only string values, other types are not supported. |
savePaymentMethod
boolean
|
Flag to indicate that the payment method should be saved so it can be used for future payments without needing to fill in the card details again (only CVV) |
ShippingDetails
Property | Description |
---|---|
name
string
|
Name order is being shipped to. |
address | Address order is being shipped to. |
Address
Property | Description |
---|---|
address1
string
|
Customer’s billing address line 1. |
address2
string
|
Customer’s billing address line 2. |
address3
string
|
Customer’s billing address line 3. |
address4
string
|
Customer’s billing address line 4. |
city
string
|
Customer’s billing address city. |
state
string
|
Customer’s billing address state or county. |
postcode
string
|
Customer’s billing address postcode or zipcode. |
countryCode
string
|
Customer’s billing address country code using ISO 3166-1 e.g. United Kingdom: 826. |
Config
This section details the fields that can/must be passed to Connect-E Standard when it is initialised
Root Config
Property | Description |
---|---|
containerId
required string
|
The id of the div element where the payment details will be displayed. |
paymentDetails
required paymentDetails
|
Details of the payment to be made. |
fontCss
array of strings
|
Array of urls pointing to css files for importing fonts. e.g. 'https://fonts.googleapis.com/css?family=Do+Hyeon' |
styles
required stylesConfig
|
Object defining custom styles for the payment form. |
text | Object defining text to override the defaults. |
onIframeLoaded
function
|
An optional function that is called once the iframe has been loaded and configured. |
onIframeLoadFailed
function
|
An optional function that is called if there is an error loading the iframe. |
errorMessages | Object defining custom validation error messages for the payment form. |
callbacks | Object defining callback functions on various events. |
billingAddressRequired
boolean
|
An optional config to collect the buyer's billing address. It defaults to false. |
Payment Details
Note that these details must be the same as those passed to the REST API when creating an access token.
Property | Description |
---|---|
paymentToken
required string
|
The access token supplied by the get access token api. |
Styles Config
Property | Description |
---|---|
base
required fieldStyle
|
Styles to be applied to all fields. |
cv2 | Styles to override the base styles for the cv2 field. |
cardNumber | Styles to override the base styles for the card number field. |
expiryDate | Styles to override the base styles for the expiry date field. |
cardName | Styles to override the base styles for the card name field. |
cardIcon | Styles to be applied to the card icon. |
form | Styles to be applied HTML form element containing all the fields. |
billingAddress | Styles to override the base styles for the billing address. |
Billing Address Fields Style Config
Property | Description |
---|---|
title | Styles to override the base styles for the title. |
addressLine1 | Styles to override the base styles for the address line 1 field. |
addressLine2 | Styles to override the base styles for the address line 2 field. |
addressLine3 | Styles to override the base styles for the address line 3 field. |
city | Styles to override the base styles for the city field. |
county | Styles to override the base styles for the county field. |
postcode | Styles to override the base styles for the postcode field. |
country | Styles to override the base styles for the country field. |
Field Style
Property | Description |
---|---|
default | Styles to be applied when the field is in its initial state. |
focus | Styles to be applied when the field has focus. |
error | Styles to be applied when the field has failed validation. |
valid | Styles to be applied when the field has passed validation. |
errorFocus | Styles to be applied when the field has focus and is in an error state. |
validFocus | Styles to be applied when the field has focus and is valid. |
container | Styles to be applied to the div wrapping the label and the input field. |
label | Styles to be applied to the label. |
validationText | Styles to be applied to the validation message. Only applicable if text.(cardName|cardNumber|expiryDate|cv2).showValidation is true . |
validationIcon | Styles to be applied to the validation message icon. Only applicable if text.(cardName|cardNumber|expiryDate|cv2).showValidation is true . E.g., to set the icon colour to purple set this property to { backgroundColor: 'purple' } |
Text Config
Property | Description |
---|---|
cardName | Config to override the default card name placeholder and label text. |
cardNumber | Config to override the default card number placeholder and label text. |
expiryDate | Config to override the default cv2 placeholder and label text. |
cv2 | Config to override the default expiry date placeholder and label text. |
billingAddress | Config to override the default text config for billing address. |
Billing Address Text Config
Property | Description |
---|---|
addressLine1 | Config to override the default address line 1 text config. |
addressLine2 | Config to override the default address line 2 text config. |
addressLine3 | Config to override the default address line 3 text config. |
city | Config to override the default city text config. |
county | Config to override the default county text config. |
postcode | Config to override the default postcode text config. |
country | Config to override the default country text config. |
Field Text
Property | Description |
---|---|
label
string
|
Text to replace the default label text. |
placeholder
string
|
Text to replace the default placeholder text. (Empty will be ignored) |
showValidation
boolean
|
Option to show the validation message. Defaults to false if not set. |
Validation Error Messages
This allows overriding of the default error messages. This will override both the messages passed to displayErrorsCallback
and the message displayed if showValidation
is set to true
.
Property | Description |
---|---|
cardNameRequired
string
|
Error returned if card name is not entered |
cardNameInvalid
string
|
Error returned if invalid card name is entered |
cardNumberRequired
string
|
Error returned if card number is not entered |
cardNumberInvalid
string
|
Error returned if invalid card number is entered |
expiryDateRequired
string
|
Error returned if card expiry date is not entered |
expiryDateInvalid
string
|
Error returned if invalid card expiry date is entered |
expiryDateMustBeInFuture
string
|
Error returned if card expiry date is not in the future |
cv2Required
string
|
Error returned if CV2 is not entered |
cv2Invalid
string
|
Error returned if invalid CV2 is entered |
billingAddressLine1Required
string
|
Error returned if billing address line 1 is not entered |
billingAddressLine1Invalid
string
|
Error returned if invalid billing address line 1 is entered |
billingAddressLine2Invalid
string
|
Error returned if invalid billing address line 2 is entered |
billingAddressLine3nvalid
string
|
Error returned if invalid billing address line 3 is entered |
billingCityRequired
string
|
Error returned if billing city is not entered |
billingCityInvalid
string
|
Error returned if invalid billing city is entered |
billingCountyRequired
string
|
Error returned if billing county is not entered |
billingCountyInvalid
string
|
Error returned if invalid county is entered |
billingPostcodeRequired
string
|
Error returned if billing postcode is not entered |
billingPostcodeInvalid
string
|
Error returned if invalid billing postcode is entered |
billingCountryRequired
string
|
Error returned if billing country is not entered |
billingCountryInvalid
string
|
Error returned if invalid billing country is entered |
Web Payment Callbacks Config
Property | Description |
---|---|
onFormComplete
function
|
An optional function that is called once the form is complete and all input values are valid. |
onFormFieldValid
function(fieldName: string)
|
An optional function that is called once a form field input is valid. |
Update Access Token
It may be useful to update the access token if the current access token has been consumed or expired. Updating the access token does not refresh the payment form so the user will not have to re-enter their card details. A new access token will need to be obtained from the REST API and passed as an object of payment details to the function.
connectE.updateAccessToken(paymentDetails);
Validation
Validation can be manually triggered by calling validate
. This returns a promise, the promise is resolved if the validation passes and rejected if the validation fails. When the promise is rejected an array of validation errors are passed to the function.
connectE.validate()
.then(() => {
/* Handle validation success */
})
.catch(errs => {
/* Handle validation errors */
});