Connect-E - Standard Repeat Payment

This section describes how to collect a customers CV2 code in order to create a repeat transaction.

Process Flow

  1. Execute payment using either Connect-E Standard or Checkout.
  2. Collect the cross reference code from the get payment endpoint on the Connect-E REST API.
  3. Create a access token with a transaction type of SALE or PREAUTH and pass in the cross reference code.
  4. User loads page with JavaScript package, and the token is passed in.
  5. iFrame is initialised to collect CV2.
  6. Once the payment form is filled out and the user clicks submit. The execute function is called and a JavaScript promise is returned.
  7. If 3D secure is required, a modal is displayed for the user to enter their details.
  8. The promise resolves with the outcome of the transaction, including status code and auth code.

Recurring Payment Example

<div id="recurring-demo-payment"></div>
<div id="recurring-errors"></div>
<button id="recurring-test-pay" class="btn-primary btn pull-right" data-loading-text="Processing...">Pay</button>
<div id="recurring-demo-result" style="display: none">
    <h5>Payment Complete</h5>
    <dl>
        <dt>Status Code</dt>
        <dd id="recurring-status-code"></dd>
        <dt>Auth Code</dt>
        <dd id="recurring-auth-code"></dd>
    </dl>
</div>


var config = {
    onIframeLoaded: function() { console.log("iframe loaded") },
    paymentDetails: {
        amount: "100",
        currencyCode: "826",
        paymentToken: "/*access token here*/"
    },
    "containerId": "recurring-demo-payment",
    fontCss: ['https://fonts.googleapis.com/css?family=Do+Hyeon'],
    styles: {
        cv2: {
            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',
                backgroundColor: '#fff',
                borderColor: '#80bdff',
                outline: '0',
                boxShadow: '0 0 0 0.2rem rgba(0,123,255,.25)'
            },
            error: {
                color: "#B00",
                borderColor: "#B00"
            },
            valid: {
                color: "green"
            },
            label: {
                display: 'none'
            },
            container: {
                width: "50%",
                float: "left",
                paddingLeft: "5px",
                boxSizing: "border-box"
            },
        },

    },
    text: {
        cv2: {
            label: "CVV",
            placeholder: "CVV"
        }
    }
};

var recurringPayment = new Connect.ConnectERecurringPayment(config, displayErrors);


$("#recurring-test-pay").on('click',
    function() {
        var btn = $(this);
        btn.button('loading');
        recurringPayment.executePayment()
            .then(function(data) {
                $("#recurring-demo-payment").hide();
                $("#recurring-test-pay").hide();
                $("#recurring-demo-result").show();
                $("#recurring-status-code").text(data.statusCode);
                $("#recurring-auth-code").text(data.authCode);
            })
            .catch(function(data) {
                console.log('Payment Request failed: ' + data);
                if (!Array.isArray(data)) {
                    var message = data.message ? data.message : JSON.stringify(data);
                    $("#recurring-errors").text("Payment failed: " + message);    
                }
            })
            .finally(function() {
                btn.button('reset');
            });
    });


function displayErrors(errors) {
    var errorsDiv = document.getElementById('recurring-errors');
    errorsDiv.innerHTML = '';
    if (errors && errors.length) {
        var list = document.createElement("ul");
        errors.forEach(function(error) {
            var item = document.createElement("li");
            item.innerText = error.message;
            list.appendChild(item);
        });
        errorsDiv.appendChild(list);
    }
}

#demo-payment iframe { width: 100%; }

#demo-result, #demo-payment { padding: 5px; }

#errors li { color: #B00; }

iframe.threeDs {
    width: 370px;
    height: 366px;
    margin: 100px 0 0 -175px;
    position: fixed;
    top: 0;
    left: 50%;
    box-shadow: 0 0 15px rgba(0, 0, 0, 0.6);
}

Setup Connect-E Standard - Repeat Payment

Load

The javascript is loaded in the same way as a one off payment, directly from our servers.
<script src="https://web.e.test.connect.paymentsense.cloud/assets/js/client.js"></script>

Initialise

To initialise an instance of connect-E Standard Repeat Payment call Connect.ConnectERecurringPayment and pass in the configuration object with an optional reference to a callback to handle validation errors.
var recurring = new Connect.ConnectERecurringPayment(config, displayErrorsCallback, onSubmitTriggered);
Parameter Description
config
required rootConfig
Config containing details of this payment and the styling of the repeat payment form.
displayErrorsCallback 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 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.

Validation Error

Property Description
errorType
string
The type of validation error that has occured. This can be either of the following: cv2Required, cv2Invalid
message
string
Message detailing the validation error for displaying to the user.

Execute Payment

To execute the repeat payment call executePayment on the object returned from the call to initialisation. This will consume the access token even if the payment is declined, another 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).
recurring.executePayment()
    .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
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.
400 Invalid Request The request as 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 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.

This section details the fields that can/must be passed to Connect-E Standard when a recurring payment is initialised

Root Config

Property Description
containerId
required string
The id of the div element where the form to capture the CV2 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 Object defining custom styles for the payment form.
text Object defining text to override the defaults.
function
onIframeLoaded
An optional function that is called once the iframe has been loaded and configured.
function
onIframeLoadFailed
An optional function that is called if there is an error loading the iframe.

Payment Details

Note that these details must be the same as those passed to the REST API when creating an access token.

Property Description
amount
required string
The amount in the minor unit e.g. "100" for 1.00 GBP.
currencyCode
required string
The three digit ISO-4217 currency code for the currency. eg 826 for the United Kingdom
paymentToken
required string
The access token supplied by the get access token api.

Styles Config

Property Description
cv2 Styles for the cv2 field.

Field Style

Property Description
default Styles to be applied when the field is in it's 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.
container Styles to be applied to the div wrapping the label and the input field.
label Styles to be applied to the label.

Text Config

Property Description
cv2 Config to override the default expiry date placeholder and label text.

Field Text

Property Description
label
required string
Text to replace the default label text.
placeholder
required string
Text to replace the default placeholder text.