Definitions

Core Payment Concepts

Elements

Elements is CityPay’s client-side payment framework for securely collecting payment details and initiating payment authorisation in the browser.

Elements provides UI components, lifecycle management, and event-driven integration while ensuring sensitive card data is never exposed to merchant systems.

Elements SDK

The Elements SDK is the JavaScript library used by integrators to embed and control Elements within their applications.

The SDK can be installed as a dependency (for example via package.json in modern framework applications, often alongside a BFF), or loaded declaratively using a script tag.

Payment Intent

A Payment Intent is a persistent payment orchestration object that represents a merchant’s intent to take payment for a given amount and currency, either customer-initiated (CIT) or merchant-initiated (MIT).

A Payment Intent groups the business logic and lifecycle required to complete the payment, including payment method attachment, customer/merchant confirmation, any required authentication (for example 3DS/SCA), authorisation and capture. It may involve multiple processing attempts over time (for example after a failure or additional customer action) and can transition through several non-terminal states before reaching a final outcome.

A Payment Intent also acts as the linkage point for downstream operations and auditability, such as associating refunds with the original authorisation/capture.

Key properties of a Payment Intent:

  • Declarative: captures what the merchant intends to do (take a payment), not a single network request.
  • Stateful: progresses through defined statuses (for example open → requires_payment_method → processing → succeeded/failed, etc.).
  • Retryable: may be processed more than once until it succeeds, is cancelled, or expires (depending on rules).
  • Traceable: provides a stable reference to correlate events, attempts/transactions, and post-payment actions (such as refunds).

Transaction

A Transaction is a discrete authorisation and/or capture attempt submitted to the acquiring network, resulting in an acquirer-level outcome such as approval, decline, or failure.

Within Elements, all Transactions are created in the context of a Payment Intent, which provides the orchestration, state management, and linkage between multiple attempts, authentication steps, and downstream operations such as refunds.

Outside of Elements (for example when using Paylink or direct API integrations), Transactions may exist independently without an associated Payment Intent.

Session

A Session represents a temporary, scoped interaction between the browser, Elements, and a Payment Intent.

Sessions are used to control the lifetime, permissions, and security context of client-side payment operations.

Session Token

A Session Token is a short-lived credential used by the Elements SDK to securely associate a browser session with a specific Payment Intent.

Session Tokens are restricted in scope and duration and do not grant direct access to merchant or administrative APIs.

Tokenisation

Tokenisation is the process of securely exchanging sensitive cardholder data for a non-sensitive reference token.

This process ensures that raw card details are never exposed to merchant systems or stored outside of compliant environments.

Card Token

A Card Token is a non-sensitive reference that represents a set of card details following successful tokenisation.

Card Tokens may be single-use or reusable, depending on configuration, and can be used to initiate payments without re-entering card details.

Vaulted Card

A Vaulted Card is a Card Token that has been securely stored for future use in accordance with PCI DSS requirements.

Vaulted Cards enable repeat payments without re-collecting card details and remain under the control of CityPay’s secure vault.

Stored Credentials

Stored Credentials refer to payment credentials that have been saved and authorised for future transactions, such as recurring or merchant-initiated payments.

Stored Credentials are processed in accordance with card scheme rules and regulatory requirements, including appropriate consent and usage flags.

Integration Modes & Architecture

Direct Mode

Direct Mode is an Elements integration where payment processing is initiated and driven from the browser using a session token, without requiring the merchant backend to make an authorisation call at the time of payment.

In Direct Mode, Elements communicates securely with CityPay APIs to perform tokenisation, authentication, and authorisation, while the merchant backend remains responsible for creating the Payment Intent and issuing session tokens.

Direct Mode:

  • reduces backend complexity and latency
  • minimises PCI DSS scope for merchant systems
  • is the recommended integration model for most use cases

Proxy Mode

Proxy Mode is an Elements integration where the browser delegates certain payment actions to a merchant-controlled backend (middleware), which then communicates with CityPay APIs.

Proxy Mode is typically used when additional server-side logic, orchestration, or control is required that cannot be performed directly from the browser.

Proxy Mode:

  • introduces additional backend responsibility
  • may increase PCI and operational scope
  • is generally used for legacy, regulated, or highly customised flows

Middleware

Middleware refers to a merchant-operated backend component that sits between Elements running in the browser and CityPay APIs.

In Proxy Mode, the middleware is responsible for receiving requests from the browser, performing server-side validation or enrichment, and forwarding authorised requests to CityPay. In Direct Mode, middleware is typically limited to intent creation and session token issuance.

Backend Authorisation

Backend Authorisation is a payment flow where the merchant backend explicitly submits an authorisation request to CityPay APIs.

This approach is used in Proxy Mode and in non-Elements integrations. It provides maximum control but requires additional security, error handling, and operational considerations.

Browser Authorisation

Browser Authorisation is a payment flow where the authorisation request is initiated from the browser via Elements using a scoped session token.

Browser Authorisation is a core characteristic of Direct Mode and is designed to reduce backend complexity while maintaining strong security controls through origin binding, token scoping, and short-lived credentials.

Fallback Flow

A Fallback Flow is a secondary processing path used when a preferred integration mode cannot complete successfully.

For example, an integration may primarily use Direct Mode but fall back to Proxy Mode in specific failure scenarios, regulatory cases, or operational constraints. Fallback flows should be explicitly designed and documented to avoid ambiguous behaviour.

SDK Behaviour & Operations

Initialisation

Initialisation is the process of loading and configuring the Elements SDK for use within a browser session.

During initialisation, the SDK establishes configuration options (such as environment and debug settings), validates runtime prerequisites, and prepares internal state. Initialisation does not attach a Payment Intent or initiate any payment activity.

Initialisation must complete successfully before any other SDK operations are performed.

Attach

Attach is the operation that associates an existing Payment Intent with an Elements instance.

Attaching a Payment Intent establishes the working context for subsequent operations, including tokenisation, authentication, and authorisation. A Payment Intent must be in a state that allows attachment before this operation can succeed.

An Elements instance may only be attached to one Payment Intent at a time.

Confirm

Confirm is the operation that signals explicit intent to proceed with processing a Payment Intent.

Confirmation may be required from the customer, the merchant, or both, depending on the Payment Intent state and integration mode. Confirming an intent may result in additional steps being required, such as Strong Customer Authentication, before authorisation can occur.

Confirm does not guarantee immediate authorisation and may transition the Payment Intent into a non-terminal intermediate state.

Reset

Reset is the operation that clears the current Elements state and disassociates it from the attached Payment Intent without destroying the SDK instance.

Reset may be used to recover from errors, allow re-entry of payment details, or prepare Elements to attach to a different Payment Intent within the same browser session.

Destroy

Destroy permanently disposes of an Elements instance and releases any associated resources.

After destruction, the Elements instance cannot be reused and must be reinitialised before further operations can be performed. Destroy should be used when Elements is no longer required, such as when navigating away from a payment flow.

Event

An Event is a structured notification emitted by the Elements SDK to signal a change in state, progress, or error condition.

Events are the primary mechanism for observing and responding to payment lifecycle changes within an integration and are emitted consistently regardless of integration mode.

Event Payload

An Event Payload is the structured data associated with an emitted Event.

Event payloads include contextual information such as the Payment Intent identifier, current status, and any relevant metadata required to respond appropriately in the user interface or application logic.

3DS & Authentication

Strong Customer Authentication (SCA)

Strong Customer Authentication (SCA) is a regulatory requirement that mandates additional verification of the cardholder’s identity for certain electronic payments.

SCA typically requires the use of two or more independent authentication factors (for example something the customer knows, has, or is). Whether SCA is required for a payment depends on factors such as transaction type, value, region, and applicable exemptions.

3D Secure (3DS)

3D Secure (3DS) is a card-scheme protocol used to perform Strong Customer Authentication for card payments.

When required, 3DS enables the card issuer to authenticate the cardholder either silently (frictionless) or through an interactive challenge flow. Elements manages the orchestration of 3DS as part of the Payment Intent lifecycle.

Frictionless Flow

A Frictionless Flow is a 3DS authentication path where the issuer is able to authenticate the cardholder without requiring any direct interaction from them.

In a frictionless flow:

  • authentication is completed automatically in the background
  • no challenge UI is presented to the cardholder
  • the Payment Intent may progress directly to authorisation

Frictionless flows are preferred where possible to reduce customer friction while remaining compliant.

Challenge Flow

A Challenge Flow is a 3DS authentication path where the card issuer requires explicit interaction from the cardholder.

During a challenge flow:

  • Elements presents an issuer-controlled authentication interface (for example a one-time passcode or biometric approval)
  • the cardholder must successfully complete the challenge for processing to continue
  • failure or abandonment of the challenge may result in the Payment Intent being cancelled or failed

Authentication Challenge

An Authentication Challenge is the interactive step within a 3DS Challenge Flow where the cardholder is asked to verify their identity.

Elements is responsible for securely presenting and managing the challenge experience within the browser, while ensuring that sensitive authentication data is handled only by the issuer and card schemes.

Authentication Result

An Authentication Result is the outcome of a 3DS authentication attempt.

Possible outcomes include:

  • successful authentication
  • failed authentication
  • authentication not performed (for example due to an exemption)

The Authentication Result directly influences the next state of the Payment Intent, determining whether it may proceed to authorisation, require further action, or be terminated.

Authentication Event

An Authentication Event is an Elements SDK event emitted to signal progress or completion of a 3DS authentication step.

Authentication events allow integrators to:

  • update user interface state
  • handle success or failure outcomes
  • correlate authentication steps with the Payment Intent lifecycle

Events & Messaging

Event

An Event is a structured notification emitted by the Elements SDK to signal a change in state, progress, or an error condition during the payment lifecycle.

Events provide a consistent, asynchronous mechanism for integrators to observe and respond to changes without polling or tightly coupling logic to internal SDK behaviour.

Lifecycle Event

A Lifecycle Event is an event that represents a transition or significant milestone within the Payment Intent lifecycle.

Lifecycle events are emitted when a Payment Intent changes state (for example when moving from requires_customer_authentication to processing) and allow integrators to update application state, user interfaces, and logs accordingly.

Authentication Event

An Authentication Event is an event emitted to signal progress or completion of a customer authentication step, such as a 3DS frictionless or challenge flow.

Authentication events enable integrators to:

  • display or hide authentication-related UI
  • handle successful or failed authentication outcomes
  • coordinate authentication steps with the broader payment flow

Error Event

An Error Event is an event emitted when an error occurs during initialisation, attachment, processing, authentication, or authorisation.

Error events may represent validation errors, runtime failures, network issues, or acquirer responses and should be handled explicitly by integrators to provide appropriate user feedback and recovery options.

Event Payload

An Event Payload is the structured data delivered with an emitted event.

Event payloads typically include contextual information such as:

  • the Payment Intent identifier
  • the current or resulting Payment Intent status
  • error codes or reason details (where applicable)
  • correlation or reference identifiers

Event payloads are designed to provide sufficient information for integrators to respond without requiring additional synchronous API calls.

PostMessage

PostMessage refers to the browser messaging mechanism used by Elements to securely communicate between isolated execution contexts, such as iframes and the parent application.

Elements uses PostMessage to emit events and exchange state information while maintaining strong isolation of sensitive payment operations.

Event Listener

An Event Listener is an integrator-defined function that subscribes to and handles Events emitted by the Elements SDK.

Event listeners should be registered during initialisation and must be resilient to receiving multiple events over the lifetime of a Payment Intent, including retries and non-terminal transitions.

Event Ordering

Event Ordering describes the sequence in which events are emitted during a payment flow.

While Elements guarantees that events are emitted in a logically consistent order for a given Payment Intent, integrators should not assume synchronous execution and should always treat events as asynchronous signals.

Event Idempotency

Event Idempotency refers to the property that handling the same event more than once does not produce unintended side effects.

Integrators are encouraged to design event handlers to be idempotent, particularly when reacting to lifecycle or authentication events that may be retried or re-emitted due to network or browser conditions.

Errors & Failure Handling

Error

An Error represents a condition that prevents an operation from completing as intended.

Errors may occur during initialisation, attachment, tokenisation, authentication, authorisation, or capture. Errors are surfaced to integrators primarily through emitted Error Events and, where appropriate, returned responses.

Validation Error

A Validation Error occurs when an operation cannot proceed due to missing, invalid, or inconsistent input.

Validation errors are typically detected before any network or processing action is taken and may include issues such as:

  • invalid configuration
  • missing required parameters
  • unsupported state transitions

Validation errors must be corrected before the operation can be retried.

Runtime Error

A Runtime Error occurs during execution of an operation after validation has succeeded.

Runtime errors may result from:

  • network failures
  • timeouts
  • service unavailability
  • unexpected processing conditions

Runtime errors may be transient and, depending on context, may be retryable.

Decline

A Decline is an explicit refusal of a transaction by the card issuer or acquiring network.

Declines are not technical failures; they represent a valid processing outcome and are returned with reason codes or indicators that may inform next steps.

Soft Decline

A Soft Decline is a decline where the issuer indicates that the transaction may succeed if additional action is taken.

Common causes include:

  • required customer authentication (for example SCA)
  • temporary issuer restrictions

Soft declines typically transition the Payment Intent into a non-terminal state where further action or retry is possible.

Hard Decline

A Hard Decline is a decline where the issuer indicates that the transaction should not be retried.

Hard declines may result from:

  • invalid card details
  • insufficient funds
  • permanent account restrictions

Hard declines usually result in a failed or cancelled Payment Intent and require a different payment method to proceed.

Retryable Error

A Retryable Error is an error condition where repeating the operation may result in a successful outcome.

Retryable errors may include:

  • transient network failures
  • timeouts
  • certain runtime errors

When a retryable error occurs, the Payment Intent typically remains in, or returns to, a non-terminal state.

Non-retryable Error

A Non-retryable Error is an error condition where repeating the same operation is not expected to succeed.

Non-retryable errors may include:

  • validation errors
  • hard declines
  • terminal state transitions

These errors require corrective action or a different payment flow to continue.

Failure

Failure is a general term describing an unsuccessful outcome of a payment attempt.

A failure may result from an error, a decline, or cancellation, and should always be interpreted in the context of the associated Payment Intent state and events.

Cancellation

Cancellation occurs when a Payment Intent is explicitly terminated before successful completion.

Cancellation may be initiated by:

  • the cardholder
  • the merchant
  • the system (for example due to policy or timeout)

Cancelled Payment Intents transition to a terminal state and cannot be processed further.

Recovery

Recovery refers to the process of returning a Payment Intent to a state where processing may continue following an error or failure.

Recovery may involve:

  • re-attaching a payment method
  • re-confirming intent
  • completing required authentication
  • retrying processing where permitted

Elements is designed to support recovery flows without requiring Payment Intents to be recreated.

Security & Compliance

PCI DSS Scope

PCI DSS Scope describes the extent to which a merchant’s systems are subject to the Payment Card Industry Data Security Standard.

Elements is designed to significantly reduce a merchant’s PCI DSS scope by ensuring that sensitive cardholder data is collected and processed only within CityPay-controlled, compliant environments. Merchant systems do not receive, store, or transmit raw card data when using Elements as intended.

Elements does not remove PCI obligations entirely; merchants remain responsible for securing their own systems and complying with applicable requirements.

Reduced PCI Scope

Reduced PCI Scope refers to the practical reduction in PCI DSS requirements achieved by isolating sensitive payment operations from merchant systems.

By using Elements:

  • card data entry occurs within secure Elements components
  • tokenisation is performed before data leaves the browser
  • merchant systems interact only with non-sensitive tokens and identifiers

This typically enables merchants to qualify for a simplified PCI compliance assessment, subject to their specific integration and business model.

Domain Key

A Domain Key is a public-facing credential used to initialise Elements within a browser context.

Domain Keys are:

  • restricted to approved origins
  • used only for client-side operations
  • safe to embed in frontend applications

Domain Keys do not grant access to administrative or merchant APIs.

API Key

An API Key is a confidential credential used to authenticate server-to-server requests to CityPay APIs.

API Keys must:

  • be stored securely
  • never be exposed in client-side code
  • be rotated periodically in accordance with security best practices

API Keys are typically used to create Payment Intents, issue Session Tokens, and perform backend operations.

Session Token

A Session Token is a short-lived, scoped credential issued by a merchant backend to authorise specific client-side actions for a Payment Intent.

Session Tokens:

  • are limited in duration and scope
  • are bound to a specific Payment Intent
  • do not provide general API access

Session Tokens are a core security control in Direct Mode integrations.

Ephemeral Key

An Ephemeral Key is a temporary credential generated for limited, time-bound use within a payment flow.

Ephemeral Keys are used to minimise the risk of credential exposure by ensuring that client-side access is narrowly scoped and automatically expires.

Origin Binding

Origin Binding is the security mechanism that restricts client-side credentials (such as Domain Keys and Session Tokens) to approved web origins.

Origin Binding prevents credentials from being reused on unauthorised domains, even if they are exposed.

Content Security Policy (CSP)

Content Security Policy (CSP) is a browser security mechanism that restricts the sources from which scripts, frames, and network requests may be loaded.

When integrating Elements, merchants are required to configure CSP directives that explicitly allow Elements resources while maintaining a restrictive default policy. Proper CSP configuration helps protect against cross-site scripting and data exfiltration attacks.

Sensitive Data

Sensitive Data refers to information that must be protected from exposure, storage, or logging.

In the context of Elements, sensitive data includes:

  • primary account numbers (PAN)
  • security codes (CVV/CVC)
  • authentication data
  • full magnetic stripe data

Elements is designed so that sensitive data never enters merchant-controlled environments.

Logging & Data Handling

Logging & Data Handling refers to the practices used to record operational information while avoiding the capture of sensitive data.

Integrators must ensure that:

  • card details and authentication data are never logged
  • tokens and identifiers are treated as confidential where appropriate
  • logs are protected and retained in accordance with security and regulatory requirements

Compliance Responsibility

Compliance Responsibility defines the shared responsibility model between CityPay and the merchant.

CityPay is responsible for securing Elements and the underlying payment infrastructure. Merchants are responsible for:

  • securing their applications and backend systems
  • protecting API keys and credentials
  • implementing Elements in accordance with documentation and guidance.