• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
< BACK TO HOME
  • Online Payments
    • Introduction to Online Payments
    • Choosing an Integration Method
    • Payment Scenarios
    • Flow Diagrams
  • Accept Payment
    • Payment Page (Cashier)
      • Quick Start for Payment Page
      • Input Parameters
      • Output Parameters
      • Payment Page Features
      • Examples of Cashier Demo Sites
      • Cashier
        • Cashier Events Guide
        • Cashier Features
        • Withdrawal Guide
    • Web SDK
      • Quick Start for Web SDK
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments with Web SDK
      • Tokenization-Only Flow
      • Web SDK Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • Web SDK FAQs
    • Simply Connect
      • Quick Start to Simply Connect
      • UI Customization
      • Payment Customization
      • Advanced Controls
      • Simply Connect Examples
    • Server-to-Server
      • REST 1.0
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
    • Mobile SDKs (Beta Release)
      • Android Mobile SDK (Beta Release)
      • iOS Mobile SDK (Beta Release)
    • Self Track
  • Features
    • Authentication
    • Financial Operations
      • Refund
      • Void
      • Auth and Settle
      • Partial Approval
      • Currency Conversion: DCC and MCP
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Payout
      • Account Funding Transactions (AFTs)
      • P2P Payment with Nuvei
    • Card Operations
      • Card-on-File
      • PCI and Tokenization
      • Zero-Authorization
      • Merchant-Initiated Transactions (MIT)
      • Blocking Cards
    • Subscriptions (Rebilling)
    • 3D-Secure
      • 3D-Secure Explained
      • 3DS Implementations
        • 3DS MPI-Only Web SDK
        • 3DS MPI-Only REST
        • 3DS External MPI
        • 3DS Responses
        • Challenges and Exemptions
      • 3DS Functions
        • 3D-Secure Fingerprinting
        • 3D-Secure Authentication Challenge
    • Addendums
      • Airline
        • External Authorization
      • Local Payment (Installments)
      • Level 2&3 Processing Data
  • Integration
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APMs
      • Testing APIs with Postman
    • Response Handling
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
      • Payment Facilitators (PayFac)
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Advanced Controls

    Home    Simply Connect    Advanced Controls

    On this page:
    • Overview
    • Event Callbacks
      • onReady()
      • onPaymentFormChange()
      • prePayment()
      • onResult()
      • userData()
      • onSelectedPaymentMethod()
      • upoDeleted()
      • onPaymentEvent()
      • onDeclineRecovery()
    • Simply Connect Methods

    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.

      • Language fr
    • Terms of use
    • Privacy Policy
    Nuvei. All rights reserved.