• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    UI Customization

    On this page:
    • Overview
    • country, currency and locale
    • Text and Translation
    • Response Customization
      • Checkout Message
      • Personalized Message
    • Card Logo
    • Pay Button
    • UI Styling
    • Checkout Styling Code Example

    Overview

    This topic describes the following Checkout UI customization topics:

    • locale (language), country, and currency
    • Text and Translation Customization
    • Response Customization
      • Checkout Message
      • Personalized Message
    • Card Logo
    • Pay Button
    • UI Styling

    country, currency and locale

    The country and currency can be used to filter the supported / relevant payment methods displayed to the customer.

    locale sets the language used in the Payment Page.

    checkout({…
        currency: 'EUR',
        country: 'DE',
        locale: 'en', // de, es, fr, it, pt, ru…
    });

    Text and Translation

    The i18n parameter is used to “internationalize” text and messages, by defining alternative custom text and messages that override the existing defaults. For example, you can set the text displayed on “card labels” to one of the following supported languages: German, Spanish, French, Italian, Portuguese.

    Example of i18n
    apmgw_MBWAY                  : 'MB WAY',
    apmgw_Vseobecna_uverova_Banka: 'VÚB banka',
    apmgw_Unicredit_Bank_SK      : 'Unicredit banka',
    apmgw_Slovenska_sporitelna   : 'Slovenská sporiteľňa',
    apmgw_ApmEmulator            : 'APM Emulator',
    apmgw_Banki_Sp_ldzielcze     : 'Banki Spółdzielcze',
    apmgw_expresscheckout        : 'PayPal',
    apmgw_BLIK_Redirect          : 'BLIK',
    apmgw_BNP                    : 'BNP Paribas',
    apmgw_BOS_Bank               : 'BOŚ Bank',
    apmgw_BZWBK                  : 'Santander Bank Polska',
    apmgw_Przelew_bankowy        : 'Przelew bankowy',
    apmgw_Pekao                  : 'Bank Pekao',
    apmgw_PaySafeCash            : 'Paysafecash',
    apmgw_mBank_PL               : 'mBank',
    apmgw_AstropayPrePaid_BF     : 'Astropay PrePaid',
    apmgw_Credit_Agricole        : 'Crédit Agricole',
    apmgw_CSOB                   : 'ČSOB',
    apmgw_CSOB_SK                : 'ČSOB',
    apmgw_Postova_Banka          : 'Poštová banka',
    apmgw_Zimpler_SE             : 'Zimpler',
    apmgw_Argencard              : 'ArgenCard',
    apmgw_MazoomaOBT             : 'Mazooma OBT',
    apmgw_Sofort                 : 'Sofortüberweisung ',
    apmgw_WebMoney               : 'WebMoney',
    apmgw_P24                    : 'Przelewy24',
    apmgw_Epay_bg                : 'ePay.bg',
    // UI labels
    my_methods                   : 'My payment methods', // payment.info.my.methods
    other_methods                : 'Select your payment method', // select.your.payment.method
    cancel                       : 'Cancel',  // button.cancel
    pay_with                     : 'Pay with ',
    success                      : "Success",
    success_text                 : "Your transaction was successfully approved.",
    ok                           : 'OK',
    remove_payment_method        : 'Remove payment method',
    del_confirm_msg              : 'Once removed, this payment method will no longer be available. Are you sure?',
    yes_remove_it                : 'Yes. Remove it.',
    remove                       : 'Remove',
    declined                     : 'Declined',
    trx_failed_msg               : 'Your payment transaction has failed. Would you like to enter new payment details and try again?',
    twp_msg                      : 'Payment was already performed!',
    button_refresh               : "Refresh",
    refresh_invalid_session_message: "Looks like you are taking your time. Click the refresh button to try again.",
    pending                      : 'Transaction pending',
    // fields
    cc_name_on_card              : 'Name on Card',
    cc_card_number               : 'Card Number',
    card_number                  : 'card placeholder',
    cvv                          : 'CVV/CVC placeholder',
    mm_yy                        : 'month placeholder',
    expiry_date                  : 'Expiry date',
    BR_personal_id               : "CPF / CNPJ",
    MX_personal_id               : "CURP / RFC / IFE",
    CL_personal_id               : "RUN/RUT",
    PE_personal_id               : "DNI",
    UY_personal_id               : "CI",
    PY_personal_id               : "CI",
    AR_personal_id               : "DNI / CUIT",
    CO_personal_id               : "CC",
    personal_id                  : "Personal ID",
    skrill_recurring_id          : "Skrill E-Mail",
    payer_name                   : "Payer Name",
    ideal_bic                    : "BIC",
    close                        : "Close",
    pay                          : "Pay",
    APM_redirect_msg             : "Don’t see the <%- label %> purchase page? We will help you return to the window to complete your purchase.",
    continue                     : "Continue",
    save_details                 : "Save my details for future use",
    cardholder_name              : "Cardholder Name",
    invalid_cardholder_name      : "Invalid cardholder name",
    invalid_creditcard           : "Please enter a valid card number",
    invalid_expiration_date      : "Invalid expiration date",
    invalid_cvv                  : "CVV is invalid",
    nettelerAccount              : "Account ID",
    invalid_nettelerAccount      : "Please enter a valid email address.",
    iDebit_account_id            : "Account ID",
    invalid_idebit_account_id    : "Invalid iDebit Account ID",
    account_id                   : "Account ID",
    invalid_account_id           : "Invalid Account ID",
    verification_email           : "Verification email",
    invalid_iban                 : "Please enter a valid IBAN.",
    use_currency_conversion      : "Use currency conversion.",
    dcc_caution                  : "Make sure you understand the costs of currency conversion as they may be different depending on whether you select your home currency or the transaction currency.",
    margin_included              : "(5% margin included)",
    blockCardMsg                 : "The card is blocked"

    Response Customization

    As with any payment checkout experience, each time a payment transaction attempt ends (either declined or approved), the user must be notified of the outcome.

    With Checkout, you can control the UI/UX of the notification messages to the user, in two modes:

    Checkout Message

    You can use Nuvei’s default UI/UX for the response messages, and control the UI and the message text.

    • This default behavior means that  showResponseMessage is set to true on the checkout() call and a standard Checkout message is shown:
         
    • You can control the styling.
    • You can control the error message using the error_i18n:{} block on the checkout call:
      error_i18n: error_i18n: {
            decline: "Your payment request was denied",
            timeoutretry: "Please try again",
            donothonor: "Please contact your bank"
          },
    • In the above example, when “Declined” is returned in the response description, the message to the end user can be changed to “Your payment request was denied”.
    • You can map any decline reason to your customized message to the end user. The key for the error_i8n is as follows:
      • The decline reason (see our full list of decline reasons)
      • Remove all spaces
      • Remove all special characters (eg. “/”)
      • Lower case

    For example, “Timeout/Retry” becomes “timeoutretry”.

    • You can also use this field to translate the decline message to any language.

    Personalized Message

    You have the ability to disable the default Checkout message and handle the communication with the end as you wish: Display your own message, redirect to another page, and so on:

    • Set showResponseMessageto false on the checkout() call.
    • Use the onResult event webhook to receive the transaction output to display the correct message to the user.
    • [Optional] Use the removeOveray(), applyOverlay(), destroy() checkout methods to control the Checkout UI according to the desired behavior.

    Card Logo

    Use this parameter to set a different style for the card logo (size and location).

    • cardLogoPosition – Possible values: right, left.
    • backgroundSize – The size of the log in pixels.

    Alternatively, use cardLogo: false to hide the card logo.

    checkout ({…
        cardLogo: {
            cardLogoPosition: 'right',
            backgroundSize: '30px 40px'
        },  //or cardLogo: false -> to hide the card logo 
    …});

    Pay Button

    You can control the display of the Pay button interface:

    • Text using the i18n-styling block.
    • Design using the styles.
    • Type of button displayed using the payButton parameter:

    payButton ValueDescriptionExample
    amountButton (default)Displays the amount on the button.
    textButtonDisplays text on the button.
    noButtonThe button can be displayed outside the checkout user interface.
    Note: When the customer presses the button, it calls the submitPayment() method, which invokes the payment externally, from Checkout.

    UI Styling

    You can customize the look and feel of Checkout to match your payment page by customizing the styles of the Checkout HTML elements.

    There are two ways of styling the Checkout Payment Form:

    • CSS – You can override the default CSS classes by using the CSS class names to  (click here for an example).
    • JavaScript Style Object for State Stylizing – Control the UI of certain text states (such as empty, invalid, and valid), by setting objects containing those styles.

    Checkout Styling Code Example

    You can test and modify your code using this live JSFiddle Web SDK example.

    2022 Nuvei. All rights reserved.