UI suggestions for cardholder messaging

The ui_suggestion object is a pre-built, localized messaging hint that Varmo generates alongside every delivery status response. It is designed so you can render cardholder-facing copy directly from the API without writing message logic yourself. Each suggestion is matched to the current delivery status, the predicted window, and the destination locale — giving cardholders accurate, appropriately worded information at every stage of the journey.

Fields at a glance

"ui_suggestion": {
  "locale": "en-US",
  "recommended_message": "Your card is likely arriving in the next 1-2 days.",
  "recommended_action": "None"
}

Field	Type	Description
`locale`	string	A BCP 47 locale tag inferred from the destination country code (e.g. `en-US`, `fi-FI`). Use this for language routing in your UI even if you write custom copy.
`recommended_message`	string	A human-readable string you can display to the cardholder verbatim. Phrasing reflects the current status and confidence level.
`recommended_action`	string	An enum indicating what action, if any, the issuer should prompt the cardholder to take. Common values: `None`, `Activate`, `ContactSupport`.

Displaying the message

The following example shows how to render recommended_message in a React component. The component also uses locale to set the lang attribute for correct browser rendering.

function CardDeliveryBanner({ uiSuggestion }) {
  const { locale, recommended_message, recommended_action } = uiSuggestion;

  return (
    <div lang={locale} className="delivery-banner">
      <p>{recommended_message}</p>
      {recommended_action === "Activate" && (
        <button onClick={() => redirectToActivation()}>
          Activate your card
        </button>
      )}
      {recommended_action === "ContactSupport" && (
        <button onClick={() => openSupportChat()}>
          Contact support
        </button>
      )}
    </div>
  );
}

Customizing messaging

recommended_message is a safe default that works for most issuers without any additional configuration. If you need to match a specific brand voice or write copy in a tone that differs from Varmo’s defaults, build your message from the structured prediction fields instead — delivery_window.min, delivery_window.max, and confidence_level give you everything you need to construct accurate, bespoke copy. Even when you write custom messages, retain locale for language routing. Varmo derives the locale from the destination country_code, so it reliably reflects the cardholder’s expected language — handling this yourself from raw country codes is error-prone, especially for multilingual countries.

Recommended actions

The recommended_action field tells you what, if anything, to ask the cardholder to do. Map each value to a corresponding UI state in your app.

Value	Trigger condition	What to do
`None`	Card is in transit or no action is needed yet.	Display `recommended_message` without any call to action.
`Activate`	Card has likely been delivered based on Varmo’s model.	Prompt the cardholder to activate their card via your activation flow.
`ContactSupport`	A delivery exception has been detected.	Prompt the cardholder to contact your support team for assistance.

Get Started

Core Concepts

Guides

Security & Compliance

UI suggestions for cardholder messaging

Fields at a glance

Displaying the message

Customizing messaging

Recommended actions

​Fields at a glance

​Displaying the message

​Customizing messaging

​Recommended actions

Fields at a glance

Displaying the message

Customizing messaging

Recommended actions