Overview
This topic describes the following Checkout UI customization topics:
locale
(language),country
, andcurrency
- Text and Translation Customization
- Response Customization
- 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 thecheckout()
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
showResponseMessage
to false on thecheckout()
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:
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.