Overview

Simply Connect 2.0 provides ways to control the payment process using event callbacks to ’hook‘ into the Nuvei Simply Connect 2.0 payment. At each stage of the payment process, you can set an event hook to interrupt the process, allowing you to view and update certain processing parameters, change the processing flow, or continue with the flow. If a payment event is triggered, the callback function performs the specified actions. Hooks can be set at various stages in the payment process.

Examples of Hooks

• At the Simply Connect 2.0 pre-payment stage, if a customer presses ‘Pay’ the prePayment event callback function can be used. See prePayment.
• If a customer selects a payment method at the payment method selection stage, the onSelectPaymentMethod event callback function can be used. See onSelectPaymentMethod.
• If a customer performs any change on the form at any stage, the onPaymentFormChange event callback function can be used. See onPaymentFormChange.

Example of prePayment Event Callback

You can use Nuvei’s prePayment event callback to perform your own custom risk-checking function, before proceeding to payment, as described in the following flow:

1. The customer selects a payment method, such as a credit card, on the Simply Connect 2.0 form and then presses ‘PAY’.
2. Before proceeding to accept the payment, Nuvei calls the specified function using the prePayment event callback.
   The function, for example, receives all the payment and transaction details as the input, which you then use to call the risk service.
3. Based on the risk assessment, decide to continue with payment or to stop the flow and display the relevant rejection message.
4. To be notified if an event is triggered, a merchant can set Simply Connect event callback input fields.

Event Callback Input Fields

This section provides information about event callback input fields.

onReady

The onReady event callback is called when the only input is the loaded Boolean. This event indicates to the merchant that the Simply Connect form is fully loaded and presented to the end user. This event is mandatory for inclusion in the Simply Connect 2.0 initialization.

Example of onReady Request

simplyConnect({
    …
    onReady: function(readyData) {
        console.log("Ready", readyData);
    },
    …
});

prePayment

The prePayment event callback is called when the customer selects the ‘Pay’ button, but before proceeding to payment.

Example prePayment Request

simplyConnect({
    …
    eventCallbacks: {
        prePayment: function(paymentDetails) {
            return new Promise(async (resolve, reject) => {
                //var getTempTokenResponse = await checkout.getTempToken();
                //console.log("getTempToken response: ", getTempTokenResponse);

                console.log("prePayment", paymentDetails);
                resolve(); // or reject payment
                /reject("REJECTED!!"");
            });
        },
    }…
});

onPaymentFormChange

If focus moves to or moves away from any field or object on the Simply Connect 2.0 form, the onPaymentFormChange event callback is called. This is useful for tracking customer behavior on the Simply Connect 2.0 form (such as selecting a field and changing a field value), for performing user activity analytics, and for error validation.

Example of onPaymentFormChange Request

const onPaymentFormChange =
    simplyConnect({
        ...,
        onPaymentFormChange: function(pm, label, action, oldValue, newValue, validation, pasted) {
            console.log('onPaymentFormChange =>', pm, label, action, oldValue, newValue, validation, pasted);
        },
        …
    });

If the event callback is triggered, the following information is passed via the event callback:

• pm – payment method
• label – label of the field
• action – focus, blur
• oldValue – value before the event
• newValue – value after the event
• validation – validation error (i18n label); only on a validation error
• pasted – indicates a new value is pasted

onSelectPaymentMethod

The onSelectPaymentMethod event callback is called when a customer selects a payment option from the gallery, either an existing user payment token (previously saved payment option) or a new user payment token.

Example onSelectPaymentMethod Request

simplyConnect({
    …
    onSelectPaymentMethod: function(paymentDetails) {
        console.log("onSelectPaymentMethod", paymentDetails);
    },
    …
});

For an existing user payment token, the merchant receives all the information about the user payment token.

{
    "paymentOptions": [{
                "name": "ach",
                "isDirect": true,
                "supportsFieldsRecovery": true,
                "fields": [{
                        "name": "accountNumber",
                        "dataType": "STRING",
                        "isMandatory": true,
                        "minimumLength": 1,
                        "maximumLength": 30
                    },
                    {
                        "name": "routingNumber",
                        "dataType": "STRING",
                        "isMandatory": true,
                        "minimumLength": 1,
                        "maximumLength": 30
                    }
                ],
                "restrictions": [{
                    "countryCode": "US",
                    "currency": "USD"
                }],
                "logoUrl": "https://srv-bsf-devppptrunk.gw-4u.com/ppp/resources//img/svg/bank_transfer_new.svg"
            },

In the case of a new payment option, only the method name is received.

{
    "paymentTokens": [{
                "paymentTokenId": "0d43a3bc317143e1bd4811bc9cc042fd",
                "cccId": 2,
                "paymentOption": {
                    "card": {
                        "cardHolderName": "CL-BRW1",
                        "maskedCardNumber": "5***1111",
                        "bin": "555544",
                        "expirationMonth": "12",
                        "expirationYear": "25",
                        "cardType": "Credit",
                        "cardBrand": "MASTERCARD"
                    }
                }
            },

onSuggestedAmount

The onSuggestedAmount event callback is called when a customer selects a suggested amount button on the payment page.

Example onSuggestedAmount Request

simplyConnect({
    …
    onSuggestedAmount: function(result) {
        console.log('onSuggestedAmount', result);
    },
    …
});

When the onSuggestedAmount event callback is triggered, the merchant receives the following information:

• action: simplyConnect
• pm: paymentMethod name
• selected_amount: value of the selected suggested amount button

Example with action: “simplyConnect”

{
    "action": "checkout",
    "pm": "cc_card",
    "selected_amount": "120"
}

userData

The userDataevent callback is called before the payment is performed. The purpose is to set the user information (buyerDetails, billingAddress, shippingAddress), so that the user information is updated on the payment record and in processing. There is no input for this event.

Example userData Request

simplyConnect({
    …
    userData: function(userDataObj) {

        console.log("userData", userDataObj);
        return {
            billingAddress: {
                email: "[email protected]",
                country: "US",
            },
            shippingAddress: {
                city: "Boston",
            },
            buyerDetails: {
                firstName: "John",
                lastName: "Smith"
            }
        }
    },
    …
});

The returned value should be the buyerDetails, that should be formatted as follows:

"return" {
    "billingAddress": {
        "email": "[email protected]",
        "country": "US"
    },
    "shippingAddress": {
        "city": "Boston"
    },
    "buyerDetails": {
        "firstName": "John",
        "lastName": "Smith"
    }
}

onResult

The onResult event callback is called to provide the full response information each time a payment request is returned – declines, errors, and approvals.

Example of onResult Request

simplyConnect({
            …
            onResult: function(result) { //windows.removeOverlay(); console.log("Result", result); }, …});

The transaction response details and the transaction details are passed as input.

Example of Transaction Response Details

{
  "result": "APPROVED",
  "errCode": 0,
  "errorDescription": "",
  "userPaymentOptionId": "94313858",
  "cavv": "",
  "eci": "",
  "dsTransID": "",
  "ccCardNumber": "4****1111",
  "bin": "411111",
  "last4Digits": "1111",
  "ccExpMonth": "03",
  "ccExpYear": "33",
  "transactionId": "711000000029189719",
  "mcc": "",
  "cancelled": false,
  "transactionStatus": "APPROVED",
  "transactionType": "Sale"
}

There is a unique onResult response to handle when the customer session expires.

The Simply Connect customer session is usually set for 15 minutes, but can be changed. For support, Contact Nuvei Technical Support.

The recommended way to handle the expiration is to re-authenticate the customer if needed and then call POST /orders again to receive a new sessionId, which must be done on the server side.

Example with session expiration handling

simplyConnect({
    …
    onResult: function(result) {
        console.log("Result", result);
        if (result.session_expired == true) {
            console.log("session expired->", result);
            // handle session expiration, initiate a new session if needed
        }
    },
    …
});

Example of onResult Request with Session Expiration Handling

simplyConnect ({…
  onResult: function(result) {
    console.log("Result", result);
    if (result.session_expired == true) {
      console.log("session expired->", result);
        // handle session expiration, initiate a new session if needed
    }
  },
…});