Documentation

Customize payment stepper messages

Customize messages displayed during payment processing using the payment stepper.

Ask about this Page
Copy for LLM
View as Markdown

During a checkout that uses a device or payment entry device (PED) for payment, InStore displays payment stepper messages about events received from the payment services provider (PSP). The messaging from the PSP can explain activity delays, prompt for action, and promote confidence that processing remains active. PSP latency can be unpredictable, so displaying status can reduce the risk that the user will cancel a slow but successful payment.

Base messages included with InStore

The following base messages are built into the product and displayed during payment processing:

  • The Credit.processingPayment string is displayed while InStore is waiting to establish the Server-Sent Events (SSE) connection, which may take several seconds. This is to avoid a blank screen until the first SSE message is sent.
  • The CashCollection.userMessageCreditApproved string is displayed after a successful payment only if no SSE success message is received before the UI screen advances.
  • The UserNotificationError.collectPaymentRejected string is displayed after a rejected payment only if no SSE rejection message is received before the UI screen advances.
  • The Credit.creditPaymentTimeout string is displayed after a payment times out only if no SSE timeout-error message is received before the UI screen advances.

Payment messages are displayed by the payment stepper in real time as they are received from the PSP. The payment stepper stacks messages on the Payment page with the newest messages at the bottom of the stack. The final message is displayed for two seconds before InStore advances to the next page.

InStore displays base messages in US English and supported languages with no action required. You can customize the message content of the base messages.

You cannot suppress the base messages listed above, you can only customize the text.

Additional PSP messages

InStore can display additional event messages from the PSP, whose content you can control. When additional messages are activated, the payment stepper displays up to six messages at a time. Older messages roll off as new messages are received.

Add and customize all payment stepper messages

Messages from the PSP may be too technical or too specific, and retailers may want to show general or user-friendly phrases. You can override PSP message strings to match the localization language for that environment. You can customize the base messages listed above, as well as other incoming PSP messages you choose to display.

To override PSP message text in the payment module, do the following:

  1. Access the customized API route as described in Override product module styling.
  2. Provide the string you want to use, prepended by Custom, as shown in the following example:
Example custom stringjson
  {
   "translations": {
     "en-US": {
       "Custom":{yourCustomization}
     }
   }
Include the Custom prefix because it gives your text priority over other translations that InStore may find for this key. The Custom prefix is stripped before the text is displayed.

Suppress additional PSP messages

Not all incoming PSP events are relevant to users. You can suppress display of event messages (other than the base messages) by not assigning them a string value in the API.

If InStore receives a message from the PSP and does not find a translation string, it passes the message ID but no translation string. In this case, the message is not displayed in the stepper. To suppress a message, do not add a translation for its ID. You can use the message ID to trigger other actions. Again, base messages will always be displayed.

To filter PSP messages, follow these steps:

  1. Access the InStore Client translation.json file.
  2. Ensure that keys for messages you want to display have translations and that other keys do not.
  3. Repeat for every supported locale's file.