Guides
PortalContact Sales
Start typing to search…
  1. Getting Started
  2. Concepts

Challenge Interface

A Challenge Interface is the web page presented to a cardholder when a transaction requires a challenge. It collects the cardholder's response to the chosen Challenge Method - for example, an OTP input field, a biometrics prompt, or a security question - and submits the result back to the ACS.

Each Challenge Method has its own Challenge Interface, and each interface is tailored per Financial Institution using a Blueprint and a Template.

Blueprints and Templates

The appearance of a Challenge Interface is controlled through two layered concepts.

Blueprint

Defines the structure of the challenge page: which elements are present, how they are arranged, and what types of content they can hold (buttons, input fields, timers, logos, text). A blueprint cannot be modified by the issuer -- it is the fixed foundation.

Template

An issuer-created instance of a blueprint. A template cannot add or remove elements, but it controls how those elements look: colours, fonts, styles, spacing, and shadows. Multiple templates can exist for the same blueprint.

📘

A Blueprint defines what the challenge interface contains. A Template defines how it looks.

Only one template can be active at a time per Challenge Method. Templates must be explicitly published to go live. Until published, the default interface is used.

Channels and Categories

Each template is configured independently across three channels and two transaction categories, allowing the interface to be tailored for the context in which it is rendered.

Channels

Browser

Rendered in an iframe within the merchant's checkout page. Supports locale settings and full text customisation for Browser Channel transactions.

App HTML

Rendered as an HTML page within a merchant's mobile app via a web view. Locale settings and text are configured separately from the Browser channel.

App Native

Rendered natively within the app using the 3DS SDK. Locale settings and text are managed separately for this channel.

⚠️

Text and locale changes made in one channel are not automatically applied to others. For example, updating the verify title in the Browser channel requires the same update to be made in App HTML and App Native separately.

Transaction Categories

Payment

Locale settings and display text for standard payment transactions.

Non-Payment

Locale settings and display text for NPA transactions such as wallet provisioning or account verification.

Global Settings

In addition to channel and category settings, a template includes global settings that apply across all channels: button colours, text styles, and logos.

Language and Locales

A Challenge Interface can support multiple languages through Locales. A locale maps a BCP-47 language tag (e.g. en-GB, fr, es-MX) to a specific set of interface text. When a transaction is processed, Apata determines which locale to render based on the language configured on the card.

As many locales as needed can be created for a single interface. The language is set on the card via the Card Link response or during enrolment.

Locale Lookup Order

When Apata determines which locale to render, it follows this lookup sequence:

flowchart TD
    classDef success fill:#e6ffed,stroke:#38a169,color:#276749
    classDef process fill:#ebf8ff,stroke:#4299e1,color:#2c5282
    START([Start]) --> EXACT{"Exact locale match?<br/>e.g. en-GB = en-GB"}:::process
    EXACT -->|Yes| USE_EXACT([Use exact match]):::success
    EXACT -->|No| BCP{"Is locale in<br/>BCP-47 format?<br/>e.g. en-GB"}:::process
    BCP -->|No| USE_DEFAULT([Use default locale]):::success
    BCP -->|Yes| GENERIC{"More generic<br/>match exists?<br/>e.g. en"}:::process
    GENERIC -->|Yes| USE_GENERIC([Use generic match]):::success
    GENERIC -->|No| USE_DEFAULT2([Use default locale]):::success

The lookup never matches locales at the same level of specificity. If the card language is en-GB and only en-US exists, the system will not select en-US. It will always attempt to fall back to the generic language (en) or the default locale.

Examples

Example 1 - Exact match

Available locales: en-GB, en-US, en, Default

Card language: en-GB

Result: The en-GB locale is used. An exact match is found immediately.

Example 2 - Fallback to generic language

Available locales: en-GB, en-US, en, Default

Card language: en-IE

Result: No exact match for en-IE. The system falls back to the generic en locale.

Example 3 - Fallback to default (no generic match)

Available locales: en-GB, en-US, Default

Card language: en-IE

Result: No exact match for en-IE and no generic en locale exists. The system falls back to the Default locale.

Example 4 - Unrelated language falls back to default

Available locales: en-GB, en-US, Default

Card language: es (Spanish)

Result: en-GB and en-US are unrelated to es. The system falls back to the Default locale.

📘

Every Challenge Interface should have a Default locale configured. This acts as the final fallback when no other locale matches the card's language.

Updated 24 days ago