Overriding default library text

  Last updated: 

When initialising the st.js library, you can translate the default text values of:

  • Messages appearing inside of the notification div (st-notification-frame)
  • Card Components labels
  • Card "Pay" button
  • Card Components validation labels

 

  Advantages:

  • Provide alternative wording to the default phrases to better reflect your brand’s voice.
  • Translate text into languages we don’t currently accept as a supported locale (as described on this page).

Screenshot of checkout with default fields "Card number", "Expiration date", "Security code". The submit button reads "Pay".
Unmodified Card Components

 

Translating the text

During the initialisation of the st.js library, you can update the default text using the translations property. The translation property expects a dictionary, where each key represents the default text to override. For each key specified in the translations object, you will need to provide a custom text value.

<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number" class="st-card-number"></div>
<div id="st-expiration-date" class="st-expiration-date"></div>
<div id="st-security-code" class="st-security-code"></div>
<button type="submit" id="st-form__submit" class="st-form__submit">
Pay securely
</button>
</form>
<script src="https://cdn.eu.trustpayments.com/js/latest/st.js"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
translations:{'An error occurred': 'INSERT YOUR CUSTOM PHRASE HERE'},
});
st.Components();
})();
</script>
</body>
</html>

 

Here is the full list of phrases for which custom text can be specified:
Important: These are case sensitive.

  • Notification div messages:
    • “A target element for the input field with id could not be found. Please check your configuration”
    • “Amount and currency are not set”
    • “An error occurred”
    • “Decline”
    • “Form is not valid”
    • “Invalid field”
    • “Invalid request”
    • “Invalid response”
    • “Merchant validation failure”
    • “Method not implemented”
    • “Payment has been cancelled”
    • “Payment has been successfully processed”
    • “Timeout”
    • “You are not logged to Apple account”

Screenshot of an example checkout built using our JavaScript Library displaying a default error message: "An error occurred".     Screenshot of an example checkout built using our JavaScript Library displaying a custom error: "Something went wrong".
Before and after – Customising the notification div messages

  • Card Components labels:
    • “Card number”
    • “Expiration date”
    • “Security code”

Screenshot of checkout with default fields "Card number", "Expiration date", "Security code". The submit button reads "Pay".     Screenshot of an example checkout with custom fields "Pan", "Expiry date" and "CVV2".
Before and after – Customising the labels

  • Card "Pay" button:
    • “Pay”
    • “Processing”

Screenshot of checkout with default fields "Card number", "Expiration date", "Security code". The submit button reads "Pay".     Screenshot of an example checkout with a custom submit button with the text: "Pay now".
Before and after – Customising the button

  • Card Components validation labels:
    • “Field is required”
    • “Value is too short”
    • “Value mismatch pattern”

Screenshot of an example checkout with a default field error that reads: "Value mismatch pattern".     Screenshot of an example checkout with a customised field error that reads: "Invalid field".
Before and after – Customising the validation labels

 

Custom translations post initialisation of st.js library

After initialisation of the st.js library, the values assigned to translations can be overridden using the method updateTranslations(translations: object, replace = false): void

  • The first argument accepts a translations object matching the specification provided to the initial config.
  • The second argument replace is optional and defaults to false.
    • When false, the updateTranslations method retains the original translations object during initialisation and modifies the messages and label keys specified in the new object.
    • When true, the updateTranslations method overrides the text translations provided in the original translations object.

 

Example Use Case

When initialising the st.js library, let’s suppose you’d like to translate the “Pay” button to include amount:

translations: {'Pay': 'Pay £15.99'}

If at any point the total price changes (e.g. due to shipping fees), you will need to update the amount displayed on the “Pay” button by invoking updateTranslations method, like so:

st.updateTranslations({'Pay': 'Pay £18.99'}, replace = false);

By using replace=false, this ensures that only the “Pay” button translation is affected, and all other translations specified during initialisation are left unchanged.

  The updateTranslations method as described in the example above can only ever update the amount displayed to the customer, not the actual transaction amount processed.

To update the amount charged to the customer, you will need to generate a newly- signed JWT on your server including the new amount and pass this as the first argument of the updateJWT method.

Click here to learn more about the updateJWT method.

Was this article helpful?
0 out of 0 found this helpful