• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
< BACK TO HOME
  • Online Payments
    • Introduction
    • Choosing an Integration Method
    • Payment Scenarios
    • Flow Diagrams
  • Accept Payment
    • Payment Page (Cashier)
      • Quick Start
      • Input Parameters
      • Output Parameters
      • Payment Page Features
      • Cashier
        • Cashier Events Guide
        • Cashier Features
        • Withdrawal Guide
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Simply Connect
      • Quick Start
        • 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)
      • Marketplaces
      • 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
        • AFT (Account Funding Transactions)
      • 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)
    • 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

    Payment Customization

    Home    Simply Connect    Payment Customization

    On this page:
    • Overview
    • General
    • Card Processing
    • Apple Pay and Google Pay
    • APMs
    • Dynamic Payment Amount
    • Open Amount Feature

    Overview

    Nuvei Simply Connect provides an out-of-the-box payment experience, but it also allows you to control the process by setting values on the checkout() input and/or switching certain values on or off.

    This page describes some of the many ways you can customize the Simply Connect payment flow.

    The customizations described in this topic are implemented in the JS code, which enables you to accommodate the behavior for the specific user or user session.

    General

    Save Payment Method

    The savePM parameter is used to display the “Save my details for future use” checkbox for each payment method in the Payment Methods list.

    Possible values:

    • true (default) – Users can save payment details for UPOs.

      This is needed for the initial request of an APM Recurring Billing transaction.

      Example of using savePM: true

    • force – The checkbox is displayed and checked initially (the customer is still able to clear the checkbox).
    • false – Users cannot save payment details for UPOs.
    • always – Instead of the checkbox, an agreement message is displayed and payment details are always saved.
      In addition, you can include the savePmUrl parameter containing a link to the “Terms and Conditions for saving payment details”.

      savePM must be set to always for the savePmUrl to be displayed in addition to the agreement message.

      Example of savePM:always using savePmUrl
      checkout({…
          savePM: always,
          savePmUrl: "<a url for the T&C>",
      …});

    Dynamic Currency Conversion

    You can use the useDCC input field to enable, disable or force the use of DCC on the payment page.

    Possible values for DCC control:

    • enable – Enables the checkbox.
    • disable – (default): Disables the checkbox.
    • force – Enables and selects the checkbox (the customer is still able to unselect the checkbox).
    checkout ({…
        useDCC: "enable", //or disable, force
    …});

    Card Processing

    Card Blocking Rules

    blockCards – Specifies which sets of cards can be blocked from appearing to the customer in Payment Methods lists.

    See Blocking Cards for more information.

    checkout({…
        blockCards: [
            ["visa", "credit", "corporate"],
            ["amex", "GB"]
        ], //blocks Visa corporate credit cards, and also blocks British Amex cards
    …});

    CVV Customization

    alwaysCollectCvv – Determines if the CVV should be collected for a stored card each time (default is true).

    maskCvv – Determines if the CVV digits in the CVV textbox are masked or visible (default is false).

    checkout({…
        alwaysCollectCvv: true,
        maskCvv: false
    …});

    In some cases, a merchant may want to perform an MPI Only request, which means that a payment request is initiated for the 3DS validation, but an actual payment is not made. You can set it using the cardAuthMode input field.

    MPI Only

    The response to such a request:

    • Includes the 3D Secure authentication.
    • If the request is successful, a result status of AUTHENTICATED is returned (other possible values: DECLINED, ERROR). Please follow the MPI-only guide for further details on this flow.

    Possible values:

    • 3dAuthOnly – Always performs only the 3DS validation (no payment)
    • 3dAuthForNewCardsOnly – Performs only 3DS validation, but only for first-time processing (not including UPOs).
    • paymentForAll (default) – Performs 3D Secure validation and proceeds to “payment” automatically.
    checkout({…
        cardAuthMode: "3dAuthOnly",
    …});

    Decline Recovery

    A certain percentage of payment requests are declined leading to the loss of those potential sales and transactions. This feature enables you to recover as many of these potential sales and transactions as possible.

    To enable this feature, add  disableDeclineRecovery: false to the checkout() function.

    When the customer receives a decline, a pop-up or dialog offers other payment options:

    • Contacting the merchant for support.
    • Selecting another payment from the payment gallery.
    • For the gaming industry, you have the option to suggest or enter a new amount.

    checkout({...
      disableDeclineRecovery: false, // The default value is true.
    ...})
    

    Apple Pay and Google Pay

    Google Pay

    You can enable Google Pay as a payment method for your customers.

    Simply follow the steps in the Google Pay guide (Simply Connect) guide.

    • No special configuration code is needed.
    • However, if you prefer, we provide a set of powerful customizations which are easy to apply.

    Apple Pay

    You can enable Apple Pay as a payment method for your customers:

    • Contact Nuvei Tech Support to enable the Apple Pay payment provider in your merchant account.
    • Set your domain, as described in the Register and Verify Your Domain topic.
    • No special configuration code is needed.
      However, if you prefer, we provide a set of powerful customizations which are easy to apply.

    APMs

    autoOpenPM

    The optional parameter controls whether APM section of the Payment Method Gallery is always open or is collapsible, in the presence of a UPO.

    Possible values:

    • true (default) – The APM section is never collapsible.
    • false – The APM section is collapsible only if UPOs exist; otherwise, it is not collapsible.
      False provides a very conversion driven UX for users with UPOs
    Example of using autoOpenPM
    checkout({...
      autoOpenPM: false, // False provides a very conversion driven UX for users with UPOs.
    ...})
    
    Example of using autoOpenPM: false

    APM Whitelisting/Blacklisting

    The APMs supported for your account is set on the Nuvei server-side and, by default, only APMs relevant to the end user are displayed (according to country and currency). However, in some cases, you may want to override certain APMs for a certain audience, specific users, or a specific user session. This can be done by either whitelisting the APMs you would like to show, or by blacklisting the ones you wish to hide:

    • pmWhitelist – Only the specified APMs are displayed to the customer in the Payment Methods list.
    • pmBlacklist – The specified APMs are not displayed to the customer in the Payment Methods list, even if they are returned by an API.

    pmWhiteList and pmBlacklist cannot be included in the same request.

    checkout({…
        pmBlacklist: ['apmgw_PaySafeCard', 'apmgw_Neteller', 'apmgw_MoneyBookers'],
        // -or- pmWhitelist: ['apmgw_PaySafeCard', 'apmgw_Neteller', 'apmgw_MoneyBookers', 'cc_card'],
    …});

    APM Fields

    Some APMs require additional user fields (such as billingAddress and userDetails) that can be collected from the user during the payment initialization. The merchant can provide these fields to mitigate user friction. If, however, these fields are not provided, this feature prevents the payment from failing by automatically detecting that the fields were not provided and instead collecting them directly from the payment page (see Sepa example):
    1.png

    function main() {
        document.getElementById('checkout').innerHTML = "";
        checkout({
            sessionToken: document.getElementById('session').value,
            env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
            merchantSiteId: '<your merchantSiteId goes here>',
            merchantId: '<your merchantId goes here>',
            country: 'US',
            currency: 'USD',
            amount: 135,
            userId: '259',
            "billingAddress": {
                "email": "john.smith@email.com",
                "country": "US"
            },
            renderTo: '#checkout', // <div id="container"></div>
            onResult: function(result) {
                console.log("Result", result)
            },
     
            fullName: document.getElementById('cardHolderName').value,
            email: 'john.smith@email.com',
            locale: 'en', // de, es, fr, it, pt, ru
            }
        });
    }

    apmWindowType

    This allows you to specify the window type (popup, newTab, or redirect (modal window)) for the system to redirect the customer to their APM provider. Alternatively, by specifying customRedirect, the system provides you with the redirectUrl for you to initiate the redirect.

    Possible values:

    • popup (default) – A po-pup window opens automatically, redirecting the customer to their APM provider’s page.
    • newTab – A new tab opens automatically, redirecting the customer to their APM provider’s page.
    • redirect – A modal window opens automatically on top of the current payment page, redirecting the customer to their APM provider’s page.

      To use the redirect window type, you must have already provided the urlDetails (e.g. urlDetails.successUrl, etc.) in the /openOrder request, for the system to navigate the customer back to, after leaving the APM provider’s page.

    • customRedirect – You (the merchant) must redirect your customer to their APM provider’s page, as follows:
      1. The response from the request includes a redirectUrl.
        Redirect your customer to this redirectUrl using a type of window of your choice, for example, IFrame, pop-up, a new tab, etc.
      2. Your customer submits their APM details and closes the window.
      3. Check the transaction status either by sending a /getPaymentStatus request, or by setting up a DMN to receive a direct notification, (at the webhook endpoint on your system, which you provided in the urlDetails.notificationUrl in the original /openOrder request).
    checkout({
      ...
      apmWindowType: 'newTab', // 'popup' (default), 'redirect', 'customRedirect'
      ...
    })

    Dynamic Payment Amount

    Simply Connect allows you to change the payment dynamically amount according to customer input or behavior using Open Order Features, for example, the /updateOrder API call to change the actual payment amount, as well as using Simply Connect Event Callbacks.
    For example, when a customer:

    • Adds or removes purchased products from their shopping cart.
    • Or, selects certain payment methods which require additional charges when using their service.

    You can use event callbacks such as prePayment(),  onSelectPaymentMethod(), and onPaymentFormChange() to trigger an /updateOrder API call to update the payment amount.  For example when a customer selects a payment method that requires the addition of a specific “payment method fee”.
    For more details, see the list of Simply Connect Event Callbacks.

    Changing the amount based on Customer Input

    You can set a “hook” on a customer event to trigger a callback function that updates the payment amount.

    The following example uses the prePayment() callback to change the payment amount in the order before proceeding with the payment, for example, to add additional fees required by certain Payment Methods:

    • The needToUpdateAmount(paymentDetails) function is used to determine if the original payment amount has changed (and therefore the payment amount in the order will also need to be updated).
      (paymentDetails is provided in the input parameters of the prePayment() callback.)
    • In a case where the amount needs to be updated, but the customer still needs to agree to the new amount:
      Display an appropriate message informing the customer about the new payment amount, and ask if they wish to proceed.
      • If the customer declines, then use the reject() function to instruct Simply Connect to abort payment, and display the relevant custom error message.
      • If the customer agrees to proceed, then continue:
        1. The updateAmountInUI() function updates the displayed amount.
        2. The callServerSideToUpdateOrder() function passes the decision to your server-side, and then a server-side /updateOrder request is performed to set the new amount.
        3. The resolve() instructs Simply Connect to proceed to payment, (based on the new amount).
    Example Simply Connect Code using the prePayment() Callback Function to Change the Amount Based on Customer Input
    prePayment: function(paymentDetails) {
      return new Promise(async(resolve, reject) => {
    
        //you get PM and card details such as name, card type, etc. in paymentDetails.paymentOption.card
    
        If(needToUpdateAmount(paymentDetails)) //decide if you want to update the amount
          updateAmountInUI();
          callServerSideToUpdateOrder() // openOrder server-side call sample below
          resolve(); // proceed with payment
        //else
          //  reject("<message to the user>");
      });
    },
    Example /updateOrder Request

    The /updateOrder request, (like the /openOrder request), must only be called from the server-side, to prevent client-side manipulation.

    {
      "sessionToken": "<sessiontoken received from openOrder>",
      "orderId": "<orderId received from openOrder>",
      "merchantSiteId": "<your merchantSiteId>",
      "merchantId": "<your merchantId>",
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>",
      "currency": "USD",
      "amount": "300",
      "items": [
        {
          "name": "product X",
          "price": "300",
          "quantity": "1"
        }
      ]
    }

    Open Amount Feature

    This feature supports merchants in industries where the payment amount is not known at the beginning of the payment flow, or needs to be updated on the client-side device, for example, in the gambling industry.

    The Open Amount feature allows you to:

    • Set Amount Limits (min and max) in the /openOrder request.
    • Call the checkout.setOpenAmount() method (if you have not sent the checkout() request yet).

    Set Amount Limits

    Before using this feature, contact Nuvei Support to enable the openAmount feature in your merchant account configuration.
    This is required because changing the amount is normally only performed using server-side APIs.

    When using this feature, payButton must be set to textButton.

    You can set “payment amount limits” in the /openOrder request by including the openAmount{min,max} object.

    In such a case, the payment amount parameter is no longer mandatory in the /openOrder request.

    • If you do send the amount in the /openOrder request, then you can override it later from the client-side Simply Connect.
    • However, if you do not send the amount in the /openOrder request, then you must provide the amount later.

    Send an /openOrder request with its mandatory parameters, and include an openAmount{min,max} object (and the optional amount), as shown below:

    Example /openOrder Request with an openAmount{min,max} Object
    {
      "merchantId": "<your merchantId goes here>",
      "merchantSiteId": "<your merchantSiteId goes here>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "clientRequestId": "<unique request ID in merchant system>",
      "currency": "USD",
      "openAmount": {
        "min": "1",
        "max": "100"
      },
      "amount": "50",
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }

    MCP conversion is not supported if you include the openAmount{min,max} object in the /openOrder request, because the customer is able to change the payment amount later.

    checkout.setOpenAmount() Method

    You can only call the checkout.setOpenAmount() method before calling a checkout() request.

    The checkout.setOpenAmount() method is used to set/overridden the payment amount (same currency) from the client-side.

    Use the checkout.setOpenAmount() method when you need to set the transaction amount.
    For example, whenever the customer changes any amount on your payment page, etc.

    Call the checkout.setOpenAmount() method from the client-side, as shown below:
    (If you included the openAmount{min,max} object in the /openOrder request earlier, then the system also validates that the amount falls within the (min,max) “limits”.)

    Example checkout.setOpenAmount() Request
    checkout.setOpenAmount('150', function(setOpenOrderResponse) {
        //Merchant code here
        console.log(setOpenOrderResponse);
    })
    • Terms of use
    • Privacy Policy
    Nuvei. All rights reserved.