Overview

This topic describes the following Simply Connect UI customization topics:

• locale (language), country, and currency
• Text and Translation Customization
  • Custom Messages
• Response Customization
  • Simply Connect Message
  • Personalized Message
• Card Icon
• Card Scheme Logos
• 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 class 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: French, German, Hebrew, Italian, Polish, Portuguese, Russian, and Spanish.

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"

Custom Messages

Merchants can add custom message keys per payment method in one of three possible positions. The key format is  apmgw_paymentname_position, where:

• apmgw_paymentname is a payment method; for example, cc_card or apmgw_skrill
• position can be aboveButton, aboveDetails, or belowButton

These keys support English and other supported languages, HTML tagging, and unlimited character length.

Examples

apmgw_iDeal_aboveButton      :"Custom text above button for iDeal payments."

checkout({
  i18n: {
    cc_card_aboveButton: "Custom text above button for card payments.",

    cc_card_aboveDetails: "Custom text above payment details for card payments.",

    cc_card_belowButton: "Custom text below button for card payments.",
  },
})

Response Customization

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

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

Simply Connect 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 payment message is shown:
     
• You can control the styling.
• You can control the error message using the error_i18n:{} class 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 payment 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() Simply Connect methods to control the payment UI according to the desired behavior.

Card Icon

Use the cardLogo class with these parameters to define the position and size of the card icon that appears in the card number field.

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

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

To hide this card icon, use cardLogo: false.

Card Scheme Logos

showCardLogos determines whether card scheme logos appear on the Simply Connect form. By default, logos do not appear (false). To enable logos for supported card schemes, set showCardLogos to true.

checkout ({…
      showCardLogos: true, // default is false 
      blockCards: ["visa","mastercard","maestro","amex"],...
})

Pay Button

You can control the display of the Pay button interface:

• Text using the Text and Translation i18n styling class.
• Design using the styles.
• Type of button displayed using the payButton parameter:

payButton Value	Description	Example
amountButton (default)	Displays the amount on the button.
textButton	Displays text on the button.
noButton	The 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 Simply Connect to match your payment page by customizing the styles of the Simply Connect HTML elements.

There are two ways of styling the Simply Connect payment form:

• CSS – You can override the default CSS classes by using the CSS class names (press 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.

Simply Connect Styling Code Example

You can test and modify your code using this live JSFiddle Simply Connect example.