On this page:

Overview

Simply Connect provides an out-of-the-box payment experience. It also provides many ways to control the payment process using checkout() method input parameters, Event Callbacks, and Simply Connect Methods.

This topic describes how to:

“Hook” into the Nuvei Simply Connect payment process using process Event Callbacks.
Divert the process using our Simply Connect Methods, or perform your own custom action.

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. When a payment event is triggered, the callback function performs the actions that you specify.

For example, these are some “hooks” that you can set at various payment stages:

At the Simply Connect “pre-payment” stage – When the customer presses Pay:
You can use the prePayment() event callback function.
At the payment method selection stage – When the customer selects a payment method:
You can use the onSelectPaymentMethod() event callback function.
At any point when the customer performs any change on the form:
You can use the onPaymentFormChange() event callback function.

Example of using Nuvei’s `prePayment` Event Callback

You can use Nuvei’s prePayment() event callback to perform your own custom risk checking function, before proceeding to payment:

The customer selects a payment method (for example a credit card) on the Simply Connect form, and presses PAY.
Before proceeding to accept the payment, Nuvei calls the function that you specified using the prePayment()) event callback.
The function, for example, receive all the payment and transaction details as the input, which you then use to call your risk service.
Based on the risk assessment, you decide whether to continue to accept the payment, or stop the flow and display the relevant rejection message.

Event Callbacks

You can set the following event callback input fields, to call a specified function when that event is triggered.

`onReady()`

The onReady() event callback is called when the only input is the loaded Boolean, which indicates that the Simply Connect form is fully loaded.

Example `onReady()` Event Callback

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

`onPaymentFormChange()`

The onPaymentFormChange() event callback is called when focus moves to/away from any field or object on the Simply Connect form.
This is useful for tracking customer behavior on the Simply Connect form, and for performing user activity analytics. For example, when selecting a field, changing a field value, error validation etc.
The following information is passed via the event callback when it is triggered:

pm – paymentMethod
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.

Example `onPaymentFormChange()` Event Callback

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

`prePayment()`

The prePayment() event callback is called when the customer selects the PAY button, but before proceeding to payment.

Example `prePayment()` Event Callback

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

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

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

Example of the Transaction Response Details and the Transaction Details Passed as Input

{
    "paymentOption":{
        "upo":{
            "paymentMethodName":"cc_card",
            "upoName":"4****0961",
            "upoRegistrationDate":"20211124",
            "expiryDate":"20230223",
            "upoStatus":"enabled",
            "userPaymentOptionId":71327218,
            "depositSuccess":"true",
            "withdrawSuccess":"false",
            "upoData":{
                "issuerCountry":"GB",
                "uniqueCC":"yKHZK4vGCyf0c/Se7rujEvNQtN8=",
                "ccCardNumber":"4****0961",
                "cardProduct":"",
                "bin":"400002",
                "cardType":"Credit",
                "ccExpMonth":"02",
                "ccExpYear":"22",
                "allowDcc":"false",
                "optionalWdType":"",
                "brand":"visa",
                "ccNameOnCard":"CL-BRW1"
            }
        }
    },
    "amount":30,
    "currency":"EUR",
    "useDCC":false,
    "dccDetails":{
        
    }
}

You can then specify the next action to be performed in the flow.
Possible values:

resolve() – To continue with the payment.
reject() – To stop the payment.
reject(message) – To stop the payment with a message.

`onResult()`

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

Example `onResult()` Event Callback

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

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

Example of the transaction response details and the transaction details passed as input

{
    "result":"APPROVED",
    "errCode":"0",
    "errorDescription":"",
    "userPaymentOptionId":"",
    "cavv":"",
    "eci":"6",
    "dsTransID":"",
    "ccCardNumber":"4****1111",
    "bin":"411111",
    "last4Digits":"1111",
    "ccExpMonth":"02",
    "ccExpYear":"22",
    "transactionId":"711000000004301096",
    "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 (contact Nuvei Technical Support if needed).

The best way to handle the expiration is to re-authenticate the customer if needed and then call /openOrder again to get a new session token (this has to be done on the server side).

The code sample below includes session expiration handling.

Example `onResult()` Event Callback with Session Expiration Handling

checkout({…
  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
    }
  },
…});

`userData()`

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

This is useful when your payment form is on the same page as the Simply Connect form, and you wish the fields collected to be submitted with the payment.

Example `userData()` Event Callback

checkout({…
  userData: function(userDataObj) {

    console.log("userData", userDataObj);
    return {
      billingAddress: {
        email: "john.smith@email.com",
        country: "US",
      },
      shippingAddress: {
        city: "Boston",
      },
      userDetails: {
        "firstName": "John",
        "lastName": "Smith"
      }
    }
  },
…});

The returned value should be the userDetails() you wish to set in the following format:

"return"{
    "billingAddress":{
        "email":"test@test.com",
        "country":"US"
    },
    "shippingAddress":{
        "city":"Boston"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith"
    }
}

`onSelectedPaymentMethod()`

The onSelectedPaymentMethod() event callback is called when a customer selects a payment method from the gallery, either an existing UPO (user payment option) or a new one.

Example `onSelectedPaymentMethod()` Event Callback

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

For an existing UPO, the merchant receives all the information about the UPO.

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

{
  "paymentOption":{
    "upo":{
      "paymentMethodName":"cc_card",
      "upoName":"4****0961",
      "upoRegistrationDate":"20211124",
      "expiryDate":"20230223",
      "upoStatus":"enabled",
      "userPaymentOptionId":71327218,
      "depositSuccess":"true",
      "withdrawSuccess":"false",
      "upoData":{
        "issuerCountry":"GB",
        "uniqueCC":"yKHZK4vGCyf0c/Se7rujEvNQtN8=",
        "ccCardNumber":"4****0961",
        "cardProduct":"",
        "bin":"400002",
        "cardType":"Credit",
        "ccExpMonth":"02",
        "ccExpYear":"22",
        "allowDcc":"false",
        "optionalWdType":"",
        "brand":"visa",
        "ccNameOnCard":"CL-BRW1"
      }
    }
  },
  "amount":30,
  "currency":"EUR",
  "useDCC":false,
  "dccDetails":{
    
  }
}

`upoDeleted()`

The upoDeleted() event callback is called when a customer selects and removes a UPO from the gallery. Note that the event is called after the customer actually confirms that the UPO should be deleted.

Example `upoDeleted()` Event Callback

checkout({…
  upoDeleted: function(paymentDetails) {

    console.log("upoDeleted", paymentDetails);

  },
…});

The merchant receives all information about the UPO:

{
  "paymentOption":{
    "upo":{
      "paymentMethodName":"cc_card",
      "upoName":"4****0961",
      "upoRegistrationDate":"20211124",
      "expiryDate":"20230223",
      "upoStatus":"enabled",
      "userPaymentOptionId":71327218,
      "depositSuccess":"true",
      "withdrawSuccess":"false",
      "upoData":{
        "issuerCountry":"GB",
        "uniqueCC":"yKHZK4vGCyf0c/Se7rujEvNQtN8=",
        "ccCardNumber":"4****0961",
        "cardProduct":"",
        "bin":"400002",
        "cardType":"Credit",
        "ccExpMonth":"02",
        "ccExpYear":"22",
        "allowDcc":"false",
        "optionalWdType":"",
        "brand":"visa",
        "ccNameOnCard":"CL-BRW1"
      }
    }
  },
  "amount":30,
  "currency":"EUR",
  "useDCC":false,
  "dccDetails":{
    
  }
}

`onPaymentEvent()`

This event callback provides maximum transparency into the payment flow, by reporting back to you at each stage of the payment flow. You can use this information for analytics or perform some custom action.

Example `onPaymentEvent()` Event Callback

checkout({…
  onPaymentEvent: function(result) {
    console.log('onPaymentEvent =>', result);
  },
…});

The following information is passed via the event callback when it is triggered:

pm
Example values:
- cc_card
- apmgw_neteller
eventType
Possible values:
- initiated (once payment initiated)
- tokenized (after initAuth3D)
- paymentStarted (after clientPayment() / clientAuthorize3D())
- challengeStarted (before redirection)
- challengeEnded (after finalizePayment())
- redirectionStarted (for APM)
- redirectionEnded (for APM)
threeD (only when 3DS is applicable – no need for the irrelevant events)
- version
- flow
  Possible values:
  - frictionless
  - challenge

Example `onPaymentEvent()` Response

{
  "eventType": "paymentStarted",
  "threeD": {
    "version": "",
    "flow": ""
  },
  "pm": "cc_card"
}

`onDeclineRecovery()`

This allows merchants to override the decline recovery recommendations with their own preferences each time the decline recovery dialog is to be displayed.

When the function is called, the history (declineRecoveryHistory) of all the previous decline recovery actions taken by the user is sent to the Merchant. The Merchant can then use declineRecoveryOverride to return the decline recovery suggestions they prefer.

Example `onDeclineRecovery()` Event Callback

var isOverriden = false;
checkout({..., 
   disableDeclineRecovery: false, 
     onDeclineRecovery: function(declineRecoveryHistory) { 
      console.log('Decline Recovery History =>', declineRecoveryHistory); 
      var declineRecoveryOverride; 
      if (!isOverriden) { 
        declineRecoveryOverride = {nextPm: true, differentCard: true, retry: true, supportMessage: 'test@test.com'}; 
         isOverriden = true; 
      } 
      return new Promise((resolve, reject) => { 
        resolve(declineRecoveryOverride ); 
       }); 
    }, 
  })
…});

The following are the possible suggestions for declineRecoveryHistory and declineRecoveryOverride:

nextPm – Displays another payment method. Possible values: True, False (default)
differentCard – Allows the user to enter a different credit card. Possible values: True, False (default)
retry – Tries the same payment method again. Possible values: True, False (default)
supportMessage – Displays either an email, a phone number, or just text.

Simply Connect Methods

Press here to see all the Simply Connect methods, which provide additional ways to control the payment process and/or perform your own custom action during the payment process.

Advanced Controls

Overview

Example of using Nuvei’s prePayment Event Callback

Event Callbacks

onReady()

Example onReady() Event Callback

onPaymentFormChange()

Example onPaymentFormChange() Event Callback

prePayment()

Example prePayment() Event Callback

Example of the Transaction Response Details and the Transaction Details Passed as Input

onResult()

Example onResult() Event Callback

Example of the transaction response details and the transaction details passed as input

Example onResult() Event Callback with Session Expiration Handling

userData()

Example userData() Event Callback

onSelectedPaymentMethod()

Example onSelectedPaymentMethod() Event Callback

upoDeleted()

Example upoDeleted() Event Callback

onPaymentEvent()

Example onPaymentEvent() Event Callback

Example onPaymentEvent() Response

onDeclineRecovery()

Example onDeclineRecovery() Event Callback