---
url: /introduction.md
description: Overview of the Payment Nexus and how to use this operator guide.
---

# Introduction

Payment Nexus is the central system used to manage payment flows between internal business systems and external payment providers. It coordinates payment requests, processes responses, and ensures that transaction data remains synchronized across the organization's systems. In addition to managing these integrations, Payment Nexus provides the hosted checkout interface used to initiate and handle client payment attempts.

Because the system integrates multiple components, this guide is designed to provide the necessary context to understand how the platform operates and how to manage it effectively.

## Who This Guide Is For

This documentation is intended for employees who operate or manage the Payment Nexus as part of their daily responsibilities. This includes:

* **Operations & Finance**: Monitoring transaction flows and ensuring financial accuracy.
* **Compliance & Risk**: Reviewing activity to ensure regulatory and internal standards are met.
* **Customer Support**: Investigating payment issues to resolve client inquiries.
* **Tenant Administration**: Configuring settings and managing integrations for specific organizations.

If your role involves reviewing payment activity, managing configuration, monitoring integrations, or investigating issues, this guide is designed to support those tasks.

---

---
url: /help.md
---
# Help & Support

Use this page to identify the right team to contact when something needs attention.

## Who to contact

### User management or access issues

Contact **IT**.

This includes problems with logging in, missing permissions, role assignments, or user account management.

### Payment processing issues

Contact the **Payments Team**.

This includes problems with transactions, PSP connections, payment failures, settlement discrepancies, or anything related to the flow of money.

### Reporting or statistics issues

Contact the **BI Team**.

This includes incorrect figures, missing data in reports, or unexpected results in dashboards and exports.

### Unexpected application behaviour

Use the **Report a Bug** button in the top-right corner of the screen and fill out the form.

This is the right path for anything that looks like the application is not working as intended — error messages, broken UI, incorrect data displayed, or behaviour that does not match what is documented here.

Clicking the button opens the **Give Feedback** panel:

## Reporting issues effectively

Regardless of who you are contacting, the most useful reports follow the same structure. The goal is to give the recipient enough information to understand and reproduce the problem without needing to ask follow-up questions.

1. **What you were doing** — which page you were on and what action you took (e.g. *I opened the Users directory and clicked Export*).
2. **What you expected to happen** — the outcome you anticipated (e.g. *I expected a CSV file to download*).
3. **What actually happened** — the exact behaviour you observed (e.g. *The page showed a red error banner and nothing downloaded*).

Include any relevant identifiers — tenant names, transaction IDs, user accounts — so the recipient can look up the affected records directly.

When submitting via the **Give Feedback** panel:

**Email** — your email address so the team can follow up if they need more detail.

**Description** — use the structure above.

**Capture Screenshot** — attach an automatic screenshot of the current screen. This is especially useful for visual glitches or error messages.

---

---
url: /concepts.md
---
# Glossary of Concepts

This glossary provides definitions for the terms used throughout the Payment Nexus Operator Guide.

## Payment Entities

| Term | Definition |
| :--- | :--- |
| **Payment Intent Ticket (PIT)** | A record that tracks the lifecycle of a customer's intent to make a payment — from creation through to a final outcome. It moves through a series of statuses (see [Payment Intent Status Lifecycle](#payment-intent-status-lifecycle) below) as the payment progresses: collecting a payment method, authenticating the customer, processing with the PSP, and ultimately succeeding or being cancelled. Each PIT records the amount in the original transaction currency alongside a EUR-normalised equivalent. The PIT represents the intent; the PSP handles the underlying charge attempts directly. |
| **Checkout Intent Ticket (CIT)** | A record of a customer-facing checkout session, created when a brand's platform sends a customer to the Payment Nexus checkout flow. The CIT captures the payment amount, currency, and destination URLs for each outcome. The checkout session expires 15 minutes after the URL is opened. When the customer initiates payment, a Payment Intent Ticket is created and attached to the CIT. If the session expires before the customer acts, the CIT remains unlinked to any payment. |
| **Destination URLs** | The set of URLs configured on a Checkout Intent Ticket that determine where the customer is sent after the payment resolves. There is one destination for each outcome: Success, Failure, Pending, Cancel, and Completed. Destination on Completed acts as a fallback for Success and Failure — if the specific destination is not set, Payment Nexus redirects to Completed instead. If no applicable destination is configured, the customer stays on a result page within Payment Nexus. |
| **Tenant** | An isolated business entity within Payment Nexus — commonly referred to as a **brand** within the organisation. Tenants relate to CRM vendors the same way PSPs relate to PSP vendors: each tenant can be connected to a CRM vendor via an adapter, and multiple tenants can use the same CRM vendor. Each tenant has its own branding, domain configuration, customer records, and PSP assignments. A single Payment Nexus deployment hosts many tenants, and data is strictly separated between them. |
| **CRM Vendor** | A CRM integration — the adapter that connects Payment Nexus to a specific customer relationship management platform. The vendor defines the communication protocol used to exchange customer and payment event data. Multiple tenants can use the same CRM vendor. |
| **PSP Vendor** | A payment integration — the adapter that connects Payment Nexus to a specific type of payment processor (e.g. Praxis Nuvillon, Tylt OpenBanking, Passpoint). The vendor defines the capabilities, payment channels, and communication protocol. Multiple PSP accounts can use the same vendor. |
| **Payment Service Provider (PSP)** | A specific account with a PSP vendor — the credentials and configuration that identify a particular merchant account or API key set at that provider. Think of the vendor as "Stripe" and the PSP as "our Stripe account". A PSP is a global resource that can be assigned to multiple tenants. |
| **Tenant PSP** | The assignment of a PSP to a tenant, with the payment channels enabled for that combination. The same PSP can be assigned to different tenants with different channel configurations. |
| **Tenant Customer** | A customer record scoped to a specific brand — the hub for everything Payment Nexus knows about that customer within that brand. Identified by the brand's own customer ID, it holds encrypted PII (name, email, phone, billing and shipping addresses) and links to the customer's payment history and PSP customer accounts. Created by the brand's CRM integration; read-only in the management portal. |
| **PSP Customer Account** | A provider-issued account held on behalf of a customer — for example a virtual IBAN, a crypto wallet address, or a stored payment token. When a PSP creates an account for a customer, Payment Nexus records it and links it to both the tenant customer and the PSP. Accounts are created by the PSP integration; operators can view them but cannot create or modify them from the management portal. |
| **Payment Channel** | A specific payment method made available to customers in checkout — for example "Credit Card", "GPay", or "Deposit BTC". Each channel comes from a PSP account and carries the PSP's channel type, which determines which category it appears under (Open Banking, Credit Card / GPay / ApplePay, Crypto, or Uncategorized). Operators can customise the channel name and icon shown to customers. |
| **Channel Flow** | The checkout interaction style used by a payment channel — for example **Form** (the customer enters details inline) or **Redirect** (the customer is sent to the PSP's own page to complete payment). Determined by the PSP integration and cannot be changed by operators. The flow also affects which fields appear in the manual creation wizard's Channel Information step. |
| **Compliance Status** | A classification assigned to a tenant customer by the CRM indicating their verification or compliance level (e.g. verified, pending, restricted). PSP restrictions can be configured to allow only customers with specific compliance statuses to access a given PSP's channels. |
| **Domain** | A fully qualified domain name (FQDN) assigned to a tenant. Defines how traffic arriving at that hostname is routed into the Payment Nexus system. A tenant can have multiple domains — typically one primary production domain and one or more sandbox domains for testing. Sandbox domains additionally expose PSP integrations in the **Development / QA** release state, making them visible in checkout for testing before those integrations reach UAT. |
| **Activation** | An operator-controlled on/off switch on a whole Tenant or PSP, independent of deletion. When **disabled**, the entity is treated as if it no longer exists to the public: a disabled tenant's checkout returns Not Found and a disabled PSP is removed from every tenant's checkout, and in both cases their API credentials stop authenticating. Disabling is non-destructive and fully reversible — all records, configuration, links, and payment history are preserved and restored on re-enable. Distinct from **Release State** (which governs an *integration's* dev-qa→production pipeline) and from a **Tenant PSP** link (which enables/disables a single tenant↔PSP pairing rather than the whole entity). |

## Metrics

| Term | Definition |
| :--- | :--- |
| **Success Rate** | The percentage of Payment Intent Tickets that reached the `succeeded` status, out of all PITs in the measured scope and period. Formula: `succeeded ÷ total × 100`. Only `succeeded` counts as approved — all other statuses (cancelled, processing, requires action, etc.) count as not approved. |
| **Volume** | The total value of approved (succeeded) Payment Intent Tickets, expressed in EUR. Each PIT stores a EUR-normalised amount calculated at the time of the transaction using the exchange rate for its currency. Volume always aggregates this normalised EUR figure, not the original transaction currency. |
| **Approved Count** | The number of Payment Intent Tickets with status `succeeded` in the measured scope and period. Used in "by Count" leaderboards and daily count charts. |

## Payment Intent Status Lifecycle

A Payment Intent Ticket moves through the following statuses:

| Status | Meaning |
| :--- | :--- |
| `requires_payment_method` | Awaiting a payment method from the customer |
| `requires_confirmation` | Payment method collected, awaiting confirmation |
| `requires_action` | Additional customer action required (e.g. 3DS authentication) |
| `processing` | Submitted to the PSP, awaiting a result |
| `requires_capture` | Authorised but not yet captured |
| `succeeded` | **Approved** — payment completed successfully |
| `canceled` | Terminal non-success state — the payment did not complete |

Only `succeeded` PITs contribute to success rate and volume figures. All other statuses — including `processing`, `requires_action`, and `canceled` — count as not approved.

## Payment Intent Ticket Operations

| Term | Definition |
| :--- | :--- |
| **Disposition** | The act of manually setting the outcome of a Payment Intent Ticket that is in a non-terminal status (i.e. not yet `succeeded` or `canceled`). Used when a payment needs to be resolved without waiting for an automated PSP response — for example, to mark a payment as succeeded after confirming receipt outside the system. |
| **Disposition Override** | The act of changing the outcome of a Payment Intent Ticket that has already reached a terminal status (`succeeded` or `canceled`). Requires elevated permission and is used to correct a payment that was resolved incorrectly. |

## Administration

| Term | Definition |
| :--- | :--- |
| **Role** | A named set of permission assignments. Each capability on a role is set to Granted, Inherited, or Denied. Users can hold multiple roles; their effective permissions are the union of all roles, with Deny taking absolute precedence over Grant. |
| **Capability** | A named permission string (e.g. `tenant:read`, `payment_intent_ticket:create`) that controls access to a specific action or data within Payment Nexus. |
| **Super Admin** | A user flag that bypasses role-based access control entirely. A super admin implicitly holds every capability in the system. |
| **PSP Integration** | A versioned software adapter that connects Payment Nexus to a specific PSP vendor. Managed through the PSP Integrations module and progresses through a release pipeline (dev-qa → production) before it can be used in production tenants. |
| **CRM Integration** | A versioned software adapter that connects Payment Nexus to a specific CRM platform. Managed through the CRM Integrations module and uses the same release pipeline as PSP Integrations. |
| **Release State** | The stage of the release pipeline for a PSP or CRM integration. States progress in order: `Development / QA` → `UAT` → `Post-Update UAT` → `Production`, and can be rolled back to `Deprecated` or `Suspended`. Each integration's current state is shown as a badge on channel cards and PSP records. |

## Integration

| Term | Definition |
| :--- | :--- |
| **Access Token** | A credential issued by Payment Nexus that an external system (such as a CRM) includes with each inbound API request to prove it is authorised. Each token is scoped to a specific set of permissions and one or more whitelisted IP addresses. |
| **CRM API** | The API that Payment Nexus exposes for each brand's domain, through which the brand's CRM system integrates. The API URL for each brand also serves as the address of its interactive API documentation — the reference that should be provided to the CRM vendor during integration. The documentation includes the Webhook Event Payload schema, which the CRM vendor needs to build the endpoint that receives payment event notifications from Payment Nexus. |
| **Webhook Event Payload** | The JSON body that Payment Nexus sends to the CRM vendor's own webhook endpoint when a payment event occurs (e.g. a payment succeeded or failed). The structure is defined in the brand's API documentation. The CRM vendor team uses this schema to build the receiving endpoint on their side. |
| **Silent Authentication** | A login mechanism where the CRM generates a token via the CRM API and sends the customer directly to a pre-authenticated session, without the customer entering credentials. Used to link a CRM user to a Payment Nexus checkout session. |
| **Incoming Webhook URL** | A URL exposed by Payment Nexus that a PSP calls to report a transaction outcome (e.g. a payment confirmed or declined). Payment Nexus acknowledges the notification immediately and processes it in the background. Each PSP has two variants: a standard URL and a sparse URL for PSPs that require plain-text responses. |
| **Sparse Webhook URL** | A variant of the Incoming Webhook URL that always responds with plain text. Intended for PSPs that cannot handle structured response bodies. The response code and body text for both success and failure cases can be customised via query parameters (`eCode`, `eText`, `eError`). |
| **Reconciliation** | The process by which Payment Nexus checks back with the PSP on payments that have not yet reached a final outcome. Payment Nexus runs reconciliation on a tiered schedule — recent payments are checked frequently, older ones less so — and stops once a payment succeeds or is cancelled. If a PSP notification was missed or delayed, reconciliation ensures the payment is eventually resolved. Operators can also trigger a manual reconciliation check using the **Refresh from PSP** action on any Payment Intent Ticket. |

The Access Token value is shown only once at creation and cannot be retrieved afterwards. If a token is lost, it must be deleted and a new one created.

## Debug Tools

| Term | Definition |
| :--- | :--- |
| **HTTP Requester** | A Postman-style request builder built into Payment Nexus. Requests originate from the application server rather than the browser, making it useful for testing PSP and CRM endpoints exactly as the application would reach them. |
| **Pre-Request Script** | A JavaScript snippet configured in the HTTP Requester that runs on the server before a request is dispatched. Used to dynamically modify the request — for example, computing a time-sensitive HMAC signature and injecting it as a header. |
| **AMQP Queue** | A message queue managed by the LavinMQ broker. Payment Nexus uses queues to process background work asynchronously — inbound PSP webhooks, outbound CRM notifications, and more. The Queues page surfaces publish/consume rates, queue depth, and consumer counts in real time. |
| **Dead-Letter Queue (DLQ)** | A holding queue for messages that were rejected or could not be processed by their source queue. Every operational queue has a corresponding DLQ named `dlq.{queue-name}`. Failed messages accumulate here and can be inspected, replayed to the source queue, or permanently discarded. |
| **Backlog** | The total number of messages sitting in a queue — the sum of ready messages (waiting for a consumer) and unacknowledged messages (delivered to a consumer but not yet confirmed). A non-zero backlog means processing has fallen behind or stalled. |
| **Cron Job** | A scheduled background task that runs at a fixed interval. Payment Nexus uses a distributed scheduler backed by PostgreSQL to ensure each job runs exactly once per interval even across multiple instances. Most cron jobs are tiered reconciliation jobs that keep Payment Intent Tickets in sync with PSPs and CRMs — recent tickets are checked frequently, older ones less so. |

## Authentication & Access

| Term | Definition |
| :--- | :--- |
| **Identity Provider (IdP)** | A secure service that manages user identities and verifies who you are when you log in (e.g. Microsoft Azure AD, Okta, or Google Workspace). |
| **Single Sign-On (SSO)** | An authentication mechanism that lets you use one set of credentials to access multiple applications. |
| **Authentication** | The process of verifying the identity of a user or device. |
| **Session Expiry** | A security feature that automatically logs you out after a period of inactivity. |
| **Multi-Factor Authentication (MFA)** | A security process that requires two or more forms of identification before granting access. |

## Directory Features

| Term | Definition |
| :--- | :--- |
| **Directory** | Any list-based module page in the Payment Nexus Management UI (e.g. Tenants, Payment Intent Tickets). All directory pages share a common set of tools for searching, filtering, sorting, and acting on records. |
| **Filter Builder** | A UI panel for constructing search conditions against specific record fields. Conditions can be combined with AND or OR logic and grouped into nested condition groups. |
| **Power Search** | An advanced search mode where you type raw Lucene query syntax directly into the search field, expressing the same conditions as the filter builder in text form. |
| **Lucene** | An open-source query syntax used for full-text search and filtering. In Payment Nexus, it is the underlying format used by the Power Search feature and the filter builder. |
| **Row Action** | An operation that applies to a single record in a directory, accessible via buttons in the row or a right-click context menu (e.g. View, Edit, Approve). |
| **Bulk Action** | An operation applied to multiple records at once — either a selected subset or all records matching the current search and filters. |
| **Aggregation** | A summary statistic computed across all records matching the current search and filters — such as a sum, average, minimum, maximum, or distinct count. Displayed beneath column headers in supported directories. |
| **Auto-Refresh** | A directory feature that automatically reloads the results at a regular interval, keeping the view up to date without manual intervention. |

---

---
url: /access.md
---
# Access

The Payment Nexus management portal uses your organisation's existing identity infrastructure for login. Rather than managing a separate set of credentials, you sign in with the same account you use for everything else at your company.

## How Authentication Works

Payment Nexus uses your company's Single Sign-On (SSO) provider. When you enter your email address, the system identifies the correct identity provider (IdP) for your organisation and routes you there automatically. This means you sign in with your standard corporate credentials.

## Logging In

Follow these steps to log in:

1. **Navigate to the Portal**: Open your web browser and go to the [Payment Nexus management portal](https://nexus.nht.io/).
2. **Enter Your Email**: In the login field, enter your full company email address and click **Continue**.

3) **Complete the SSO Process**: After clicking **Continue**, a new browser window will open to handle your organization's specific authentication process.

   **Important**: While the new window is active, the main portal window will display a notification: *"A new window has been opened for you to continue the authentication process. Do not close this window while the authentication is in progress."* Please keep the original window open until the process is complete.

4. **Enter the Dashboard**: Once you have successfully authenticated in the pop-up window, you will be automatically logged in and redirected to your primary dashboard in the original browser window.

   **Note**: The authentication window will remain open after the process is complete; you may close it manually.

::: tip Troubleshooting Access
If you encounter issues while logging in, consider the following:

* **Incorrect Email Domain**: Ensure you are using your official company email. The system relies on the domain (e.g., `@company.com`) to route you to the correct login provider.
* **SSO Issues**: If you are redirected to your company's login page but cannot authenticate, please contact your internal IT help desk, as the issue likely resides with your corporate identity provider.
* **MFA Requirements**: If you encounter an error stating that you need to enable MFA (multi-factor authentication), please contact your IT department for assistance.
* **Session Expiry**: For security reasons, sessions will expire after a period of inactivity. If you are suddenly logged out, simply repeat the login process.
  :::

---

---
url: /checkout-flow.md
description: >-
  How a customer moves from a brand's platform through Payment Nexus checkout to
  a final payment outcome.
---

# The Checkout Flow

This page describes what happens when a customer initiates a payment through a brand's platform. It covers every step from the moment the brand sends the customer to checkout, through payment processing, to the final redirect back to the brand.

## Overview

Payment Nexus hosts the checkout experience. The brand's platform never handles payment details directly — it sends the customer to Payment Nexus with a pre-configured session. Payment Nexus handles the interaction with the customer and the PSP, then redirects the customer back.

The full flow involves three parties:

* **Brand Platform** — the website or app the customer is using
* **Payment Nexus** — the payment orchestration layer (checkout UI + processing)
* **Payment Service Provider (PSP)** — the payment processor that handles the actual charge

## Step 1 — The Brand Initiates a Session

Before the customer sees a checkout page, the brand's platform calls the Payment Nexus API to create a checkout session. This call includes:

* Who the customer is (their ID in the brand's system)
* How much they should pay, and in which currency
* Whether the customer is allowed to change the amount
* A set of destination URLs — where to send the customer after each possible outcome

Payment Nexus creates a **Checkout Intent Ticket (CIT)** to record the session, then responds with a time-limited checkout URL. The brand redirects the customer to that URL.

```mermaid
sequenceDiagram
    participant Brand as Brand Platform
    participant PN as Payment Nexus
    participant Customer as Customer

    Brand->>PN: Request checkout session
    Note over PN: Checkout Intent Ticket created
    PN-->>Brand: Checkout URL (15-minute session)
    Brand->>Customer: Redirect to checkout URL
```

::: tip Session expiry
The checkout URL is valid for 15 minutes from the moment it is opened. If the customer does not complete the flow within that window, the session expires. The CIT remains in Payment Nexus but is never linked to a payment.
:::

## Step 2 — The Customer at Checkout

The customer arrives at the Payment Nexus checkout page and selects a payment method. The available methods depend on which channels the brand has enabled.

Payment channels come in two types:

| Type | What the customer sees |
| :--- | :--- |
| **Form** | Payment details are entered directly on the Payment Nexus checkout page |
| **Redirect** | The customer is sent to the PSP's own payment page to complete the transaction |

When the customer confirms their payment, a **Payment Intent Ticket (PIT)** is created and linked to the CIT. The PIT records everything about the payment attempt — status, amounts, PSP references, and the final outcome.

```mermaid
sequenceDiagram
    participant Customer as Customer
    participant PN as Payment Nexus

    Customer->>PN: Open checkout page
    Customer->>PN: Select payment method and confirm
    Note over PN: Payment Intent Ticket created
```

## Step 3 — The Payment is Processed

Payment Nexus submits the payment to the PSP. What happens next depends on the PSP and the payment method:

```mermaid
flowchart TD
    A([Customer confirms payment]) --> B[Payment submitted to PSP]

    B --> C{PSP response}

    C -->|Approved| D([Payment succeeded])
    C -->|Declined| E([Payment failed])
    C -->|Pending — awaiting PSP confirmation| F[Payment Nexus waits]
    C -->|Additional authentication required| G[Customer completes 3DS / extra step]

    G -->|Authenticated| D
    G -->|Failed or abandoned| E

    F -->|PSP later confirms| D
    F -->|PSP later declines| E
```

**Requires additional authentication** — Some payment methods require the customer to complete a verification step (such as a 3D Secure challenge from their bank). Payment Nexus holds the payment in a waiting state while the customer completes that step, then resumes processing.

**Pending** — Some PSPs do not return an immediate result. Payment Nexus records the payment as pending and waits for the PSP to notify it of the outcome. Background [reconciliation jobs](/data-flow#keeping-payments-in-sync-reconciliation) also check back on pending payments at regular intervals in case a notification is missed.

## Step 4 — The Customer is Redirected

Once the payment reaches a final outcome, Payment Nexus redirects the customer to the destination URL the brand configured for that outcome. Each outcome has its own destination, but Destination on Completed acts as a fallback for success and failure if the specific one is not set. If no destination is configured at all, the customer stays on Payment Nexus:

```mermaid
flowchart LR
    A{Outcome} -->|Approved| B{Destination on Success set?}
    B -->|Yes| C[Redirect to Destination on Success]
    B -->|No| D{Destination on Completed set?}
    D -->|Yes| E[Redirect to Destination on Completed]
    D -->|No| F[Show result page on Payment Nexus]

    A -->|Declined| G{Destination on Failure set?}
    G -->|Yes| H[Redirect to Destination on Failure]
    G -->|No| I{Destination on Completed set?}
    I -->|Yes| E
    I -->|No| F

    A -->|Pending| J{Destination on Pending set?}
    J -->|Yes| K[Redirect to Destination on Pending]
    J -->|No| F

    A -->|Cancelled| L{Destination on Cancel set?}
    L -->|Yes| M[Redirect to Destination on Cancel]
    L -->|No| F
```

When no destination is configured, the customer stays on a result page within Payment Nexus showing the payment status, amount, and transaction reference, with an option to start a new payment. No error is shown.

::: tip Destination on Completed
Destination on Completed is not a separate outcome — it is a fallback used when a success or failure destination is not set. Brands use it as a catch-all landing page when they don't need to distinguish between the two outcomes.
:::

## What Operators See

From the management portal:

* The **CIT** records the checkout session — what was configured, when it was created, and whether a payment was initiated from it.
* The **PIT** records the payment attempt — its status, amounts, PSP references, and how it was resolved.
* If a payment is stuck in a non-final state, operators can use **Refresh from PSP** on the PIT to fetch the latest status from the provider, or use **Disposition** to set the outcome manually.

---

---
url: /data-flow.md
description: >-
  How information moves between the brand's CRM, Payment Nexus, and the PSP —
  and what keeps everything in sync.
---

# Data Flow & Synchronisation

Payment Nexus sits between two external systems: the brand's CRM (which manages customers and orders) and the PSP (which processes payments). This page explains how information flows between all three, and the mechanisms that keep them in sync.

## The Three Systems

```mermaid
flowchart LR
    CRM["Brand CRM\n(Customer & order data)"]
    PN["Payment Nexus\n(Orchestration layer)"]
    PSP["PSP\n(Payment processing)"]

    CRM <-->|"CRM API\n(Silent Auth, webhooks)"| PN
    PN <-->|"PSP API\n(payment submission, webhooks)"| PSP
```

* **Brand CRM** — manages the brand's customers and initiates checkout sessions
* **Payment Nexus** — coordinates the checkout, creates payment records, and keeps all parties in sync
* **PSP** — processes the payment and reports the result back

## CRM → Payment Nexus: Starting a Payment

The brand's CRM begins every payment flow by calling the Payment Nexus CRM API. This is done via [Silent Authentication](/concepts#integration) — the CRM generates a session token on behalf of the customer, without the customer needing to log in.

The CRM call includes the customer's identity, the payment amount, and the destination URLs for each outcome. Payment Nexus validates the request, creates a Checkout Intent Ticket, and returns a checkout URL that the CRM uses to redirect the customer.

## PSP → Payment Nexus: Receiving a Payment Result

When a payment is processed, the PSP sends the result to Payment Nexus via an **incoming webhook** — a notification sent to a URL that Payment Nexus exposes for each PSP.

Payment Nexus acknowledges the notification immediately and processes it in the background. This means the PSP gets a fast confirmation, and Payment Nexus handles the update without holding the PSP waiting. If processing fails for any reason, the notification is retried automatically.

Once processed, the notification updates the Payment Intent Ticket to reflect the new status (succeeded, cancelled, etc.).

```mermaid
sequenceDiagram
    participant PSP as PSP
    participant PN as Payment Nexus
    participant Q as Processing Queue

    PSP->>PN: Payment result notification
    PN-->>PSP: Acknowledged
    PN->>Q: Queue for processing
    Q->>PN: Process notification
    Note over PN: Payment Intent Ticket updated
```

## Payment Nexus → CRM: Notifying of a Payment Update

After a Payment Intent Ticket is updated, Payment Nexus notifies the brand's CRM by sending it a notification with the latest payment details.

This happens after every status change: when the payment is created, when it succeeds or fails, and when a reconciliation update occurs.

The notification includes:

* What changed (e.g. payment created, payment updated)
* The current ticket status
* The transaction amounts (both in the original currency and in EUR)
* The customer's ID in the brand's system
* The PSP transaction ID
* Checkout session details (if the payment came from a checkout session)

The CRM uses this to update its own records — for example, to mark an order as paid.

```mermaid
sequenceDiagram
    participant PN as Payment Nexus
    participant Q as Notification Queue
    participant CRM as Brand CRM

    Note over PN: Payment Intent Ticket updated
    PN->>Q: Queue CRM notification
    Q->>CRM: Send notification (event + ticket data)
    CRM-->>Q: Acknowledged
```

::: tip CRM updates can be disabled
Individual Payment Intent Tickets can be excluded from automatic CRM notifications via [Advanced Settings](/payment-intent-tickets/advanced). When disabled, the **Automatically Updates CRM** field on the ticket shows **No** in red.
:::

## Keeping Payments in Sync: Reconciliation

Not every payment resolves immediately. Some PSPs take minutes or hours to confirm a result, and occasionally a webhook is missed or fails to process. Payment Nexus uses a tiered schedule of background reconciliation jobs to check back on any payment that has not yet reached a final state.

**Reconciliation only runs on payments that have not yet reached a final state. Once a payment succeeds or is cancelled, no further checks are made.**

The reconciliation schedule is tiered by age — recent payments are checked frequently, older ones less so:

| Payment age | Check frequency |
| :--- | :--- |
| Under 5 minutes | Every minute |
| 5 – 15 minutes | Every 5 minutes |
| 15 – 30 minutes | Every 15 minutes |
| 30 – 60 minutes | Every 30 minutes |
| 1 – 3 hours | Every hour |
| 3 – 6 hours | Every 3 hours |
| 6 – 18 hours | Every 6 hours |
| 18 – 36 hours | Every 12 hours |
| 1 – 3 days | Daily |
| 3 – 21 days | Weekly |
| 21 – 90 days | Monthly |

Each reconciliation run queries the PSP for the current status of the payment, updates the ticket if anything has changed, and triggers a CRM notification if the status moved.

```mermaid
flowchart TD
    A([Reconciliation job fires]) --> B[Find non-final payments in age window]
    B --> C[Check each payment with PSP]
    C --> D{Status changed?}
    D -->|Yes| E[Update Payment Intent Ticket]
    E --> F[Notify CRM]
    D -->|No| G([Done])
    F --> G
```

::: tip Manual reconciliation
Operators can trigger a reconciliation check on demand using the **Refresh from PSP** button on any Payment Intent Ticket. This is useful when a payment appears stuck and you want to fetch the latest status immediately rather than waiting for the next scheduled run.
:::

## Full Synchronisation Picture

```mermaid
sequenceDiagram
    participant CRM as Brand CRM
    participant PN as Payment Nexus
    participant PSP as PSP

    CRM->>PN: Silent Auth — request checkout session
    PN-->>CRM: Checkout URL
    Note over PN: Checkout Intent Ticket created

    Note over CRM,PSP: Customer completes checkout (see Checkout Flow)

    PN->>PSP: Submit payment
    PSP-->>PN: Submitted

    alt PSP sends a result notification
        PSP->>PN: Payment result
        PN-->>PSP: Acknowledged
        Note over PN: Payment Intent Ticket updated
        PN->>CRM: Notify — ticket updated
    else No notification received
        Note over PN: Reconciliation job fires
        PN->>PSP: Check payment status
        PSP-->>PN: Current status
        Note over PN: Payment Intent Ticket updated
        PN->>CRM: Notify — ticket updated
    end

    CRM-->>PN: Acknowledged
```

## What Can Go Wrong

| Situation | What happens |
| :--- | :--- |
| PSP webhook is delayed or never arrives | Reconciliation jobs will eventually check back and pick up the result |
| CRM notification fails to deliver | The notification queue will retry delivery |
| Payment is stuck and reconciliation hasn't run yet | Use **Refresh from PSP** on the PIT for an immediate check |
| PSP result is ambiguous and cannot be reconciled automatically | Use **Disposition** on the PIT to manually set the outcome |

---

---
url: /globals/search.md
---
# Global Search

Global Search gives you a fast, centralized way to find anything across the Payment Nexus Management UI. Start typing and results from all modules you have access to appear immediately — no need to navigate to a specific section first.

## Opening Search

You can open the search interface in two ways:

* **Search field**: Click the search input in the top-right corner of the screen.
* **Keyboard shortcut**: Press Cmd + K (macOS) or Ctrl + K (Windows/Linux) from anywhere in the application.

## Searching for Content

Once the search interface is open, start typing the phrase or keyword you are looking for. Results appear after a short pause while you type. Only results you have permission to view are shown.

Results stay visible until you select one or clear the search field — so you can take your time reviewing them without losing your place.

To close search without navigating anywhere, press Esc.

## Using Search Results

Click a result to navigate to the relevant page.

To keep your current page open, open a result in a new tab:

* **Windows/Linux**: Ctrl + click (or right-click → Open in new tab)
* **macOS**: Cmd + click (or right-click → Open in new tab)

You can also navigate results with the keyboard:

* ↑ / ↓: Move between results
* Enter: Open the highlighted result
* Esc: Close the search dialog

### What You See in Each Result

Each result row has three parts:

* **Module icon**: A quick visual hint of which area the result belongs to
* **Result name and description**: The matching term is highlighted to show why it appeared
* **Module name** (right-aligned): The module the result comes from

The highlight may match part of a word and can appear in either the name or the description.

---

---
url: /globals/directories.md
---
# Directories

A directory is any list-based module page in the Payment Nexus management portal — Tenants, Payment Intent Tickets, and so on. Every directory shares the same set of tools for finding, viewing, and acting on records.

## Layout

A directory page is made up of three main areas:

* **Toolbar**: Contains the search field, filter/sort/column controls, bulk actions, export, and refresh.
* **Table**: Displays the records matching your current search and filters. Columns, sorting, and row actions are all managed here.
* **Pagination bar**: Shows the total record count and lets you move between pages and adjust how many records appear per page.

## In This Section

| Page | What it covers |
| --- | --- |
| [Searching & Filtering](./searching) | Search field, filter builder, saving filter state |
| [Power Search](./power-search) | Raw Lucene query syntax for advanced filtering |
| [Sorting](./sorting) | Column sorting, multi-field sort drawer |
| [Columns](./columns) | Showing, hiding, and reordering columns |
| [Results & Pagination](./results) | Page size, navigation, totals, aggregations, auto-refresh |
| [Row Actions](./row-actions) | Per-record actions, context menu, opening in new tab |
| [Bulk Actions](./bulk-actions) | Multi-record operations, bulk update form |
| [Exporting](./exporting) | Downloading records to a file |

---

---
url: /globals/directories/searching.md
---
# Searching & Filtering

Every directory has a search field and a filter builder to help you find the records you need. Whether you're investigating a specific transaction, reviewing activity for a tenant, or pulling a filtered set for a compliance check — both tools work together. Results must satisfy the search term AND any active filter conditions at the same time.

## Search Field

The search field is in the toolbar at the top of every directory. Start typing and results update automatically after a short pause. Clear the field to return to the full list.

The search field accepts plain keywords or full Lucene query syntax for precise matching. For a syntax reference, click the i icon inside the search field — it opens a cheat sheet drawer listing every supported pattern with examples. See [Power Search](./power-search) for the full guide.

## Column Header Quick Filter

For a fast single-field filter, you don't need to open the filter drawer at all. Click the filter icon on any filterable column header to open a quick filter panel for that column:

The panel has three sections:

* **Sorting** — sort the column ascending, descending, or clear the sort
* **Advanced Sorting** — open the full sort drawer for this column
* **Filter** — choose a comparison operator and enter a value, then click **Apply Filter**. Click **Clear Filter** to remove it.
* **Advanced Filtering** — jump straight to the filter builder with this column pre-selected

When a filter is active on a column, the filter icon changes to indicate it. The column filter integrates with the main filter builder — you can see and edit it there too.

## Filter Builder

For multi-field or complex conditions, open the filter builder using the **Filters** button in the toolbar. The number badge on the button shows how many conditions are currently active across all groups.

### Adding a Condition

Click **Add Rule** to add a condition row. Each condition has three parts:

1. **Property** — the field to filter on (e.g. Status, Created At, Tenant)
2. **Operator** — how to compare (see [Operators](#operators) below)
3. **Value** — what to compare against (varies by operator and field type)

### AND / OR Logic

The **Match All** / **Match Any** toggle at the top of the drawer controls how conditions in that group are combined:

* **Match All** (AND) — a record must satisfy every condition
* **Match Any** (OR) — a record must satisfy at least one condition

### Condition Groups

Click **Add Group** to create a nested group inside the current one. Each group has its own AND/OR toggle, letting you express logic like:

> Status is "failed" AND (Currency is "EUR" OR Currency is "GBP")

Groups can be nested as deeply as needed. A delete icon on each group or condition row removes it.

### Operators

Available operators depend on the field type:

| Field type | Example operators |
| --- | --- |
| Text | equals, not equals, contains, does not contain, starts with, ends with, is set, is not set, is null, in list, not in list |
| Number | equals, not equals, greater than, less than, between, not between, is set, is null, in list |
| Boolean | equals, not equals, is set, is null |
| Date / DateTime | equals, before, after, between, today, yesterday, this week, last month, this quarter, and other relative periods |

### Applying, Discarding, and Clearing Filters

* **Save** — applies the current filter and refreshes results. If any conditions are incomplete or invalid, a warning icon appears on the Save button and saving is blocked until corrected.
* **Reset to Saved** — discards unsaved changes and reverts the drawer to the last applied state.
* **Clear All** — removes all filter conditions entirely. The button only appears when filters are active.

If you close the filter drawer with unsaved changes, a confirmation dialog asks whether to **Save**, **Discard**, or **Cancel** (keep the drawer open).

## Quick Clear

When filters are active, a **clear** button appears next to the Filters button in the toolbar. Click it to remove all active filter conditions in one step without opening the filter drawer.

## Shareable Filter State

Your search query, filter conditions, AND/OR settings, and column/sort configuration are all encoded in the page URL. Bookmark a view you return to regularly, or share the URL with a colleague — they'll land on the same results, subject to their own access permissions. This is useful for handing off an investigation, flagging a specific result set in a support ticket, or sharing a filtered view in a team channel.

::: tip Power users
The search field accepts the same Lucene syntax that the filter builder uses under the hood — type conditions directly instead of building them through the UI. See [Power Search](./power-search).
:::

---

---
url: /globals/directories/power-search.md
---
# Power Search

The search field accepts full Lucene query syntax — the text-based equivalent of the filter builder. Both express the same conditions; power search lets you type them directly rather than building them through the UI. Click the i icon in the search field to open a built-in cheat sheet at any time.

## Basic Terms

A bare word matches any record where that term appears (case-insensitive):

```text
visa
```

Wrap in single or double quotes for a case-sensitive match:

```text
'Visa'
"Visa"
```

## Field-Scoped Queries

Target a specific field with `field:value`. Field names with spaces must be quoted:

```text
name:acme
'full name':acme
name.first:john
```

## Comparison Operators

Use `:=`, `:>`, `:<`, `:>=`, `:<=` for numeric and date comparisons:

```text
amount:=100
amount:>100
amount:>=100
amount:<100
amount:<=100
createdAt:=2024-01-01T00:00:00Z
createdAt:>2024-01-01T00:00:00Z
```

## Ranges

Square brackets are inclusive, curly braces are exclusive:

```text
amount:[100 TO 200]
amount:{100 TO 200}
createdAt:[2024-01-01T00:00:00Z TO 2024-12-31T23:59:59Z]
```

## Wildcards

* `*` matches any sequence of characters
* `?` matches exactly one character

```text
name:acme*
reference:TXN?001
name:foo*bar
```

## Boolean and Null Values

```text
active:true
active:false
active:null
```

## Boolean Operators

Combine terms with `AND`, `OR`, and `NOT` (must be uppercase). A space between terms is an implicit `AND`:

```text
status:active AND currency:EUR
status:failed OR status:declined
NOT status:archived
name:foo height:=100
```

## Negation Shorthand

Prefix a term or field query with `-` as a shorthand for `NOT`:

```text
-foo
-status:archived
name:foo AND NOT (status:failed OR status:declined)
```

## Grouping

Use parentheses to control precedence:

```text
(status:active OR status:pending) AND currency:USD
name:foo AND (bio:bar OR bio:baz)
```

## Examples

| Goal | Query |
| --- | --- |
| Active EUR records | `status:active AND currency:EUR` |
| Transactions over $1,000 | `amount:>1000` |
| Transactions between $100 and $500 | `amount:[100 TO 500]` |
| Tenant names starting with "acme" | `name:acme*` |
| Failed or declined in January 2024 | `(status:failed OR status:declined) AND createdAt:[2024-01-01T00:00:00Z TO 2024-01-31T23:59:59Z]` |
| Exclude archived | `-status:archived` |
| Case-sensitive exact match | `'Acme Corp'` |

---

---
url: /globals/directories/sorting.md
---
# Sorting

Directories can be sorted by one or more fields to control the order records appear in — useful when you need to find the most recent activity, surface the largest transactions, or work through records in a consistent sequence.

## Sorting from a Column Header

Click the sort button on any sortable column header to open a quick panel for that column:

The panel lets you sort the column ascending or descending, clear the sort, or jump to the full sort drawer for that column. Not all columns support sorting — the sort button only appears on sortable ones.

## Sort Drawer

For multi-field sorting, open the **Sorting** drawer from the toolbar. Here you can add multiple sort fields, set the direction for each, and control priority — records are sorted by the first field first, then by subsequent fields to break ties.

Click **Save** to apply or **Discard** to abandon changes.

## Sort State in the URL

Like filters, your sort configuration is encoded in the page URL — bookmark or share a sorted view and it will open with the same ordering applied, subject to the recipient's access permissions.

---

---
url: /globals/directories/columns.md
---
# Columns

Each directory has a default set of columns, but you can customise which fields are visible and how they're ordered to suit your workflow.

## Adding Hidden Columns

A **+** button at the far right of the table header lets you quickly add columns that aren't currently shown. Click it to see a list of available fields — select one to add it to the table immediately.

## Columns Drawer

For full control over visibility and ordering, open the **Columns** drawer from the toolbar. Each available field has a toggle — turn it on to show the column, off to hide it. Changes take effect immediately in the table behind the drawer.

The available fields are determined by the module — not every field in the system is available as a column in every directory.

## Column Order

Columns appear in the table in the order they are listed in the Columns drawer. Reorder them by dragging a field to a new position.

## Column State in the URL

Your column selection and order are encoded in the page URL alongside your filters and sort, so a bookmarked or shared link preserves the exact view you configured.

---

---
url: /globals/directories/results.md
---
# Results & Pagination

## Pagination

The pagination bar at the bottom of the table shows where you are in the full result set and lets you move between pages. Use the page controls to go forward, back, or jump to a specific page. The per-page selector controls how many records appear at once — increase it if you're scanning a large set, or reduce it for a more focused view.

The total record count for your current search and filters is shown alongside the pagination controls.

## Refreshing Data

### Manual Refresh

Click the **Refresh** button in the toolbar to reload the current page of results at any time. Useful when you know data has changed and want to see the latest state without navigating away.

### Auto-Refresh

For directories where data changes frequently — such as active transaction queues — auto-refresh keeps results current without manual intervention. Click the **play** button next to the refresh control to start it, and **pause** to stop. The refresh interval is fixed per directory.

## Aggregations

Some directories display summary statistics below certain column headers — totals, averages, minimums, maximums, or distinct counts. These apply to the full result set matching your current search and filters, not just the current page, so they stay accurate as you page through results.

Not all directories or columns support aggregations.

---

---
url: /globals/directories/row-actions.md
---
# Row Actions

Each row in a directory has one or more actions that operate on that specific record — navigating to it, editing it, or triggering a workflow step.

## Pinned Actions

The most common actions appear as icon buttons directly in the row — typically things like View, Edit, or Delete. These are always visible without any extra clicks.

## Overflow Menu

If a row has more actions than can be displayed inline, the rest are accessible through a **⋮** overflow menu at the end of the row. Click it to see the full list.

## Right-Click Context Menu

Right-clicking any row opens a context menu with the same actions available for that record, plus browser-native options:

* **Open in new tab** — navigate to the record without leaving your current view
* **Copy link** — copy the record's URL to your clipboard

## Opening a Record in a New Tab

Keeping your filtered directory view open while investigating a record is useful when working through a queue. To open a record in a new tab without losing your current view:

* **macOS**: Cmd + click the action
* **Windows/Linux**: Ctrl + click the action

Or right-click the row and choose **Open in new tab**.

## Action Availability

Some actions only appear on certain records based on their state. For example, an **Approve** action may only be available on records with a pending status. Actions that don't apply to a record are either hidden or disabled.

---

---
url: /globals/directories/bulk-actions.md
---
# Bulk Actions

Bulk actions let you run an operation against multiple records at once — useful for processing a queue, updating a batch of tenants, or acting on a filtered result set without touching each record individually.

## Selecting Records

Use the checkboxes on the left side of each row to select individual records. The checkbox in the column header selects or deselects all records on the current page.

## Running a Bulk Action

Once records are selected, the **Bulk Actions** dropdown in the toolbar becomes active. Click it to see the available actions for this directory.

## Scope Confirmation

After choosing an action, a confirmation dialog appears before anything runs.

When the result set spans multiple pages, you'll also be asked whether to apply the action to:

* **Selected records** — only the records you checked
* **All matching records** — every record matching your current search and filters, across all pages

Using filters to narrow down your result set before running a bulk action is the recommended approach — it gives you a clear, auditable scope before anything runs.

### Large Result Sets

If the number of matching records is very large, an additional warning appears before the action runs. Confirm to proceed or cancel to go back and refine your selection.

## Progress

Bulk actions run in the background. A progress dialog shows how many records have been processed, a running success and failure count, and an **Abort** button to stop early if needed.

Processing continues even if individual records fail — the dialog reports the outcome for each.

---

---
url: /globals/directories/exporting.md
---
# Exporting

Directories support downloading records to a file for use in spreadsheets, reporting tools, or offline review. This is useful when you need to share a filtered result set, hand off data to another team, or build a report outside the system.

Click the **Download** button in the toolbar to open the export drawer.

## File Name

The file name field is pre-filled with a default name based on the module. You can edit it before downloading.

## Records to Download

The drawer shows how many records will be included — all results matching your current search and filters. Apply filters before opening the drawer to narrow the export to exactly what you need.

## Options

Three checkboxes let you control the output format:

* **Include Hidden Columns** — include fields that aren't currently visible in the table
* **Use Human-Friendly Column Names** — use readable display names instead of raw field keys
* **Use Human-Friendly Data** — format values for readability (e.g. status labels instead of codes)

## Downloading

Click **Download** to generate the file. It downloads as an Excel (.xlsx) file directly to your browser's downloads folder.

---

---
url: /globals/accessibility.md
---
# Accessibility

The interface has a set of controls in the top-right corner of the application that let you personalise how it looks, sounds, and reads.

## Language

Click the **language** button to switch the interface language. Four languages are available:

* **English** (en)
* **Hebrew** (he)
* **Bulgarian** (bg)
* **Ukrainian** (uk)

Switching language takes effect immediately across the entire interface.

## Theme

The **theme toggle** switches between light and dark mode. Your preference is persisted across sessions.

## Sound Volume

The interface plays audio feedback for certain events — completed operations, notifications, and alerts. Click the **volume** button to open the volume control.

Drag the slider to adjust the volume level. Click the **speaker** button at the bottom to play a test sound and confirm your setting. Set the slider to zero to mute all audio feedback.

---

---
url: /globals/reporting.md
---
# Reporting

Payment Nexus exposes dedicated read-only endpoints so that a BI system can query the full dataset directly, without any manual exports. Both a RESTful JSON API and an OData v4 feed are available — the OData feed is the recommended integration point for tools like Power BI, which can connect to it natively and discover the schema automatically.

## Authentication

Both endpoints use HTTP Basic authentication. The credentials are configured separately from your operator login and do not grant access to any other part of the system. Contact your Payment Nexus administrator to obtain them.

## Available Data

The following entity sets are exposed across both endpoints:

| Entity | Description |
| --- | --- |
| `currency` | Supported currencies and exchange rate metadata |
| `domain` | Business domains |
| `tenant` | Merchant tenants |
| `paymentServiceProvider` | Payment service provider definitions |
| `tenantPaymentServiceProvider` | Tenant-to-PSP assignments and configuration |
| `paymentIntentTicket` | Payment transactions |
| `tenantCustomer` | Customer records associated with tenants |
| `pspCustomerAccount` | Customer accounts on the PSP side |
| `checkoutIntentTicket` | Checkout sessions |
| `user` | System users |

All endpoints are read-only. Create, update, and delete operations are not available.

## OData Feed

The OData v4 endpoint is the primary integration path. It supports all standard OData query options and allows BI tools to discover the schema from the metadata document.

**Service document:** `https://<host>/api/private/reporting`\
**Metadata:** `https://<host>/api/private/reporting/$metadata`

The metadata document is in EDMX format and describes every entity, its properties, their types, and how they relate to one another. Tools like Power BI use this automatically when you connect to an OData feed.

### Query Options

| Option | Description |
| --- | --- |
| `$filter` | Filter records (see [Filter Syntax](#filter-syntax) below) |
| `$select` | Return only specific properties |
| `$expand` | Inline related entities |
| `$orderby` | Sort results |
| `$top` | Limit the number of results |
| `$skip` | Skip a number of results (for paging) |
| `$count` | Include the total record count in the response |

### Filter Syntax

The `$filter` parameter supports the standard OData comparison and string functions:

**Comparison operators:** `eq`, `ne`, `gt`, `ge`, `lt`, `le`\
**String functions:** `contains()`, `startswith()`, `endswith()`\
**Date functions:** `year()`, `month()`, `day()`

**Examples:**

```text
/api/private/reporting/paymentIntentTicket?$filter=status eq 'failed'
/api/private/reporting/paymentIntentTicket?$filter=contains(currency,'EUR')
/api/private/reporting/tenant?$filter=createdAt ge 2024-01-01T00:00:00Z
/api/private/reporting/paymentIntentTicket?$select=id,status,amount&$top=100&$count=true
```

### Connecting from Power BI

1. In Power Query, choose **Get Data → OData Feed**
2. Enter the service document URL: `https://<host>/api/private/reporting`
3. When prompted for authentication, select **Basic** and enter the reporting credentials
4. Power BI will read the metadata and present all entity sets for selection

Once connected, you can build relationships, apply filters, and schedule refreshes from within Power BI as you would with any OData source.

## REST (JSON) API

A JSON REST API is also available at `/api/private/v1/reporting`. It exposes the same entity sets using the same Basic authentication. This is useful when integrating with systems that consume JSON but don't speak OData, or when building custom pipelines that call the API directly.

Endpoints follow standard RESTful conventions:

```text
GET /api/private/v1/reporting/paymentIntentTicket
GET /api/private/v1/reporting/paymentIntentTicket/:id
GET /api/private/v1/reporting/tenant/:id/paymentIntentTicket
```

Results are paginated. Use the `perPage` query parameter to control page size.

An OpenAPI (Swagger) document is served alongside the REST API and describes all available endpoints, parameters, and response shapes.

---

---
url: /globals/auditing.md
---
# Auditing

Payment Nexus keeps an immutable audit trail of every significant action taken in the system. Audit log entries are created automatically — they cannot be edited or deleted after the fact.

## What Gets Audited

An entry is created whenever a user (or the system itself) performs one of the following actions on a tracked record:

| Action | Description |
| --- | --- |
| `login` | A user authenticated |
| `list` | A directory was queried |
| `read` | A single record was opened |
| `create` | A new record was created |
| `update` | A record was modified |
| `delete` | A record was deleted |

Tracked models: **User**, **Tenant**, **Payment Service Provider**, **Tenant PSP**, **PSP Customer Account**, **Payment Intent**, **Tenant Customer**, **Role**.

## Viewing Audit Logs

There are two ways to access audit logs depending on what you're investigating.

### Global Audit Log

The global audit log at **Debug Tools → System Audit Log** shows every audit entry across the entire system in reverse chronological order. Each row shows the model and record ID that was acted on, who performed the action, their source IP and country, the action type, and when it happened.

Use the filters to narrow by actor, model type, record ID, action, date range, IP address, country, or session ID. This is the right view when you're investigating a specific actor's behaviour across multiple records, tracking down a suspicious login, or doing a broad compliance review.

### Record-Level Audit Tab

Every audited record has an **Audit** tab on its detail page. It shows the full history of changes to that specific record — create, update, and delete events, in order.

This is the right view when you're investigating a specific record: a tenant whose configuration changed unexpectedly, a payment that was updated, a user account that was modified.

Modules with record-level audit tabs: Tenants, Payment Service Providers, Tenant PSPs, PSP Customer Accounts, Payment Intents, Checkout Intents, Tenant Customers, Users, Roles.

## Audit Entry Detail

Click any row to open the full detail view.

### Who

The actor that performed the action — a user, a tenant, a PSP customer, or the system itself. Where you have permission to view the actor's record, their name or identifier is a link.

Also shown: source IP address (with geolocation link), country, user agent, and session ID.

### What

The model type, the record ID, and the action taken.

### Where (Changes)

For `create`, `update`, and `delete` events, the entry records exactly what changed:

* **Added** — fields that were set for the first time
* **Updated** — fields whose value changed, showing both the old and new value
* **Deleted** — fields that were removed or cleared

Changes are shown as a tree. Click any field to expand it and view the full value. Nested objects are navigable inline.

### When

The UTC timestamp of the action.

## Access Control

Viewing audit logs requires the `auditLog:monitor` permission. Users without this permission will not see the global audit log page or the audit tabs on individual records. Contact your administrator if you need access.

---

---
url: /dashboard.md
---
# The Dashboard

The dashboard is the first thing you see after logging in. It gives a live overview of system health and payment activity — useful for a quick daily check or for spotting a drop in approval rates before it becomes a support issue.

The widgets shown depend on your permissions. Users without access to a given module won't see the widgets for it. If you have no dashboard permissions at all, the dashboard shows navigation cards to the modules you do have access to instead.

## Stat Widgets

The top row shows six at-a-glance metrics. Each has a refresh button. Those marked as date-range aware also have a date picker — the value updates to reflect the selected period.

| Widget | What it shows |
| --- | --- |
| **Success Rate** | Overall payment approval rate as a percentage across the entire system for the selected period |
| **Total Tenants** | Total number of tenant records in the system — not date-range filtered |
| **Active Tenants** | Number of tenants that processed at least one payment in the selected period |
| **Total PSPs** | Total number of PSP integrations in the system — not date-range filtered |
| **Active PSPs** | Number of PSP integrations that processed at least one payment in the selected period |
| **Active PSP Vendors** | Number of distinct PSP vendor types with active traffic in the selected period |

## Top Performers

The middle section is a carousel of ranked leaderboards, showing the top five entries for each metric. Use the pagination dots to move between pages:

### PSPs

| Widget | What it shows |
| --- | --- |
| **Top PSPs by Count** | PSPs ranked by number of approved payment intents in the period |
| **Top PSPs by Volume** | PSPs ranked by total approved payment volume (EUR) in the period |
| **Top PSPs by Rate** | PSPs ranked by approval rate (%) in the period |

### PSP Vendors

| Widget | What it shows |
| --- | --- |
| **Top PSP Vendors by Count** | PSP vendor types ranked by approved payment intent count |
| **Top PSP Vendors by Volume** | PSP vendor types ranked by approved payment volume (EUR) |
| **Top PSP Vendors by Rate** | PSP vendor types ranked by approval rate (%) |

### Tenants

| Widget | What it shows |
| --- | --- |
| **Top Tenants by Count** | Tenants ranked by number of approved payment intents |
| **Top Tenants by Volume** | Tenants ranked by total approved payment volume (EUR) |
| **Top Tenants by Rate** | Tenants ranked by approval rate (%) |

## Charts

The bottom section is a carousel of time-series charts, each showing daily data across the selected date range. Use the pagination dots to move between charts. Each chart has its own date range picker and zoom controls.

### System-wide

| Chart | What it shows |
| --- | --- |
| **Daily Success Rate** | Overall payment approval rate (%) plotted by day — the quickest way to spot a system-wide decline |
| **Daily Payment Intents** | Count of approved vs non-approved payment intents per day across the whole system |
| **Daily Payment Intent Volume** | Total value (EUR) of approved vs non-approved payments per day across the whole system |

### By Tenant

| Chart | What it shows |
| --- | --- |
| **Daily Tenant Success Rate** | Approval rate (%) per day, with a separate series for each tenant — shows which tenants are driving rate changes |
| **Daily Active Tenants** | Number of tenants with payment activity each day |
| **Daily PITs by Tenant** | Approved payment intent count per day, broken out by tenant |
| **Daily Volume by Tenant** | Approved payment volume (EUR) per day, broken out by tenant |

### By PSP

| Chart | What it shows |
| --- | --- |
| **Daily PSP Success Rate** | Approval rate (%) per day, with a separate series for each PSP — shows which integrations are underperforming |
| **Daily Active PSPs** | Number of PSP integrations processing payments each day |
| **Daily PITs by PSP** | Approved payment intent count per day, broken out by PSP |
| **Daily Volume by PSP** | Approved payment volume (EUR) per day, broken out by PSP |

### By PSP Vendor

| Chart | What it shows |
| --- | --- |
| **Daily PSP Vendor Success Rate** | Approval rate (%) per day, with a separate series for each PSP vendor type |
| **Daily Active PSP Vendors** | Number of distinct PSP vendor types active each day |
| **Daily PITs by PSP Vendor** | Approved payment intent count per day, broken out by PSP vendor type |
| **Daily Volume by PSP Vendor** | Approved payment volume (EUR) per day, broken out by PSP vendor type |

---

---
url: /tenants.md
---
# The Tenants Module

A tenant — commonly referred to as a **brand** within the organisation — is an isolated business entity within Payment Nexus. Tenants relate to CRM vendors the same way PSPs relate to PSP vendors: each tenant can connect to a CRM platform through an adapter, and multiple tenants can share the same CRM vendor. Each tenant has its own branding, domain configuration, customer records, PSP assignments, client communication settings, API credentials, and outgoing webhooks. Data is strictly separated between tenants.

The Tenants module is where you manage the full lifecycle of these entities: creating new tenants, configuring their checkout experience, wiring up integrations, and monitoring their payments and customers.

## Permissions

| Action | Permission required |
| :--- | :--- |
| List tenants | `tenant:list` |
| View a tenant | `tenant:read` |
| Create a tenant | `tenant:create` |
| Edit basic details | `tenant:update:basic` |
| Edit branding | `tenant:update:branding` |
| Edit payment channels | `tenant:update:channels` |
| Edit domains | `tenant:update:domains` |
| Edit CRM adapter | `tenant:update:adapter` |
| Manage support settings | `tenant:update:support` |
| Manage API credentials | `tenant:manage:api:credentials` |
| Manage webhooks | `tenant:manage:webhooks` |
| View audit trail | `tenant:audit` |

## Directory

The tenant directory is searchable, filterable, sortable, and exportable.

| Column | Description |
| :--- | :--- |
| **ID** | Internal tenant identifier |
| **Tenant** | Brand name and visual identity |
| **CRM Vendor** | The CRM system integrated with this tenant, if any |
| **Updated At** | Timestamp of the most recent configuration change |

### Row actions

Each row has four pinned actions:

| Action | Description |
| :--- | :--- |
| **View** | Open the tenant detail page |
| **Edit** | Edit the tenant's name and description |
| **Manage Channels** | Jump directly to payment channel configuration |
| **Manage Branding** | Jump directly to branding configuration |

### Creating a tenant

Click **New** in the toolbar to create a new tenant. This opens a full creation form covering basic details, branding, and initial configuration.

---

---
url: /tenants/view.md
---
# Viewing a Tenant

The tenant detail page is the hub for everything about a specific tenant. It shows the tenant's identity at a glance and provides navigation to every configuration area.

## What is shown

The page displays a **brand cover** built from the tenant's own branding configuration — logo, colours, and theme. Below that:

| Field | Description |
| :--- | :--- |
| **Name** | The tenant's organisation name |
| **Description** | A short summary of the tenant's business or purpose |

## Navigation

The toolbar provides direct access to every tenant sub-section:

| Action | Destination |
| :--- | :--- |
| **Basics** | Edit name and description |
| **Experience** → Manage Checkout Branding | [Checkout Branding](./client-experience/branding) |
| **Experience** → Manage Payment Channels | [Payment Channels](./client-experience/channels) |
| **Experience** → Manage Checkout Domains | [Checkout Domains](./client-experience/domains) |
| **Integration** → Manage CRM Adapter Configuration | [Adapter Configuration](./integration/adapter) |
| **Integration** → Manage Inbound API Credentials | [API Credentials](./integration/api-credentials) |
| **Integration** → Manage Outbound Webhooks | [Webhook Management](./integration/webhooks) |
| **Audit Instance** | Audit trail for this specific tenant |
| **Customers** | Tenant customers linked to this tenant |
| **Payments** | Payment Intent Tickets processed under this tenant |

---

---
url: /tenants/edit.md
---
# Editing a Tenant

The basic edit page covers the tenant's core identity fields. All other configuration — branding, channels, domains, client communication, and integrations — is managed through the dedicated sub-sections accessible from the [tenant detail page](./view).

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit basic details | `tenant:update:basic` |

## Fields

| Field | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| **Name** | Text | Min 3 characters | The tenant's organisation name, displayed throughout the portal |
| **Description** | Text | Max 254 characters, optional | A short summary of the tenant's business or purpose |

Click **Save** to apply changes, or **Reset** to revert to the last saved values.

---

---
url: /tenants/client-experience/branding.md
---
# Checkout Branding

Checkout Branding controls how a brand appears to customers during the checkout process — logos, icons, brand colours, semantic theme palettes, and the copy used in the checkout UI. Changes here affect the live checkout experience for all customers under this brand.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit checkout branding | `tenant:update:branding` |

## Sections

The form is organised into six collapsible sections. Expand a section to edit its fields; collapse it to save space. A validation error indicator appears on the section header if any field within it is invalid.

### Identity

Core identity strings used in the checkout portal.

| Field | Description |
| :--- | :--- |
| **Brand Name** | The name shown to customers as the brand (e.g. in page titles and headings) |
| **Portal Name** | The name of the checkout portal itself, distinct from the brand name |
| **Portal Meta Description** | The HTML `<meta name="description">` content for the checkout portal, used by search engines and link previews |

### Logos

Full-width logotype images used in the checkout UI. A separate logo can be supplied for each visual theme so the brand's mark always looks correct against any background.

| Field | Description |
| :--- | :--- |
| **Logo for Light Theme** | SVG logo displayed when the checkout uses a light theme |
| **Logo for Neutral Theme** | SVG logo displayed when the checkout uses a neutral (mid-tone) theme |
| **Logo for Dark Theme** | SVG logo displayed when the checkout uses a dark theme |

Images are stored as Base64-encoded SVG data URIs.

### Icons

Square icon images (favicons / app icons) for each visual theme. These appear in browser tabs and as shortcut icons.

| Field | Description |
| :--- | :--- |
| **Icon for Light Theme** | Square SVG icon for light theme contexts |
| **Icon for Neutral Theme** | Square SVG icon for neutral theme contexts |
| **Icon for Dark Theme** | Square SVG icon for dark theme contexts |

### Colors

The four brand colours that seed the checkout palette. These are used directly in UI elements and as the basis for the per-theme colour overrides in the Themes section.

| Field | Description |
| :--- | :--- |
| **Brand Primary Color** | The main brand colour — used for primary buttons, links, and key UI elements |
| **Brand Secondary Color** | A supporting colour for secondary actions and accents |
| **Brand Accent Color** | A highlight colour for emphasis elements |
| **Brand Tertiary Color** | A fourth brand colour for additional visual variety |

### Themes

Fine-grained semantic colour palettes for each of the three checkout visual themes: **Light**, **Neutral**, and **Dark**. Each theme has the same set of ten colour roles.

| Field | Description |
| :--- | :--- |
| **Background** | Page background colour |
| **Surface** | Card and panel surface colour |
| **Highlight** | Interactive highlight and focus colour |
| **Info** | Informational state colour |
| **Success** | Success/confirmation state colour |
| **Notify** | Notification/alert state colour |
| **Warning** | Warning state colour |
| **Error** | Error state colour |
| **Question** | Question/prompt state colour |
| **Cancel** | Cancel/destructive action state colour |

### Copy & Text

Customisable strings used in the checkout portal UI. Each term supports macro substitution.

| Term | Macros available | Description |
| :--- | :--- | :--- |
| `app.pages.main.title` | `brandName`, `channelName` | The main page title shown in the checkout portal |
| `app.layouts.channel_selection.title` | `brandName` | The title shown on the payment channel selection screen |

Macros are written as {{macroName}} in the term value and are substituted at render time with the relevant runtime values.

::: tip
A right-hand preview panel is planned but not yet available. Save changes and open the checkout portal directly to verify how branding appears to customers.
:::

## Saving changes

Click **Save** to apply all changes across all sections, or **Reset** to revert to the last saved values. Validation runs across all sections on save — check each section header for error indicators if the save is rejected.

---

---
url: /tenants/client-experience/channels.md
---
# Payment Channels

Payment Channels is one of the most operationally critical pages in the system. It controls which payment methods are available to customers during checkout, the order they appear in, and how each is labelled and branded. Getting the channel configuration right directly affects conversion — wrong order, missing channel names, or misconfigured icons will affect every checkout session for this brand.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit payment channels | `tenant:update:channels` |

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Add** | Green | Open the channel picker to add new channels from configured PSPs |
| **Remove All** | Orange | Remove every channel from this brand in one step |
| **Refresh** | Blue | Re-fetch the latest channel and PSP data from the backend, discarding any unsaved changes |
| **Save** | Blue | Persist all staged changes — names, icons, and ordering |

::: warning
**Remove All** stages the removal of every channel at once. Until you click **Save**, no changes are committed — but if you do save, customers will see no payment options in checkout until channels are re-added and saved again. Use with care.
:::

## How channels are organised

Channels are grouped into four fixed categories, always displayed in this order:

| Category | Description |
| :--- | :--- |
| **Open Banking** | Bank transfer and open banking payment methods |
| **Credit Card / GPay / ApplePay** | Card-based and digital wallet methods |
| **Crypto** | Cryptocurrency deposit methods |
| **Uncategorized** | Channels whose PSP type is not mapped to a named category |

Each category header shows a count badge. If no channels have been added to a category, it shows an empty-state message. Channels cannot be moved between categories — the category is determined by the PSP channel type and is fixed.

## Channel card anatomy

Each channel is represented as a card. From left to right:

| Element | Description |
| :--- | :--- |
| **Drag handle** | The grip icon on the far left — drag this to reorder the channel within its category |
| **Ordinal badge** | Position within the category (1st, 2nd, 3rd…) — updates live as you reorder |
| **PSP channel name** | The payment method name as defined by the PSP (read-only) |
| **PSP account name** | The specific PSP account this channel comes from (read-only) |
| **Release state badge** | The release state of the PSP integration (e.g. Post-Update UAT, Production) |
| **PSP vendor badge** | The vendor framework for this PSP (e.g. Praxis, Rapyd, AlphaEdge) |
| **Channel Name** | Editable — the name shown to customers in checkout |
| **Light Icon** | Editable — square icon shown when checkout is in light theme |
| **Dark Icon** | Editable — square icon shown when checkout is in dark theme |
| **Up / Down buttons** | Reorder the channel one step at a time within its category |
| **Remove button** | Stage this channel for removal from the brand's checkout |

There is no per-channel enable or disable toggle — a channel is either present in the brand's channel list and visible in checkout, or it is removed from it entirely.

## Adding channels

Channels can also be added in bulk across many brands at once from the PSP side — see [Link to Tenants](../../payment-solution-providers/view#link-to-tenants) on the PSP view page. That approach adds every channel from a PSP to the selected brands in one operation; the steps below give you per-channel, per-brand control.

### Step 1 — Open the picker

Click **Add** in the toolbar. The channel picker opens showing every PSP integration configured in this environment. Each integration shows a count of currently selected channels and its release state. The right panel shows "No Channels Selected" until you make a pick.

### Step 2 — Expand an integration

Click the chevron next to an integration to expand it. This reveals the PSP accounts configured under that integration. You can expand multiple integrations at the same time to pick channels across providers in a single operation.

### Step 3 — Expand a PSP account to see channels

Click the chevron next to a PSP account to see its individual channels. Each channel shows its type badge and name. Channels that are already active on this brand are hidden — they will not appear here.

### Step 4 — Select channels

Tick the checkbox next to any channel to select it. You can select channels from multiple integrations and PSP accounts in the same session — expand as many as you need and tick across all of them before confirming. The preview panel on the right updates live as you select, showing exactly what will be added. The integration and account rows update their Selected count badges too.

Use the **Select All** / **Deselect All** buttons on an integration or account row to quickly toggle all available channels under it.

### Step 5 — Confirm

Click the green confirm button in the bottom-right corner of the dialog. The dialog closes and the new channels appear at the bottom of their respective categories, marked as unsaved. The category count badge updates immediately.

### Step 6 — Reorder and save

The newly added channels land at the bottom of their category. Drag them or use the Up button to move them into the correct position. When the order and names look right, click **Save**.

A success notification confirms the save. The channels are now live for this brand's checkout.

## Customising a channel

### Channel Name

The **Channel Name** field controls what customers see as the payment method label in checkout. It defaults to the PSP's own channel name. Clearing the field restores that default — it is not saved blank.

### Channel Icons

Each channel has two icon slots: **Light Icon** (used when checkout is in light theme) and **Dark Icon** (used when checkout is in dark theme). Icons must be square (1:1 aspect ratio). Accepted formats are any standard image type — JPG, PNG, WebP, GIF, and others — but not SVG. Non-SVG images are automatically scaled down to a maximum of 1024 × 1024 pixels before being stored.

To upload an icon, drag an image file onto the upload field or click it to open a file picker. If no icon is uploaded, checkout falls back to the PSP's default icon for that channel.

## Ordering channels

Channels within each category can be reordered two ways:

**Drag and drop** — grab the drag handle icon on the left of any card and drag it to the desired position within the same category. A ghost element shows where the card will land.

**Up / Down buttons** — click the arrow buttons on the right of each card to move it one step at a time.

The Up button is disabled on the first channel in a category; the Down button is disabled on the last. Both are disabled on a channel that is alone in its category. The ordinal badge updates immediately as positions change.

Order is per-category — each category has its own independent 1, 2, 3 sequence. The order within a category maps directly to the order customers see those options in checkout.

## Removing a channel

Click the **Remove** button on a channel card to stage it for removal. The change does not take effect until you click **Save**. If you remove a channel by mistake, click **Refresh** to reload from the last saved state.

To remove all channels from a PSP at once across multiple brands, use the **Unlink** row action or **Bulk Actions → Unlink** on the PSP's [Linked Tenants](../../payment-solution-providers/tenants) page instead.

## Saving changes

All edits — adding channels, name changes, icon uploads, reordering, and removals — are staged locally until you click **Save**. Navigating away without saving discards all pending changes.

::: tip Changes apply to new checkout sessions only
Saving immediately invalidates the server-side channel cache for this brand. New checkout sessions started after the save will always see the updated configuration. Customers who are already mid-checkout will continue to see the previous channel list for the duration of that session.

If a change does not appear in checkout straight away, ask the customer to start a new checkout session.
:::

---

---
url: /tenants/client-experience/domains.md
---
# Checkout Domains

Checkout Domains defines the hostnames from which a brand's checkout can be accessed. Each domain entry maps a fully qualified domain name to its role — production primary, sandbox, or additional — and controls which IP addresses are permitted to access sandbox domains.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Manage checkout domains | `tenant:update:domains` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal domain identifier |
| **Checkout Page** | The hostname served by the client-facing checkout UI |
| **API Hostname** | The fully qualified domain name (FQDN) configured for this entry |
| **Description** | Optional notes about the domain's purpose |
| **Primary** | Whether this is the brand's main public API domain |
| **Sandbox** | Whether this domain is for sandbox/testing use only |
| **Sandbox IP Whitelist** | IP addresses or CIDR ranges permitted to access this sandbox domain |

Created At and Updated At columns are available but hidden by default — use the column picker to show them.

## Row actions

| Action | Description |
| :--- | :--- |
| **Edit** | Update the domain's configuration |
| **Delete** | Remove the domain entry |

## Adding a domain

Click **Add Domain** to open the creation form.

| Field | Required | Description |
| :--- | :--- | :--- |
| **FQDN** | Yes | The fully qualified domain name (e.g. `checkout.example.com`) |
| **Description** | No | A note describing the domain's purpose |
| **Primary** | No | Toggle on if this is the main public API domain for this brand |
| **Sandbox** | No | Toggle on if this domain is for sandbox/testing purposes |
| **Sandbox IP Whitelist** | Conditional | Appears when Sandbox is enabled — see below |

::: warning
A domain cannot be both Primary and Sandbox. Enabling one automatically prevents the other from being set.
:::

### Sandbox IP Whitelist

When **Sandbox** is enabled the **Sandbox IP Whitelist** field appears. Enter one or more IPv4 or IPv6 addresses or CIDR ranges, separated by spaces, commas, or line breaks.

* **Empty whitelist** — no IP restriction. Any source IP can access the sandbox domain.
* **Populated whitelist** — only requests from the listed IPs or CIDR ranges are allowed through. Requests from any other IP will be blocked.

### What sandbox mode does

A sandbox domain exposes PSP integrations that are in **Development / QA** release state in addition to all other active integrations. On a non-sandbox domain those integrations are hidden from checkout entirely, so sandbox domains are the correct place to test new PSP integrations before they reach UAT.

## Editing a domain

Click the **Edit** button on any row to open the edit form. The fields are identical to the add form. Save the floppy-disk icon to apply changes.

The directory supports the standard search, filter, sort, and export controls common to all Payment Nexus directories.

---

---
url: /tenants/client-communication.md
---
# Client Communication

Client Communication settings control the ways a tenant communicates with customers during hosted checkout and related client-facing flows.

These settings are managed per tenant. Each brand can use different communication providers and credentials without affecting other tenants.

## Permissions

| Area | Permission required |
| :--- | :--- |
| Manage email settings | `tenant:update:email` |
| View customer support settings | `tenant:read:support` |
| Edit customer support settings | `tenant:update:support` |

## Available sections

| Section | What it manages |
| :--- | :--- |
| Email | Tenant email communication settings |
| [Customer Support](/tenants/client-communication/support) | Customer support or live chat provider configuration for client-facing pages |

## Customer support in checkout

When a customer support integration is configured, Payment Nexus can load the provider's widget in the hosted checkout and client portal experience. If the provider supports a custom button, operators can choose whether customers see the provider's default launcher or a Payment Nexus support button that opens the same widget.

Use the customer support settings when a brand needs customer-facing assistance during payment flows, such as live chat, help desk escalation, or guided support during checkout.

---

---
url: /tenants/client-communication/support.md
---
# Customer Support

Customer Support configures the support or live chat provider used by a tenant's hosted checkout and client-facing pages. This is a tenant-level setting: each brand can select and configure its own provider.

Use this page when a brand needs customers to access support directly from the checkout or client portal experience.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View support configuration | `tenant:read:support` |
| Test support configuration | `tenant:read:support` |
| Save support configuration | `tenant:update:support` |

## Provider selector

The provider selector lists the customer support integrations available in the current environment. The current supported provider is **LiveChat**.

Selecting a provider displays that provider's configuration fields. Removing the selected provider disconnects the tenant from its support integration after you save the change.

::: warning
Removing the support provider and saving will stop Payment Nexus from loading that provider's widget for this tenant. Customers will no longer see that support option in the hosted checkout or client portal until a provider is selected and configured again.
:::

## Configuration fields

The configuration form is defined by the selected support provider, so the fields can vary between providers.

For **LiveChat**, the configuration includes:

| Field | Required | Description |
| :--- | :--- | :--- |
| **License ID** | Yes | The LiveChat license ID for the brand's LiveChat account |
| **Custom Icon URL** | No | Optional URL for a custom icon used by the LiveChat widget |
| **Use Custom Button** | No | When enabled, Payment Nexus shows its own floating support button and opens the LiveChat widget from that button |

## Toolbar actions

| Action | Description |
| :--- | :--- |
| **Test Settings** | Checks whether the current support provider configuration is valid |
| **Reset** | Discards unsaved changes and restores the last saved values |
| **Refresh** | Reloads the saved configuration from the backend |
| **Save** | Saves the selected provider and configuration values |

## Test Settings

Use **Test Settings** before saving or relying on a new support configuration. The test validates the selected provider and its configuration values.

If no provider is selected, the test reports that there is nothing to test. If required fields are missing or invalid, the test explains which values need attention.

::: tip
Always test support settings after changing provider credentials or widget options, especially before enabling the integration for a production brand.
:::

## Checkout and client portal behavior

When support settings are saved successfully, the tenant's public configuration includes the provider information needed by the checkout and client portal.

If a support provider is configured, Payment Nexus loads the provider's widget scripts for that tenant. If the provider is missing, removed, or misconfigured, Payment Nexus skips the widget rather than blocking the checkout experience.

## Custom support button

Some support providers can be opened programmatically from a Payment Nexus button. LiveChat supports this behavior.

When **Use Custom Button** is disabled, customers see the provider's normal widget launcher according to the provider's own behavior.

When **Use Custom Button** is enabled, Payment Nexus shows a floating support button in the hosted client experience. Clicking that button opens the provider widget. This gives the brand a more consistent Payment Nexus-styled entry point while still using the provider behind the scenes.

Use the custom button when:

* The brand wants the support entry point to match the Payment Nexus checkout experience
* The provider's default launcher conflicts with checkout layout or branding
* Operators want a predictable support button location across tenants

Leave the custom button disabled when the brand prefers the provider's standard launcher or when the provider's embedded experience already matches the required presentation.

## Operational guidance

* Confirm the provider account belongs to the correct tenant before saving the License ID.
* Use a tenant-specific provider account or configuration where possible, so support conversations and reporting stay separated by brand.
* Test settings after every provider or credential change.
* After saving, open the hosted checkout or client portal for that tenant to confirm the support widget appears as expected.

---

---
url: /tenants/integration/adapter.md
---
# CRM Adapter Configuration

CRM Adapter Configuration is where you connect a brand to its back-office (CRM) platform. The same CRM integration can be used across many brands — each brand has its own separate set of credentials and settings. Because each CRM integration defines its own fields, the form on this page will look different depending on which integration is selected.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit CRM adapter configuration | `tenant:update:adapter` |

## Vendor selector

The dropdown at the top of the page lists every CRM integration available in this environment. Each option shows the integration name and its release state.

**Refresh Vendors** — the button inside the dropdown updates the list without leaving the page. Use this if a new integration has just been made available and is not appearing in the list.

**Removing the integration** — clicking the × on the selector disconnects this brand from its CRM. The form fields below disappear immediately, but the change is not applied until you click **Save**.

::: warning
Removing the integration and saving will disconnect this brand from its CRM. Customer notifications, authentication flows, and any other CRM-dependent behaviour will stop working until an integration is selected and configured again.
:::

## No integration selected

When no integration is selected the configuration area is empty. You must select an integration before you can configure, test, or save anything.

## Basic tab

The Basic tab shows the configuration form for the selected integration. The fields are defined by the integration itself, so they vary between CRM providers. Depending on the field, you may see a text input, a number input with up/down controls, a Yes/No toggle, or a dropdown. Required fields must be filled in before you can save.

**Switching integrations** — if you switch to a different integration, any values whose field names match between the old and new integration are carried over automatically. Fields that do not exist in the new integration are removed.

## Advanced tab

The Advanced tab shows the complete configuration as raw JSON. Use it when:

* A field you need to set is not visible on the Basic tab
* You want to paste in a known-good configuration from another source
* You need to find and fix a configuration error that the Basic tab is not surfacing

Whatever you edit in the Basic tab is instantly reflected in the Advanced tab, and vice versa — they show the same data in different forms. On save, the JSON is checked against the integration's rules; invalid values will be rejected with an error.

::: tip
If saving fails with a validation error and you cannot spot the problem on the Basic tab, switch to the Advanced tab and inspect the raw JSON — the problematic field is often easier to find there.
:::

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Test Settings** | Blue | Checks whether the current configuration can successfully connect to the CRM |
| **Reset** | Orange | Discards all unsaved changes and restores the last saved values |
| **Refresh** | Blue | Reloads the saved configuration from the server |
| **Save** | Blue | Saves the current integration selection and all configuration values |

## Test Settings

**Test Settings** sends the current configuration to the CRM integration and checks whether it can connect. If there are unsaved changes on the form when you click it, a prompt appears asking what to do first:

| Choice | Effect |
| :--- | :--- |
| **Yes** | Saves your changes first, then runs the test |
| **No** | Runs the test immediately against your current unsaved values — nothing is saved |
| **Cancel** | Goes back without running the test or saving anything |

All fields on the form are locked while the test is running. The test can take up to a minute.

### Test passed

A success message confirms the integration could connect and authenticate with the CRM using the configuration you provided.

### Test failed

A failure message shows what went wrong. There are two common causes:

* **Invalid configuration values** — a required field is empty, or a value is in the wrong format (for example, a field that expects a URL contains plain text). Correct the field on the Basic or Advanced tab and test again.
* **Connection or authentication failure** — the values are correctly formatted but the CRM rejected them (for example, a wrong API key or an endpoint that could not be reached). The error message will describe what the CRM reported.

::: tip
Always run **Test Settings** after changing credentials or endpoints before relying on this brand's CRM integration in production.
:::

---

---
url: /tenants/integration/api-credentials.md
---
# Inbound API Credentials

Inbound API Credentials manages the access tokens that the brand's CRM vendor uses to authenticate calls it makes *into* Payment Nexus. These are not credentials for Payment Nexus to call outward — they are credentials the CRM vendor holds and sends with each inbound request.

The page has two panels: **API URLs** on the left, and **API Access Tokens** on the right.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Manage inbound API credentials | `tenant:manage:api:credentials` |

## API URLs panel

The left panel lists every domain configured for this brand, showing the full CRM API base URL alongside a **Live** or **Sandbox** badge. Each entry is labelled **Provide to integrator as Docs & Endpoint** — this URL serves double duty: it is both the base URL for all CRM API calls and the address of the brand's interactive API documentation.

Each entry has a copy button.

### API documentation

Visiting the URL in a browser opens the brand's interactive API documentation — an OpenAPI reference generated automatically for this brand, with the correct server URL pre-filled.

![Payment Nexus CRM API documentation showing the Overview page with API base URL, security scheme, and endpoint groups in the sidebar](/screenshots/tenants-api-docs-light-pw-1370x855-1778743470000.jpg)

**Give this URL to the CRM vendor team who is integrating with this brand.** It is the single reference they need: available endpoints, authentication requirements, request and response schemas, and — critically — the **Webhook Event Payload** schema, which defines the structure of the JSON body that Payment Nexus sends to the CRM vendor's own webhook endpoint when payment events occur.

![Expanded Authentication endpoint showing the POST request parameters and response schema](/screenshots/tenants-api-docs-endpoint-light-pw-1370x855-1778743470000.jpg)

The documentation is also available in machine-readable formats for CRM vendor teams who want to generate client code or import the spec into their own tooling:

| Format | URL suffix |
| :--- | :--- |
| Interactive HTML (default) | `/api/integration/crm/` or `/api/integration/crm/swagger` |
| OpenAPI JSON | `/api/integration/crm/openapi.json` |
| OpenAPI YAML | `/api/integration/crm/openapi.yaml` |

All API calls require a bearer token in the `Authorization` header. See [API Access Tokens](#api-access-tokens-table) below for how to create and manage those tokens.

## API Access Tokens table

The right panel lists all access tokens created for this brand. Each row shows:

| Column | Description |
| :--- | :--- |
| **Name** | A label assigned at creation to identify who or what uses this token |
| **Permissions** | The actions this token is allowed to perform |
| **Whitelisted IPs** | The IP addresses or ranges from which this token may be used |
| **Expiration** | The date the token expires, or **Never** if no expiry was set |
| **Last Access** | When this token was last used to make a request |

## Toolbar actions

| Action | Description |
| :--- | :--- |
| **Refresh** | Reloads the token list from the server |
| **Add** | Opens the form to create a new access token |

## Adding a token

Click **Add** to open the creation form.

| Field | Required | Description |
| :--- | :--- | :--- |
| **Name** | Yes | A label to identify this token (minimum 3 characters) |
| **Permissions** | Yes | One or more actions to grant to this token — select from the available list |
| **Whitelisted IPs** | Yes | At least one IP address or CIDR range from which the token may be used |
| **Expiration** | No | An optional expiry date; if set, must be at least one day in the future |

::: warning
The token value is shown **once only**, immediately after creation. Copy it and store it somewhere secure before closing the dialog — it cannot be retrieved again.
:::

### After creation — copying the token

Once the token is created, a dialog appears showing the new token value. Use the **Copy** button to copy it to your clipboard. If you try to close this dialog before copying, you will be asked to confirm that you have already done so.

## Editing a token

Click the edit button on any token row to update its permissions or whitelisted IPs. The token's name and expiration date cannot be changed after creation — if either needs to change, delete the token and create a new one.

## Deleting a token

Click the delete button on any token row to remove it. A confirmation dialog shows the token name and warns that any system using the token will immediately lose access. Choose **Delete Access Token** to proceed or **Keep Access Token** to cancel.

::: warning
Deletion takes effect immediately and cannot be undone. The token value is permanently gone.
:::

---

---
url: /tenants/integration/webhooks.md
---
# Outbound Webhooks

Outbound Webhooks configures the HTTP endpoints Payment Nexus will notify when events occur on Payment Intent Tickets for this brand. Each webhook receives a signed POST request in real time as events happen.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Manage outbound webhooks | `tenant:manage:webhooks` |

## Webhook table

| Column | Description |
| :--- | :--- |
| **Description** | An optional label to help identify the webhook's purpose |
| **Webhook URL** | The HTTP/HTTPS endpoint that receives the POST request |
| **Events** | The event types this webhook is subscribed to |
| **Enabled** | Whether the webhook is currently active |
| **Pre-Shared Key** | The secret used to sign outgoing payloads (masked) |

## Row actions

| Action | Description |
| :--- | :--- |
| **Edit** | Update the webhook's configuration |
| **Test** | Send a sample payload for every subscribed event and verify the endpoint returns a 2xx response |
| **Delete** | Permanently remove the webhook |

## Adding a webhook

Click **Add** to create a new webhook.

| Field | Required | Description |
| :--- | :--- | :--- |
| **Description** | No | A brief label to identify this webhook |
| **Webhook URL** | Yes | The HTTPS endpoint that will receive event notifications |
| **Pre-Shared Key (PSK)** | Yes | A secret shared with the receiving endpoint, used to verify payload signatures |
| **Events** | Yes | One or more event types to subscribe to (see below) |
| **Enabled** | — | Toggle to activate or deactivate this webhook; defaults to enabled |

## Available events

| Event | Fires when |
| :--- | :--- |
| `payment_intent_ticket.created` | A new Payment Intent Ticket is created |
| `payment_intent_ticket.updated` | An existing Payment Intent Ticket is updated |
| `payment_intent_ticket.saved` | Any create or update occurs (fires alongside both of the above) |

## Payload and signature verification

Each delivery is a `POST` request with these headers:

| Header | Description |
| :--- | :--- |
| `X-Request-ID` | A unique UUID for this delivery |
| `X-Event` | The event type that triggered the delivery |
| `X-Timestamp` | ISO 8601 UTC timestamp of the delivery |
| `X-Signature` | A bcrypt hash for verifying authenticity |
| `User-Agent` | `Payment Nexus/{VERSION} ({ENVIRONMENT})` |

To verify a delivery, reconstruct the pre-hash string `{timestamp}|{psk}|{requestId}|{event}` using the values from the headers and your stored PSK, then verify it against `X-Signature` using bcrypt. Checking the timestamp guards against replay attacks.

The payload body contains the Payment Intent Ticket data including ID, status, amount, currency, customer reference, and checkout details. For the full schema definition, refer to the **Webhook Event Payload** schema in the brand's [API documentation](./api-credentials#api-documentation).

::: tip
Use the **Test** action after creating or editing a webhook to confirm your endpoint is reachable and responding correctly before relying on it for live events.
:::

Click **Refresh** to reload the webhook list from the backend.

---

---
url: /tenants/integration/activation.md
---
# Tenant Activation

Tenant Activation lets you enable or disable a tenant as a whole, without deleting it. Disabling is a safe, reversible "off switch" for suspending a brand while preserving all of its history.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Enable or disable a tenant | `tenant:manage:activation` |

## What disabling does

When a tenant is disabled:

* **Its checkout stops.** Public checkout requests on the tenant's domains are rejected with a *Not Found* (404) response — to the public, the storefront simply no longer exists.
* **Its API credentials stop working.** Any API request authenticated as this tenant is rejected with a *Not Found* (404) response.
* **No new payments can be processed** for it.

Existing records — the tenant itself, its configuration, its customers, and its payment history — are all preserved. Re-enabling the tenant restores it to service exactly as it was.

::: warning
Disabling a tenant takes its storefront offline for **all** of its customers. Use it to suspend a brand intentionally, not to make routine configuration changes.
:::

::: tip
The checkout block is served from a cache that refreshes about once a minute, so disabling (or re-enabling) a tenant can take up to a minute to take effect for public checkout. API credentials are rejected immediately.
:::

## Changing the activation state

The page shows a single switch reflecting the tenant's current state — **Enabled** or **Disabled**. Toggle the switch to the desired state and click **Save**.

When you disable a tenant, a confirmation dialog appears first, summarising the effect. The change is only applied after you confirm and save.

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Refresh** | Blue | Reloads the current activation state from the server |
| **Save** | Blue | Applies the selected activation state |

---

---
url: /tenants/tenant-customers.md
---
# Linked Tenant Customers

The Linked Tenant Customers page lists every customer record associated with this brand. Each row is a Tenant Customer — the identity hub that ties a customer's personal details, payment history, and PSP customer accounts together under this brand.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View linked tenant customers | `tenant_customer:read` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this tenant customer record |
| **Tenant Customer ID** | The customer identifier used by the brand's own CRM system |
| **Updated At** | When the record was last modified |

## Row actions

| Action | Description |
| :--- | :--- |
| **View** | Open the full tenant customer detail page |

Click **Refresh** to reload the list from the backend.

---

---
url: /tenants/payments.md
---
# Linked Payment Intent Tickets

The Linked Payment Intent Tickets page lists every Payment Intent Ticket associated with this brand. This is a scoped view of the global PIT directory, filtered to show only payments that belong to this brand.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View linked payments | `payment_intent_ticket:read` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this Payment Intent Ticket |
| **Amount** | The transaction amount and currency |
| **Status** | The current lifecycle status of the payment (e.g. `succeeded`, `processing`, `canceled`) |
| **Order ID** | The external order reference from the brand's system |
| **Payment Service Provider** | The PSP that handled this payment |
| **PSP Transaction ID** | The transaction identifier issued by the PSP |
| **Tenant** | The brand this payment belongs to |
| **Tenant Customer** | The customer associated with this payment |
| **Tenant Transaction ID** | The transaction reference used by the brand's CRM |
| **Created At** | When the Payment Intent Ticket was created |

## Row actions

| Action | Description |
| :--- | :--- |
| **View** | Open the full Payment Intent Ticket detail page |
| **Audit** | View the audit history for this ticket |
| **Disposition** | Manually set the outcome of this payment (only available when the ticket is in a non-terminal status) |
| **Disposition Override** | Change the outcome of a payment that has already reached a terminal status — `succeeded` or `canceled` (requires elevated permission) |
| **Edit Advanced** | Make advanced edits to the ticket (requires elevated permission) |
| **View Checkout Intent Ticket** | Navigate to the related checkout session |
| **View PSP** | Navigate to the payment service provider record |
| **View Tenant** | Navigate to the brand record |
| **View Tenant Customer** | Navigate to the associated tenant customer record |

Click **Refresh** to reload the list from the backend.

---

---
url: /payment-solution-providers.md
---
# The Payment Solution Providers Module

The Payment Solution Providers (PSP) module is where you manage the external payment processor accounts that brands use to accept payments. Each PSP record represents a specific merchant account or API credential set with a payment processor. PSPs are global resources — they are created once and then assigned to one or more brands with the channels each brand should offer.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the PSP list | `psp:read` |
| Create a new PSP | `psp:create` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal numeric identifier |
| **Name / Description** | The PSP's display name and description |
| **Tenants** | The number of brands this PSP is currently assigned to |
| **Integration** | The PSP integration vendor currently configured for this account, with its release state badge |

## Toolbar actions

| Action | Description |
| :--- | :--- |
| **New** | Opens the form to create a new PSP |
| **Audit** | Opens the audit log for all PSP records |
| **Refresh** | Reloads the list from the server |

## Creating a PSP

Click **New** in the toolbar to open the creation form.

| Field | Required | Description |
| :--- | :--- | :--- |
| **Name** | Yes | A short label identifying this PSP (minimum 3 characters) |
| **Description** | No | A longer note explaining what this account is used for |

After saving, the new PSP is created and you are taken to its view page. From there you can configure the integration adapter and restrictions.

---

---
url: /payment-solution-providers/view.md
---
# Viewing a Payment Solution Provider

The PSP view page shows a read-only summary of a single payment processor account: its identity, the customer restriction rules currently in effect, the payment channels it provides, and the webhook URLs to configure in the payment processor's dashboard.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View a PSP | `psp:read` |

## Profile cover

The cover at the top shows the PSP's numeric ID, display name, description, and the release state badge of the integration vendor currently configured for it.

## Customer Restrictions

The Customer Restrictions table shows the rules that determine which tenant customers can use this PSP's channels. There are two rules:

| Row | Description |
| :--- | :--- |
| **Qualifying Tenant Customer Compliance Statuses** | The compliance statuses a customer must have to use this PSP. Displays **All Permitted** when no statuses are configured. |
| **Qualifying Tenant Customer Countries** | The countries a customer must be from to use this PSP. Displays **All Permitted** when no countries are configured. |

When either row shows **All Permitted**, there is no restriction on that dimension — any customer can use this PSP regardless of their compliance status or country. Restrictions can be configured on the [Restrictions](./restrictions) edit page.

## Payment Channels

The Payment Channels table lists every payment method this PSP provides. Each row shows:

| Column | Description |
| :--- | :--- |
| **Channel** | The channel name as defined by this PSP |
| **Type** | The payment method category (e.g. Deposit Method, Credit Card) |
| **Channel Flow** | The user interface flow used during checkout (e.g. Form, Redirect) |
| **Currencies** | The number of currencies configured for this channel |

### Expanded channel row

Click the expand button on any row to see the per-currency limits configured for that channel:

| Column | Description |
| :--- | :--- |
| **Currency** | The currency code |
| **Min** | Minimum deposit amount in that currency, or — if no minimum is set |
| **Max** | Maximum deposit amount in that currency, or — if no maximum is set |

### Link to Tenants

The **Link to Tenants** button on an expanded row opens a dialog that lets you assign this channel to multiple brands at once. This is the fastest way to roll out a new channel across many brands — rather than visiting each brand's Channels page individually, you select all the relevant brands here and confirm in one step.

The dialog lists every brand in the system, paginated. Select the brands you want to add this channel to by ticking their checkboxes. The confirm button updates to show how many brands are selected (e.g. **Link to 5 Tenants**).

::: info
The channel is appended to the **end** of each brand's channel list. To change its position within a category, go to the brand's [Payment Channels](../tenants/client-experience/channels) page and reorder it there.
:::

## Incoming Webhook URLs

The Incoming Webhook URLs section lists the URLs you give to the payment processor so it can notify Payment Nexus of transaction outcomes. Each URL has a copy button.

There are two URL types:

### Base URL

```text
https://<host>/api/integration/psp/<id>/webhook
```

The standard endpoint. Accepts any HTTP method and any `Content-Type`. When the notification is received and successfully queued for processing, Payment Nexus returns **HTTP 201**. If the queue is unavailable it returns **HTTP 503**. The response body format depends on the `Accept` header the PSP sends:

| `Accept` header | Success body | Failure body |
| :--- | :--- | :--- |
| `application/json` (default) | `{"accepted": true}` | `{"accepted": false}` |
| `application/x-yaml` | `accepted: true` | `accepted: false` |
| `application/xml` | `<response accepted="true"/>` | `<response accepted="false"/>` |
| `text/plain` | `Accepted` | `Not Accepted` |

Processing is **asynchronous** — Payment Nexus acknowledges the notification immediately and processes it in the background. A 201 response means the notification was queued, not that the underlying payment has been updated yet.

### Sparse URL

```text
https://<host>/api/integration/psp/<id>/webhook/sparse?eCode=201&eText=ok&eError=error
```

Use this URL for PSPs that require plain-text responses rather than structured bodies. The response is always `text/plain`. Three query parameters let you control exactly what the PSP receives:

| Parameter | Default | Description |
| :--- | :--- | :--- |
| `eCode` | `201` | HTTP status code returned on success. Must be a 2xx value; any value outside 200–299 falls back to 201. |
| `eText` | `ok` | Response body text returned on success. |
| `eError` | `error` | Response body text returned on failure (HTTP 503). |

The sparse URL shown on this page already includes the default parameters — copy it as-is or adjust the values before entering it in the PSP's dashboard.

### Priority

For either URL type, the PSP can include an `X-Priority` header (integer 1–255, default 1) to influence queue processing priority for that notification.

---

---
url: /payment-solution-providers/edit.md
---
# Editing a Payment Solution Provider

The Basics edit page lets you update a PSP's display name and description. All other configuration — the integration adapter, channel settings, and customer restrictions — is managed on dedicated sub-pages accessible from the same tab bar.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit a PSP | `psp:update` |

## Fields

| Field | Required | Description |
| :--- | :--- | :--- |
| **Name** | Yes | The display name for this PSP (minimum 3 characters) |
| **Description** | No | A note explaining what this account is used for |

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Reset** | Orange | Discards all unsaved changes and restores the last saved values |
| **Refresh** | Blue | Reloads the saved values from the server |
| **Save** | Blue | Saves the current name and description |

---

---
url: /payment-solution-providers/adapter.md
---
# PSP Adapter Configuration

PSP Adapter Configuration is where you connect a PSP account to its payment processor integration. The integration defines the communication protocol, available channels, and configuration fields specific to that processor. Because each integration defines its own fields, the form will look different depending on which integration is selected.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit PSP adapter configuration | `psp:update:integration` |

## Vendor selector

The dropdown at the top of the page lists every PSP integration available in this environment. Each option shows the integration name and its release state.

**Refresh Vendors** — the button inside the dropdown updates the list without leaving the page. Use this if a new integration has just been made available and is not appearing in the list.

**Removing the integration** — clicking the × on the selector disconnects this PSP account from its integration. The form fields below disappear immediately, but the change is not applied until you click **Save**.

::: warning
Removing the integration and saving will disconnect this PSP account from its payment processor. Any brands using this PSP will lose access to its payment channels until an integration is selected and configured again.
:::

## No integration selected

When no integration is selected the configuration area is empty. You must select an integration before you can configure, test, or save anything.

## Basic tab

The Basic tab shows the configuration form for the selected integration. The fields are defined by the integration itself, so they vary between processors. Depending on the field, you may see a text input, a number input, a Yes/No toggle, a dropdown, a JSON editor, or an icon uploader.

**PSP-specific field types:**

| Field type | Description |
| :--- | :--- |
| **Icon (Light)** | An image uploader for the channel icon shown in light-themed checkout pages |
| **Icon (Dark)** | An image uploader for the channel icon shown in dark-themed checkout pages |
| **Currencies** | A JSON editor for defining per-currency limits (minimum and maximum deposit amounts) |

**Switching integrations** — if you switch to a different integration, any values whose field names match between the old and new integration are carried over automatically. Fields that do not exist in the new integration are removed.

## Advanced tab

The Advanced tab shows the complete configuration as raw JSON. Use it when:

* A field you need to set is not visible on the Basic tab
* You want to paste in a known-good configuration from another source
* You need to find and fix a configuration error that the Basic tab is not surfacing

Whatever you edit in the Basic tab is instantly reflected in the Advanced tab, and vice versa — they show the same data in different forms. On save, the JSON is checked against the integration's rules; invalid values will be rejected with an error.

::: tip
If saving fails with a validation error and you cannot spot the problem on the Basic tab, switch to the Advanced tab and inspect the raw JSON — the problematic field is often easier to find there.
:::

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Test Settings** | Blue | Checks whether the current configuration can successfully connect to the payment processor |
| **Reset** | Orange | Discards all unsaved changes and restores the last saved values |
| **Refresh** | Blue | Reloads the saved configuration from the server |
| **Save** | Blue | Saves the current integration selection and all configuration values |

## Test Settings

**Test Settings** sends the current configuration to the PSP integration and checks whether it can connect. If there are unsaved changes on the form when you click it, a prompt appears asking what to do first:

| Choice | Effect |
| :--- | :--- |
| **Yes** | Saves your changes first, then runs the test |
| **No** | Runs the test immediately against your current unsaved values — nothing is saved |
| **Cancel** | Goes back without running the test or saving anything |

All fields on the form are locked while the test is running. The test can take up to a minute.

### Test passed

When the test succeeds, the Test Settings button turns green to confirm the integration could connect and authenticate with the payment processor using the configuration provided.

### Test failed

A failure dialog shows what went wrong. There are two common causes:

* **Invalid configuration values** — a required field is empty, or a value is in the wrong format. Correct the field on the Basic or Advanced tab and test again.
* **Connection or authentication failure** — the values are correctly formatted but the payment processor rejected them (for example, a wrong API key or an unreachable endpoint). The error message will describe what the processor reported.

::: tip
Always run **Test Settings** after changing credentials or endpoints before relying on this PSP in production.
:::

---

---
url: /payment-solution-providers/restrictions.md
---
# PSP Restrictions

PSP Restrictions let you limit which tenant customers can use a PSP's payment channels. Two independent filters are available: compliance status and country. Either filter can be left empty, which means no restriction applies for that dimension.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit PSP restrictions | `psp:update:restrictions` |

## Fields

| Field | Description |
| :--- | :--- |
| **Accepted Client Compliance Statuses** | When one or more statuses are selected, only tenant customers whose compliance status matches will be offered this PSP's channels at checkout. Leave empty to allow customers of any compliance status. |
| **Accepted Client Countries** | When one or more countries are selected, only tenant customers whose country matches will be offered this PSP's channels at checkout. Leave empty to allow customers from any country. |

Both fields are multi-select dropdowns. Use **Select All** to pick every available option at once, or **Select None** to clear the field.

::: tip
An empty field means **All Permitted** — every customer qualifies on that dimension. You only need to add values when you want to *restrict* access, not to grant it.
:::

### Selecting values

Clicking a field opens a list of all available values. Tick any item to add it to the active restriction. The same picker is used for both compliance statuses and countries.

### Configured state

Selected values appear as chips inside the field. Click the × on any chip to remove that value individually, or use **Select None** to clear the field entirely.

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Refresh** | Blue | Reloads the saved restrictions from the server |
| **Save** | Blue | Saves the current restriction settings |

---

---
url: /payment-solution-providers/activation.md
---
# PSP Activation

PSP Activation lets you enable or disable a Payment Solution Provider as a whole, without deleting it. Disabling is a safe, reversible "off switch" for taking a misbehaving or retired PSP out of service while preserving all of its history.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Enable or disable a PSP | `psp:update:activation` |

## What disabling does

When a PSP is disabled, the following happen immediately:

* **It disappears from checkout.** The PSP's channels are removed from the configuration served to every tenant that uses it, so customers can no longer select them.
* **Its API credentials stop working.** Any API request authenticated as this PSP is rejected with a *Not Found* (404) response.
* **No new payments can be processed** through it.

Existing records — the PSP itself, its configuration, its links to tenants, and its payment history — are all preserved. Re-enabling the PSP restores it to service exactly as it was.

::: warning
Disabling a PSP affects **every** tenant linked to it, not just one. If you only want to stop a single tenant from using this PSP, unlink that tenant on the [Linked Tenants](/payment-solution-providers/tenants) page instead.
:::

## Changing the activation state

The page shows a single switch reflecting the PSP's current state — **Enabled** or **Disabled**. Toggle the switch to the desired state and click **Save**.

When you disable a PSP, a confirmation dialog appears first, summarising the effect. The change is only applied after you confirm and save.

## Toolbar actions

| Action | Color | Description |
| :--- | :--- | :--- |
| **Refresh** | Blue | Reloads the current activation state from the server |
| **Save** | Blue | Applies the selected activation state |

---

---
url: /payment-solution-providers/tenants.md
---
# Linked Tenants

The Linked Tenants page lists every brand that has been assigned this PSP. Removing a brand from this list unlinks the PSP from that brand, which disables all payment channels sourced from this PSP for that brand's customers.

A PSP can also be linked to or unlinked from a brand on the brand's own [Payment Channels](../tenants/client-experience/channels) page, which provides per-channel control rather than linking or unlinking the entire PSP at once.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View linked tenants | `tenant:read` |
| Unlink a tenant | `tenant:update:channels` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for the brand |
| **Tenant** | The brand name |
| **CRM Vendor** | The CRM integration vendor connected to this brand |
| **Updated At** | When the brand record was last modified |

## Row actions

Click the **⋯** icon on any row to open its action menu.

| Action | Description |
| :--- | :--- |
| **View** | Open the brand detail page |
| **Manage Payment Channels** | Go directly to the brand's Payment Channels page to configure available checkout methods |
| **Manage Checkout Branding** | Go directly to the brand's Branding page to configure colors, themes, and logos |
| **Experience** | Go to the brand's client experience settings |
| **Comms** | Go to the brand's client communication settings |
| **Integration** | Go to the brand's integration configuration |
| **Customers** | View the brand's tenant customers |
| **Payments** | View the brand's payment intent tickets |
| **Reset Channel Overrides** | Restore channel names and icons for this brand to the PSP-level defaults |
| **Unlink** | Remove this PSP from the brand, disabling all its payment channels for that brand |

## Bulk actions

Click the chevron next to **Bulk Actions** to open the bulk action menu. Bulk actions apply to all records matching the current search and filters.

| Action | Description |
| :--- | :--- |
| **Reset Channel Overrides** | Restore channel names and icons to the PSP-level defaults for all matching brands |
| **Unlink** | Remove this PSP from all matching brands at once |

### Bulk Unlink

Selecting **Unlink** from the bulk actions menu opens a confirmation dialog showing how many records will be affected. Click **Yes** to proceed.

The result is reported per brand — each brand shows as successfully unlinked, failed, or undetermined.

## Adding a linked tenant

Click **Add** to open the [Link to Tenants](./view#link-to-tenants) dialog, which lets you assign this PSP to one or more brands in a single operation.

Click **Refresh** to reload the list from the backend.

---

---
url: /payment-solution-providers/payments.md
---
# Linked Payment Intent Tickets

The Linked Payment Intent Tickets page lists every Payment Intent Ticket that was processed through this PSP. This is a scoped view of the global PIT directory, filtered to this PSP.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View linked payments | `payment_intent_ticket:read` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this Payment Intent Ticket |
| **Amount** | The transaction amount and currency |
| **Status** | The current lifecycle status of the payment (e.g. `succeeded`, `processing`, `canceled`) |
| **Order ID** | The external order reference from the brand's system |
| **Payment Service Provider** | The PSP that handled this payment |
| **PSP Transaction ID** | The transaction identifier issued by the PSP |
| **Tenant** | The brand this payment belongs to |
| **Tenant Customer** | The customer associated with this payment |
| **Tenant Transaction ID** | The transaction reference used by the brand's CRM |
| **Created At** | When the Payment Intent Ticket was created |

## Row actions

| Action | Description |
| :--- | :--- |
| **View** | Open the full Payment Intent Ticket detail page |
| **Audit** | View the audit history for this ticket |
| **Disposition** | Manually set the outcome of this payment (only available when the ticket is in a non-terminal status) |
| **Disposition Override** | Change the outcome of a payment that has already reached a terminal status — `succeeded` or `canceled` (requires elevated permission) |
| **Edit Advanced** | Make advanced edits to the ticket (requires elevated permission) |
| **View Checkout Intent Ticket** | Navigate to the related checkout session |
| **View PSP** | Navigate to the payment service provider record |
| **View Tenant** | Navigate to the brand record |
| **View Tenant Customer** | Navigate to the associated tenant customer record |

Click **Refresh** to reload the list from the backend.

---

---
url: /payment-solution-providers/customers.md
---
# Linked PSP Customer Accounts

The Linked PSP Customer Accounts page lists every PSP Customer Account registered under this PSP. A PSP Customer Account is a persistent account identifier — such as a virtual IBAN or crypto wallet address — issued by the PSP on behalf of a customer and stored in Payment Nexus for reuse in future payment sessions.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View linked PSP customer accounts | `payment_intent_ticket:read` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this PSP Customer Account |
| **Related Payment Service Provider** | The PSP that issued this account |
| **Related Tenant Customer** | The tenant customer this account belongs to |
| **Account Type** | The type of account (e.g. Virtual IBAN, Crypto Wallet) |
| **Account Identifier** | The account reference or address issued by the PSP |
| **External Reference ID** | A secondary reference identifier from the PSP |
| **Related Currency** | The currency this account is denominated in |
| **Label** | An optional label for this account |
| **Description** | An optional description for this account |
| **Status** | The current status of the account |

## Row actions

| Action | Description |
| :--- | :--- |
| **View** | Open the full PSP Customer Account detail page |

Click **Refresh** to reload the list from the backend.

---

---
url: /payment-intent-tickets.md
---
# The Payment Intent Tickets Module

A Payment Intent Ticket (PIT) is a record that tracks the lifecycle of a customer's intent to make a payment — from creation through to a final outcome. Each PIT moves through a series of statuses as the payment progresses: collecting a payment method, authenticating the customer, processing with the PSP, and ultimately succeeding or being cancelled.

The Payment Intent Tickets module provides a full directory of these records with tools for searching, filtering, creating, and resolving payments.

## Permissions

| Action | Permission required |
| :--- | :--- |
| List tickets | `payment_intent_ticket:list` |
| View a ticket | `payment_intent_ticket:read` |
| Create a ticket | `payment_intent_ticket:create` |
| Disposition a ticket | `payment_intent_ticket:disposition` |
| Override disposition | `payment_intent_ticket:disposition:override` |
| Advanced edit | `payment_intent_ticket:update:advanced` |
| View audit trail | `payment_intent_ticket:audit` |

## Directory

The PIT directory is searchable, filterable, sortable, and exportable. It supports all standard directory features including the filter builder, power search, bulk actions, and column customisation. See the [Directories](/globals/directories/) section for full details on these shared capabilities.

### Default columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal Payment Nexus identifier for this PIT |
| **Amount** | The transaction amount and currency |
| **Status** | The current lifecycle status (see [Status Lifecycle](/concepts#payment-intent-status-lifecycle)) |
| **Order ID** | The external order reference from the brand's system |
| **PSP** | The payment service provider handling this payment |
| **PSP Transaction ID** | The transaction identifier issued by the PSP |
| **Tenant** | The brand this payment belongs to |
| **Tenant Customer** | The customer associated with this payment |
| **Tenant Transaction ID** | The transaction reference used by the brand's CRM |
| **Created At** | When the PIT was created |

### Row actions

Each row has four pinned actions plus additional items in an overflow menu.

**Pinned actions:**

| Action | Description |
| :--- | :--- |
| **View** | Open the full PIT detail page |
| **Audit** | View the audit history for this ticket |

The third pinned action depends on the ticket's status:

* **Disposition** — shown when the ticket is in a non-terminal status. Opens the disposition form to manually set the outcome.
* **Override Disposition** — shown when the ticket has reached a terminal status (`succeeded` or `canceled`). Opens the override form to change the outcome.

**Overflow menu:**

| Action | Description |
| :--- | :--- |
| **Edit Advanced** | Modify the advanced settings for this ticket |
| **View Checkout Intent Ticket** | Navigate to the related checkout session |
| **View PSP** | Navigate to the payment service provider record |
| **View Tenant** | Navigate to the brand record |
| **View Tenant Customer** | Navigate to the associated customer record |

## Viewing a PIT

Clicking **View** on any row opens the PIT detail page. It shows the full transaction record across four sections — Payment Intent Basics, PSP Transaction Details, CRM Transaction Details, and Transaction Processing Details — together with a toolbar for all available actions.

See [Viewing a Payment Intent Ticket](/payment-intent-tickets/view) for a full breakdown of every field and action.

---

---
url: /payment-intent-tickets/view.md
---
# Viewing a Payment Intent Ticket

The PIT detail page shows everything Payment Nexus knows about a payment in one place. It is split into four sections plus a toolbar of available actions.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View a ticket | `payment_intent_ticket:read` |
| View PSP transaction data | `payment_intent_ticket:read:psp` |
| View CRM transaction data | `payment_intent_ticket:read:crm` |
| Download proof of payment | `payment_intent_ticket:read:pii` |

## Detail Toolbar

The toolbar runs across the top of the detail page. The actions shown depend on the ticket's current status and your permissions.

**Primary actions:**

| Action | When shown | Description |
| :--- | :--- | :--- |
| **View** | Always | The default read-only detail view. |
| **Disposition** | Ticket has not yet reached a final status | Manually set the outcome of the payment. See [Dispositioning](/payment-intent-tickets/dispositioning). |
| **Override Disposition** | Ticket is `succeeded` or `canceled` | Change the outcome of a ticket that has already been resolved. See [Dispositioning](/payment-intent-tickets/dispositioning). |
| **Advanced** | Always | Edit the advanced settings for this ticket. See [Advanced Settings](/payment-intent-tickets/advanced). |
| **Audit** | Always | View the full audit log of changes to this ticket. |
| **Refresh from PSP** | When the PSP supports it | Re-fetches the latest transaction state from the PSP and updates the ticket. Requires a confirmation step. |

::: tip Disposition vs Override Disposition
Only one of these is ever shown at a time — which one depends on whether the ticket has already been resolved.
:::

**Navigation links** (shown in a secondary group, or in a **More** overflow menu depending on screen width):

| Link | When shown | Navigates to |
| :--- | :--- | :--- |
| **Checkout Intent Ticket** | Only when the PIT was created from a checkout session | The checkout session that initiated this payment |
| **Payment Service Provider** | Always | The PSP record |
| **Tenant** | Always | The brand record |
| **Tenant Customer** | Always | The customer record associated with this payment |

## Payment Intent Basics

The **Payment Intent Basics** section shows the core details of the ticket.

| Field | Description |
| :--- | :--- |
| **Payment Intent Ticket ID** | The internal Payment Nexus identifier for this PIT. Copyable. |
| **Payer** | The tenant customer who initiated this payment, shown as `Name (ID)`. Copyable. |
| **Transaction Amount** | The amount and currency as originally submitted to the PSP — the amount in the customer's transaction currency. Copyable. |
| **System Transaction Amount** | The EUR equivalent of the transaction amount, converted at the exchange rate in effect when the payment was recorded. Always shown in EUR. This is the figure used in all volume and success rate metrics. Copyable. |
| **Order ID** | The order reference from the brand's system. Copyable when present. |
| **PSP Transaction ID** | The transaction identifier issued by the PSP. This is the primary reference for looking up the transaction at the provider. Copyable when present. |
| **CRM Transaction ID** | The transaction reference used by the brand's CRM system. Copyable when present. |
| **Created** | When the PIT was first created. |
| **Updated** | When the PIT was last modified. |
| **Status** | The current lifecycle status, shown as a coloured chip. See [Payment Intent Status Lifecycle](/concepts#payment-intent-status-lifecycle) for the full list of statuses and what they mean. |
| **Automatically Updates CRM** | Whether Payment Nexus will automatically notify the brand's CRM when this ticket's status changes. Shows **Yes** (green) by default. Shows **No** (red) when the ticket has been excluded via [Advanced Settings](/payment-intent-tickets/advanced). |

## PSP Transaction Details

The **PSP Transaction Details** section shows the data received from the payment service provider about this transaction.

| Field | Description |
| :--- | :--- |
| **PSP** | The PSP that processed this payment. Click the card to navigate to the PSP record. |
| **Transaction ID** | The PSP's own transaction identifier — same value as **PSP Transaction ID** in the basics section. Copyable when present. |
| **Transaction Info** | Opens the data the PSP sent for this transaction (**View Raw Data**). Requires `payment_intent_ticket:read:psp`; the button is disabled if no data has been received. |
| **Transaction Meta** | Opens supplementary data from the PSP (**View Raw Data**). Requires `payment_intent_ticket:read:psp`; the button is disabled if no data has been received. |

**Download Proof of Payment** appears at the top of this section for wire transfer payments that have an uploaded evidence file attached. Requires `payment_intent_ticket:read:pii`.

::: warning Evidence files are not scanned for viruses or malware
Exercise caution when opening downloaded evidence files. If you are unsure about safe handling procedures, consult your IT department before proceeding.
:::

## CRM Transaction Details

The **CRM Transaction Details** section shows the data exchanged with the brand's CRM about this payment.

| Field | Description |
| :--- | :--- |
| **Tenant** | The brand this payment belongs to. Click the card to navigate to the brand record. |
| **Tenant Customer** | The customer associated with this payment, shown as `Name (ID)`. Copyable when present. |
| **Transaction ID** | The CRM's own transaction reference — same value as **CRM Transaction ID** in the basics section. Copyable when present. |
| **Transaction Info** | Opens the data the CRM sent for this transaction (**View Raw Data**). Requires `payment_intent_ticket:read:crm`; the button is disabled if no data has been received. |
| **Transaction Meta** | Opens supplementary data received from the CRM (**View Raw Data**). Requires `payment_intent_ticket:read:crm`; the button is disabled if no data has been received. |

## Transaction Processing Details

The **Transaction Processing Details** section shows identifiers from the PSP's processing of this payment. These fields are most useful when investigating a declined payment or working with the PSP to trace a specific transaction. Fields with data are copyable.

::: tip Field availability depends on the PSP
Not all PSPs provide all of these fields — some return a full set, others return only a subset or none at all. Empty fields simply mean the PSP did not supply that data for this transaction.
:::

| Field | Description |
| :--- | :--- |
| **Last PSP Internal Transaction ID** | The PSP's internal reference for the final payment attempt. Distinct from the main PSP Transaction ID — use this when the PSP asks for an internal tracking reference. |
| **Last PSP Subprocessor ID** | The identifier of the underlying processor the PSP routed this payment through, if applicable. |
| **Last PSP Subprocessor Name** | The name of that underlying processor. |
| **Last PSP Correlation ID** | A reference the PSP uses to link its own records to those of the underlying processor. Useful when asking the PSP to trace a transaction on your behalf. |
| **Last PSP Subprocessor Transaction ID** | The underlying processor's own transaction reference. Use this when contacting the processor directly. |
| **Last PSP Decline Code** | A short code indicating why the payment was declined (e.g. `insufficient_funds`). Only present for declined payments. |
| **Last PSP Decline Reason** | A plain-text explanation of why the payment was declined. Only present for declined payments. |

---

---
url: /payment-intent-tickets/manual-creation.md
---
# Manual Creation

Payment Intent Tickets are normally created through the checkout flow, but operators can create them manually from the management portal. This is useful for testing PSP integrations, resolving edge cases, or creating payments on behalf of a customer outside the normal checkout path.

The creation wizard has five steps, shown as breadcrumb buttons at the top. Each step must be completed in order; you can only advance once the current step's requirements are met.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Create a ticket | `payment_intent_ticket:create` |

## Step 1 — Select Tenant

Choose which brand this payment belongs to. Type a name in the search field to filter the list, or scroll through the tenant cards. Each card shows the brand's icon and name. Click a card to select it, then click **Continue**.

A selected tenant is highlighted and the Continue button enables. You can click a different tenant card to change your selection before advancing.

## Step 2 — Select Tenant Customer

Choose which customer this payment is for. The step shows a search field — no results are displayed until you enter a search term and press **Enter** to submit it.

Search by the customer's **external CRM ID** — the identifier the CRM system uses for that customer. Email addresses and names are not searchable here. If the payment needs to be applied to a specific trading account or sub-account, enter the CRM customer ID and sub-account ID joined with a colon (e.g. `12345:67890`).

If no matching customers are found, verify the external CRM ID and try again. There is no way to create a tenant customer from this wizard.

## Step 3 — Select Payment Channel

Choose which PSP and payment channel to use. The picker shows all channels configured for the selected tenant. Each channel shows its name and the currencies it supports.

::: warning Compliance restrictions may not be enforced
The channel list includes a notice that some compliance and country restrictions may not be applied here. Verify that the selected channel is appropriate for this customer before proceeding.
:::

The channels shown here are exactly the channels active on the brand's [Payment Channels](/tenants/client-experience/channels) page. If the channel you need is missing, you may need to add it there first.

If the tenant has no PSPs linked, or no channels configured, the list will be empty and you cannot proceed. Link a PSP from the [PSP's Linked Tenants](/payment-solution-providers/tenants) page, then configure channels for the brand.

## Step 4 — Channel Information

The fourth step is dynamic — the form adapts based on the selected channel's requirements. The channel determines which fields appear, so every payment captures the data the PSP needs to process the transaction.

### All channels

**Amount** and **Currency** are always present. Currency is a searchable dropdown limited to the currencies the selected channel supports — type to filter the list and click a result to select. Amount must meet any minimum or maximum constraints the PSP enforces for the channel.

### Channel-specific fields

Beyond amount and currency, the form adapts entirely to what the selected channel's PSP integration requires. Each PSP integration defines its own field set — this could be anything from a bank reference number and a file upload to cardholder name and card details. The exact fields shown depend on the channel; there is no universal template.

For **redirect** channels, the PSP collects the payment details on their own page, so typically fewer fields appear here. For inline channels, the form may include additional fields the PSP needs to initiate the transaction.

## Step 5 — Results

The final step shows the outcome of the creation. Depending on the channel type and the PSP's response, you will see one of:

| Outcome | Meaning |
| :--- | :--- |
| **Complete** | The payment was created and accepted by the PSP. You will see the PIT ID, status, and a link to view the full record. |
| **Redirect** | The payment requires the customer to visit the PSP's page. A redirect URL is provided — send this URL to the customer to complete the payment. |
| **Blocked** | The payment could not be created. An error message explains why — typically a PSP restriction blocked the transaction based on the customer's compliance status or country. |

Once the result is shown, click **Done** to leave the wizard. You can navigate to the new PIT from the directory or use the link shown on the result screen.

::: tip Creating a PIT does not charge the customer
Creating a Payment Intent Ticket manually records the intent to pay. The PSP handles the actual charge separately — the PIT tracks the lifecycle of that interaction. A PIT in `processing` status means the PSP is still working on it; `succeeded` means the PSP confirmed the charge completed.
:::

---

---
url: /payment-intent-tickets/dispositioning.md
---
# Dispositioning

Dispositioning is the act of manually setting the outcome of a Payment Intent Ticket. It is used when a payment needs to be resolved without waiting for an automated PSP response — for example, confirming a payment was received outside the system, or correcting a ticket that was resolved incorrectly.

There are two forms of dispositioning, each with different permissions and constraints.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Disposition a non-terminal ticket | `payment_intent_ticket:disposition` |
| Override a terminal ticket | `payment_intent_ticket:disposition:override` |

## Disposition (non-terminal tickets)

When a PIT is in a non-terminal status — anything other than `succeeded` or `canceled` — you can set its final outcome manually. This is available from both the directory row actions and the detail page toolbar.

Click **Disposition** to open the form. It shows the ticket's current status and a dropdown to choose the target disposition:

| Disposition | Effect |
| :--- | :--- |
| **Succeeded** | Mark the payment as completed. The PIT moves to `succeeded` and will contribute to success rate and volume metrics. |
| **Canceled** | Mark the payment as not completed. The PIT moves to `canceled` — a terminal non-success state. |

Select the desired outcome and click **Update Disposition**. The change takes effect immediately and is recorded in the audit log.

::: warning Disposition is final for the current status
Once a ticket reaches `succeeded` or `canceled`, the regular disposition form is no longer available. Correcting a terminal ticket requires **Override Disposition**.
:::

## Disposition Override (terminal tickets)

When a PIT has already reached a terminal status (`succeeded` or `canceled`), changing its outcome requires the override form. This requires elevated permission (`payment_intent_ticket:disposition:override`).

Click **Override Disposition** to open the form. It shows the ticket's current terminal status and the same dropdown to choose the new outcome. The override allows switching a succeeded ticket to cancelled, or a cancelled ticket back to succeeded.

Click **Update Disposition** to apply the override. As with regular dispositioning, the change takes effect immediately and is recorded in the audit log.

## Read-only mode

If you have `payment_intent_ticket:read` but lack the disposition or override permission, the detail page shows **View** as the active mode. The disposition and override links are hidden — you can inspect the current status but cannot change it.

The directory row action is also hidden. The row will show only **View** and **Audit** as pinned actions, with the overflow menu containing the navigation links (View PSP, View Tenant, etc.).

## Auditing

Every disposition and override is recorded in the ticket's audit log. The audit entry captures:

* The previous status
* The new status
* The user who made the change
* The timestamp

Click **Audit** on the detail toolbar or row action to review the full history.

---

---
url: /payment-intent-tickets/advanced.md
---
# Advanced Settings

Each Payment Intent Ticket has an advanced settings section that exposes a single configuration toggle. Advanced settings are separate from the ticket's core payment data and are edited through their own form.

## Permissions

| Action | Permission required |
| :--- | :--- |
| Edit advanced settings | `payment_intent_ticket:update:advanced` |

## Excluded from Automatic CRM Updates

The only setting under Advanced is **Excluded from Automatic CRM Updates**. When enabled, Payment Nexus will not automatically send status updates for this ticket to the brand's CRM system.

This is useful when:

* The CRM has already been updated manually and a duplicate notification would cause confusion.
* A payment is being processed outside the normal CRM workflow and should not appear in the CRM's records.
* The CRM integration is temporarily misconfigured and you need to suppress updates for specific tickets while it is fixed.

The setting affects only CRM webhook notifications — it does not affect:

* The ticket's status lifecycle within Payment Nexus
* PSP communication or reconciliation
* Checkout session behavior
* Any other ticket processing

## Accessing Advanced Settings

From the PIT detail page, click **Advanced** in the detail toolbar. From the directory, open the overflow menu on the row and click **Edit Advanced**.

The form shows a single toggle switch. Flip it on or off and save. The change takes effect immediately — no other ticket fields are shown or editable on this form.

::: tip Default is off
New tickets are created with **Excluded from Automatic CRM Updates** set to off. CRM notifications are sent by default; you must explicitly enable this setting to suppress them.
:::

---

---
url: /checkout-intent-tickets.md
---
# The Checkout Intent Tickets Module

A Checkout Intent Ticket (CIT) is a record of a customer-facing checkout session initiated by a brand. When a brand's platform sends a customer to the Payment Nexus checkout flow, a CIT is created to capture what the customer is paying, where they should land after the payment resolves, and whether they are allowed to change the amount before confirming.

Each CIT is linked to at most one [Payment Intent Ticket](/payment-intent-tickets/) — the PIT that records the actual payment attempt. If the customer completes the checkout flow and initiates a payment, the PIT is created and attached. If the session expires before the customer acts, the CIT remains with no associated PIT.

CITs are read-only in the management portal — they are created exclusively by the brand's platform via [Silent Authentication](/concepts#integration) and cannot be modified from the portal.

```mermaid
sequenceDiagram
    participant Brand as Brand Platform
    participant PN as Payment Nexus
    participant Customer as Customer Browser
    participant PSP as Payment Service Provider

    Brand->>PN: Silent Authentication request
    PN-->>Brand: Checkout URL (15-minute session)
    Note over PN: Checkout Intent Ticket created

    Brand->>Customer: Redirect to checkout URL
    Customer->>PN: Opens checkout flow
    Customer->>PN: Confirms payment

    Note over PN: Payment Intent Ticket created<br/>and linked to CIT

    PN->>PSP: Submit payment
    PSP-->>PN: Payment result
    PN->>Customer: Redirect to destination URL
```

## Permissions

| Action | Permission required |
| :--- | :--- |
| List tickets | `checkout_intent_ticket:list` |
| View a ticket | `checkout_intent_ticket:read` |
| View audit trail | `checkout_intent_ticket:audit` |

## Directory

The CIT directory is searchable, filterable, sortable, and exportable. It supports all standard directory features including the filter builder, power search, and column customisation. See the [Directories](/globals/directories/) section for full details on these shared capabilities.

### Default columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal Payment Nexus identifier for this CIT |
| **Unique ID** | The public-facing identifier passed to the brand's checkout redirect |
| **External Order ID** | The order reference from the brand's system |
| **Amount Editable** | Whether the customer was permitted to change the payment amount during checkout |
| **Transaction Amount** | The transaction amount and currency as configured by the brand |
| **Created At** | When the CIT was created |
| **Payment Intent Ticket** | The PIT created from this checkout session, if one exists |

### Row actions

Each row has two pinned actions:

| Action | Description |
| :--- | :--- |
| **View** | Open the full CIT detail page |
| **Audit** | View the audit history for this ticket |

## Viewing a CIT

Clicking **View** on any row opens the CIT detail page. See [Viewing a Checkout Intent Ticket](/checkout-intent-tickets/view) for a full breakdown of every field.

---

---
url: /checkout-intent-tickets/view.md
---
# Viewing a Checkout Intent Ticket

The CIT detail page shows all fields for the checkout session in a single **Basics** card.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View a ticket | `checkout_intent_ticket:read` |
| View audit trail | `checkout_intent_ticket:audit` |

## Basics

| Field | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this CIT. Copyable. |
| **Unique ID** | The public identifier for this checkout session, used in the checkout URL passed to the customer. Copyable. |
| **External Order ID** | The order reference from the brand's system. Copyable when present. |
| **Amount Editable** | Whether the customer was able to change the amount before confirming payment. |
| **Transaction Amount** | The amount and currency configured by the brand for this session. Copyable. |
| **Normalized Amount** | The EUR equivalent of the transaction amount, converted at the exchange rate in effect when the session was created. Copyable. |
| **Payment Intent Ticket** | A link to the associated PIT, if a payment was initiated during this session. Empty if the session expired before the customer acted. |
| **Destination on Success** | The URL the customer is sent to when the payment succeeds. |
| **Destination on Failure** | The URL the customer is sent to when the payment fails. |
| **Destination on Pending** | The URL the customer is sent to when the payment is left in a pending state. |
| **Destination on Completed** | A fallback destination used when no specific Success or Failure destination is configured. See [Destination URLs](/concepts#payment-entities) in the glossary for details. |
| **Destination on Cancel** | The URL the customer is sent to if they cancel during checkout. |
| **Created At** | When the CIT was created. |
| **Updated At** | When the CIT was last modified. |

## Session Expiry

Checkout sessions are time-limited. Once the customer opens the checkout link, they have 15 minutes to complete the checkout flow. If they do not act within that window, the session expires and the CIT remains unlinked to any payment.

---

---
url: /psp-customers.md
---
# The PSP Customer Accounts Module

A PSP Customer Account is a provider-issued account held on behalf of a customer — for example a virtual IBAN, a crypto wallet address, or a stored payment token. When a PSP creates an account for a customer (such as assigning them a deposit address), Payment Nexus records it here and links it to both the customer and the PSP.

PSP Customer Accounts are read-only in the management portal. They are created by the PSP integration and cannot be modified from the portal.

## Permissions

| Action | Permission required |
| :--- | :--- |
| List accounts | `psp_customer_account:list` |
| View an account | `psp_customer_account:read` |
| View audit trail | `psp_customer_account:audit` |

## Directory

The PSP Customer Accounts directory is searchable, filterable, sortable, and exportable. It supports all standard directory features including the filter builder, power search, and column customisation. See the [Directories](/globals/directories/) section for full details on these shared capabilities.

### Default columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal Payment Nexus identifier for this account |
| **Payment Service Provider** | The PSP that issued this account |
| **Tenant Customer** | The customer this account belongs to |
| **Account Type** | The type of account (e.g. Wallet, IBAN) |
| **Account Identifier** | The account address or reference issued by the PSP — for example a crypto wallet address or virtual IBAN. Copyable. |
| **External Reference ID** | An additional reference from the PSP, if provided. Copyable. |
| **Currency** | The currency this account is denominated in |
| **Label** | A short name for the account |
| **Description** | A longer description of the account |
| **Status** | The current status of the account (e.g. Active) |

### Row actions

Each row has two pinned actions:

| Action | Description |
| :--- | :--- |
| **View** | Open the full account detail page |
| **Audit** | View the audit history for this account |

## Viewing an Account

Clicking **View** on any row opens the account detail page. See [Viewing a PSP Customer Account](/psp-customers/view) for a full breakdown of every field.

---

---
url: /psp-customers/view.md
---
# Viewing a PSP Customer Account

The account detail page shows all fields for the PSP Customer Account in a single **Basics** card.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View an account | `psp_customer_account:read` |
| View audit trail | `psp_customer_account:audit` |

## Basics

| Field | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this account. Copyable. |
| **Payment Service Provider** | The PSP that issued this account. Links to the PSP record. |
| **Tenant Customer** | The customer this account belongs to. Links to the tenant customer record. |
| **Account Type** | The type of account — for example Wallet or IBAN. |
| **Account Identifier** | The account address or reference issued by the PSP — for example a crypto wallet address or virtual IBAN. Copyable. |
| **External Reference ID** | An additional reference from the PSP. Copyable when present. |
| **Currency** | The currency this account is denominated in. |
| **Label** | A short name for the account. |
| **Description** | A longer description of the account, typically set by the PSP integration. |
| **Status** | The current status of the account. |
| **Metadata** | Additional structured data provided by the PSP integration, displayed as JSON. Copyable. |
| **Created At** | When the account was first recorded in Payment Nexus. |
| **Updated At** | When the account was last modified. |

---

---
url: /tenant-customers.md
---
# The Tenant Customers Module

A Tenant Customer is a customer record scoped to a specific brand. Each record links a customer's identity — name, contact details, and addresses — to the brand they belong to, and serves as the hub for their payment history within that brand.

Tenant Customers are created by the brand's CRM integration and cannot be created or edited from the management portal.

## Permissions

| Action | Permission required |
| :--- | :--- |
| List customers | `tenant_customer:list` |
| View a customer | `tenant_customer:read` |
| View personal information | `tenant_customer:read:pii` |
| View audit trail | `tenant_customer:audit` |

::: tip PII visibility
Name, email, phone, and address fields are only shown to users with the `tenant_customer:read:pii` permission. Without it, those fields are hidden throughout the directory and detail page.
:::

## Directory

The Tenant Customers directory is searchable, filterable, sortable, and exportable. It supports all standard directory features including the filter builder, power search, and column customisation. See the [Directories](/globals/directories/) section for full details on these shared capabilities.

### Default columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal Payment Nexus identifier for this customer record |
| **Tenant Customer ID** | The customer's identifier in the brand's own system. Copyable. |
| **Name** | The customer's full name. Visible only with `tenant_customer:read:pii`. |
| **Tenant** | The brand this customer belongs to |

### Row actions

Each row has two pinned actions:

| Action | Description |
| :--- | :--- |
| **View** | Open the full customer detail page |
| **Audit** | View the audit history for this customer record |

### Toolbar actions

| Action | When shown | Description |
| :--- | :--- | :--- |
| **View Tenant** | Always | Navigate to the brand record for the selected customer. Requires `tenant:read`. |
| **Payments** | Always | View all Payment Intent Tickets for the selected customer. Requires `payment_intent_ticket:list`. |

## Viewing a Customer

Clicking **View** on any row opens the customer detail page. See [Viewing a Tenant Customer](/tenant-customers/view) for a full breakdown of every field.

---

---
url: /tenant-customers/view.md
---
# Viewing a Tenant Customer

The Tenant Customer detail page is split into four cards. The Basic Information card is always visible. The Personal Information, Address, and Shipping Address cards are only shown to users with the `tenant_customer:read:pii` permission.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View a customer | `tenant_customer:read` |
| View personal information | `tenant_customer:read:pii` |
| View audit trail | `tenant_customer:audit` |

## Toolbar

| Action | Description |
| :--- | :--- |
| **View Tenant** | Navigate to the brand record this customer belongs to. Requires `tenant:read`. |
| **Payments** | View all Payment Intent Tickets for this customer. Requires `payment_intent_ticket:list`. |

## Basic Information

| Field | Description |
| :--- | :--- |
| **ID** | The internal Payment Nexus identifier for this customer record. Copyable. |
| **Tenant** | The brand this customer belongs to. Links to the brand record. |
| **Tenant Customer ID** | The customer's identifier in the brand's own system. Copyable. |
| **Created At** | When this customer record was first created in Payment Nexus. |
| **Updated At** | When this customer record was last modified. |

## Personal Information

::: tip Requires `tenant_customer:read:pii`
This section is only visible to users with the PII permission.
:::

| Field | Description |
| :--- | :--- |
| **Name** | The customer's full name. |
| **Email** | The customer's email address. Copyable when present. |
| **Phone** | The customer's phone number. Copyable when present. |

## Address

::: tip Requires `tenant_customer:read:pii`
This section is only visible to users with the PII permission.
:::

The billing address on file for this customer.

| Field | Description |
| :--- | :--- |
| **Address Line 1** | First line of the billing address. |
| **Address Line 2** | Second line of the billing address. |
| **City** | City. |
| **State** | State or region. |
| **Country** | Country code. |
| **Postal Code** | Postcode or ZIP. |

## Shipping Address

::: tip Requires `tenant_customer:read:pii`
This section is only visible to users with the PII permission.
:::

The shipping address on file for this customer. Fields mirror the Address section above.

---

---
url: /administration.md
---
# The Administration Module

The Administration module is the control plane for system-wide configuration. It covers identity and access management, reference data, the integration catalogue, and platform-wide webhook notifications.

Access to the module requires at least one of the following permissions: `users:read`, `roles:read`, `currency:read`, or `domain:read`. Users without any of these will not see the Administration section in the navigation.

## Sub-modules

| Module | What it manages |
| :--- | :--- |
| [Users](/administration/users/) | User accounts and role assignments |
| [Roles](/administration/roles/) | Roles and their permission sets |
| [Currencies](/administration/currencies/) | Supported currencies and exchange rates |
| [Domains](/administration/domains/) | Checkout domains registered in the system |
| [PSP Integrations](/administration/psp-integrations/) | PSP vendor integration catalogue and release states |
| [CRM Integrations](/administration/crm-integrations/) | CRM vendor integration catalogue and release states |
| [System Webhooks](/administration/system-webhooks/) | Platform-wide outbound notifications for operational and integration events |

---

---
url: /administration/users.md
---
# Users

The Users module lists every account that has authenticated into Payment Nexus. Accounts are provisioned automatically on first login via your organisation's Identity Provider — they cannot be created manually through the portal.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the directory | `users:read` |
| Open a user record | `users:read` |
| Edit a user | `users:update` |
| View audit history | `users:audit` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal user identifier |
| **Name** | Full name sourced from the Identity Provider |
| **Nickname** | Display name |
| **Email** | Email address sourced from the Identity Provider |
| **Super Admin** | Whether the user has unconditional system-wide access |
| **Created At** | When the account was first provisioned |
| **Updated At** | When the record was last modified |

---

---
url: /administration/users/view.md
---
# Viewing a User

The user detail page shows who the user is and what they can currently do in the system.

## Profile header

The header shows the user's avatar, full name, and email address as sourced from the Identity Provider. These fields are read-only and cannot be changed through Payment Nexus.

## Resolved User Capabilities

This section lists every capability in the system and whether the user currently holds it, derived from the combined effect of all their assigned roles. Capabilities are grouped by functional area (e.g. **Application**, **Auditlog**, **Users**).

Each row shows the capability name and one of two states:

| State | Meaning |
| :--- | :--- |
| **Granted** | At least one of the user's roles grants this capability and none deny it. The user can perform the action. |
| **Denied** | No role grants this capability, or a role explicitly denies it. The user cannot perform the action. |

### The WHY button

Every capability row has a **WHY** button. Clicking it opens a dialog that explains the resolved state in plain language:

* If **Granted**: the dialog lists exactly which of the user's roles are responsible for granting the capability (e.g. *"The following roles assigned to the user grant the `payment_intent_ticket:read` capability: Customer Support Agent."*).
* If **Denied**: the dialog confirms that none of the user's current roles grant the capability.

This is primarily useful when troubleshooting access issues — for example, confirming that a user has the right capability before they report a problem, or identifying which role to check when a capability is unexpectedly present or absent.

## Navigation

From the view page you can:

* **Edit** — open the edit page to change the Super Admin flag or manage role assignments
* **Audit Instance** — view the change history for this user record
* **List** — return to the Users directory

---

---
url: /administration/users/edit.md
---
# Editing a User

The edit page controls what a user is allowed to do in Payment Nexus. There are two things you can change: their Super Admin status and their assigned roles.

::: warning
You cannot edit your own user account. The edit page is blocked for the currently authenticated user.
:::

## Super Admin

The **Super Admin** dropdown grants unconditional access to every capability in the system, bypassing role assignments entirely. A Super Admin cannot be locked out by role configuration.

This should only be set for break-glass accounts or initial system setup. For day-to-day access management, use roles instead.

## Assigned Roles

The **Assigned Roles** section shows the roles currently attached to the user. Each role is listed with its name and description.

* To **add** a role, type in the search box to find it and click the **+** button.
* To **remove** a role, click the **−** button next to it.

Role changes take effect after the user logs out and back in — updates are not applied to an active session.

## Saving changes

Click **Save** to apply changes. Click **Reset** to discard any unsaved changes and revert to the last saved state.

---

---
url: /administration/roles.md
---
# Roles

Roles define the set of permissions a user can exercise in Payment Nexus. A user can hold multiple roles; their effective capabilities are the union of all granted permissions across those roles, subject to any explicit denials.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the directory | `roles:read` + `application:administer` |
| Open a role record | `roles:read` + `application:administer` |
| Create a role | `roles:create` + `application:administer` |
| Edit a role | `roles:update` + `application:administer` |
| View audit history | `roles:audit` + `application:administer` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal role identifier |
| **Name** | Short identifier shown in user assignments |
| **Description** | Plain-text explanation of what the role is for |
| **Created At** | When the role was first created |
| **Updated At** | When the role was last modified |

---

---
url: /administration/roles/view.md
---
# Viewing a Role

The role detail page shows the role's name and description, and every capability it currently configures.

## Capabilities

This section lists every capability in the system and the state this role has set for each one. Capabilities are grouped by functional area (e.g. **Users**, **Tenants**, **PSP**). Each capability shows one of three states:

| State | Meaning |
| :--- | :--- |
| **Granted** | This role explicitly allows the capability. |
| **Inherited** | This role takes no position — the capability is neutral. |
| **Denied** | This role explicitly forbids the capability. Denial takes precedence over grants from any other role. |

## Navigation

From the view page you can:

* **Edit** — open the edit page to change the role's name, description, or capability settings
* **Audit Instance** — view the change history for this role record
* **List** — return to the Roles directory

---

---
url: /administration/roles/edit.md
---
# Editing a Role

The edit page lets you define what a role is and what it allows or denies.

## Name and Description

| Field | Description |
| :--- | :--- |
| **Name** | Short identifier shown in user assignments and the directory |
| **Description** | Plain-text explanation of what this role is for |

## Capabilities

Each capability in the system can be set to one of three states:

| State | Meaning |
| :--- | :--- |
| **Granted** | The capability is explicitly allowed by this role. |
| **Inherited** | The capability is neutral — it will be granted only if another of the user's roles grants it. |
| **Denied** | The capability is explicitly forbidden. Denial wins over grants from any other role, regardless of how many roles grant it. |

Capabilities are grouped by functional area. Toggle each one individually to build the role's permission profile.

::: warning
Deny always beats Grant. If a user holds one role that denies a capability and another that grants it, the denial wins. Use **Denied** deliberately — it is an active block, not just an absence of permission.
:::

## Saving changes

Click **Save** to apply changes. Click **Reset** to discard any unsaved changes and revert to the last saved state.

## Capabilities reference

For a full list of available capabilities and what each one controls, see the [Capabilities Reference](./capabilities.md).

---

---
url: /administration/roles/capabilities.md
---
# Capabilities Reference

Every capability that can be configured on a role is listed here, grouped by functional area.

## The Permission Model

Every capability can be set to one of three states on a role:

| State | Meaning |
| :--- | :--- |
| **Granted** | The capability is explicitly allowed by this role. The user can perform the action unless another of their roles explicitly denies it. |
| **Inherited** | The capability is neutral — it will be granted only if another of the user's roles grants it. |
| **Denied** | The capability is explicitly forbidden. This takes precedence over all other roles — even if another role grants it, the denial wins. |

**Precedence rule:** Deny always beats Grant. If any single role on a user denies a capability, the user does not have it, regardless of how many other roles grant it.

## Users & Roles

| Capability | What it controls |
| :--- | :--- |
| `users:read` | View user records |
| `users:update` | Edit user configuration and role assignments |
| `users:audit` | View the user audit log |
| `roles:read` | View role records |
| `roles:create` | Create new roles |
| `roles:update` | Edit existing roles |
| `roles:audit` | View the role audit log |

## Tenants

| Capability | What it controls |
| :--- | :--- |
| `tenant:read` | View tenant records |
| `tenant:read:channels` | View a tenant's payment channel configuration |
| `tenant:read:domains` | View a tenant's domain assignments |
| `tenant:read:adapter` | View a tenant's adapter configuration |
| `tenant:read:email` | View a tenant's email settings |
| `tenant:read:support` | View a tenant's customer support and live chat settings |
| `tenant:read:api:credentials` | View a tenant's API credentials |
| `tenant:read:webhooks` | View a tenant's webhook configuration |
| `tenant:audit` | View the tenant audit log |
| `tenant:create` | Create new tenants |
| `tenant:update:basic` | Edit a tenant's core fields |
| `tenant:update:branding` | Edit a tenant's branding and checkout appearance |
| `tenant:update:channels` | Edit a tenant's payment channel assignments |
| `tenant:update:domains` | Edit a tenant's domain assignments |
| `tenant:update:adapter` | Edit a tenant's adapter configuration |
| `tenant:update:email` | Edit a tenant's email settings |
| `tenant:update:support` | Edit a tenant's customer support and live chat settings |
| `tenant:manage:api:credentials` | Create, rotate, and revoke a tenant's API credentials |
| `tenant:manage:webhooks` | Create and manage a tenant's webhooks |
| `tenant:manage:activation` | Activate or deactivate a tenant |

## Payment Service Providers

| Capability | What it controls |
| :--- | :--- |
| `payment_service_provider:read` | View PSP records |
| `payment_service_provider:read:adapter` | View a PSP's adapter configuration |
| `payment_service_provider:read:restrictions` | View a PSP's restriction rules |
| `payment_service_provider:audit` | View the PSP audit log |
| `payment_service_provider:create` | Create new PSPs |
| `payment_service_provider:update:basic` | Edit a PSP's core fields |
| `payment_service_provider:update:adapter` | Edit a PSP's adapter configuration |
| `payment_service_provider:update:restrictions` | Edit a PSP's restriction rules |
| `payment_service_provider:update:activation` | Activate or deactivate a PSP |

## Payment Intent Tickets

| Capability | What it controls |
| :--- | :--- |
| `payment_intent_ticket:read` | View payment intent ticket records |
| `payment_intent_ticket:read:pii` | View PII fields on payment intent tickets |
| `payment_intent_ticket:read:psp` | View PSP-level fields on payment intent tickets |
| `payment_intent_ticket:read:crm` | View CRM-linked fields on payment intent tickets |
| `payment_intent_ticket:audit` | View the payment intent ticket audit log |
| `payment_intent_ticket:create` | Manually create payment intent tickets |
| `payment_intent_ticket:disposition` | Approve or reject a payment intent ticket |
| `payment_intent_ticket:disposition:override` | Override a payment intent ticket disposition |
| `payment_intent_ticket:reconcile` | Manually reconcile a payment intent ticket |
| `payment_intent_ticket:disable:crm_sync` | Disable CRM sync on a payment intent ticket |

## Checkout Intent Tickets

| Capability | What it controls |
| :--- | :--- |
| `checkout_intent_ticket:read` | View checkout intent ticket records |
| `checkout_intent_ticket:audit` | View the checkout intent ticket audit log |

## Customers

| Capability | What it controls |
| :--- | :--- |
| `tenant_customer:read` | View tenant customer records |
| `tenant_customer:read:pii` | View PII fields on tenant customers |
| `tenant_customer:audit` | View the tenant customer audit log |
| `psp_customer_account:read` | View PSP customer account records |
| `psp_customer_account:read:pii` | View PII fields on PSP customer accounts |
| `psp_customer_account:audit` | View the PSP customer account audit log |

## Reference Data

| Capability | What it controls |
| :--- | :--- |
| `currency:read` | View currency records |
| `currency:sync` | Trigger a manual currency rate sync |
| `domain:read` | View domain records |

## Integrations

| Capability | What it controls |
| :--- | :--- |
| `integrations:psp:read` | View PSP integration records |
| `integrations:psp:create` | Register new PSP integrations |
| `integrations:psp:update` | Edit PSP integration configuration |
| `integrations:psp:dev-uat` | Promote a PSP integration to dev-uat state |
| `integrations:psp:production-uat` | Promote a PSP integration to production-uat state |
| `integrations:crm:read` | View CRM integration records |
| `integrations:crm:create` | Register new CRM integrations |
| `integrations:crm:update` | Edit CRM integration configuration |
| `integrations:crm:dev-uat` | Promote a CRM integration to dev-uat state |
| `integrations:crm:production-uat` | Promote a CRM integration to production-uat state |

## Debug & Operations

| Capability | What it controls |
| :--- | :--- |
| `system:webhooks:read` | View and test system-wide outbound webhooks |
| `system:webhooks:manage` | Create, edit, enable, disable, and delete system-wide outbound webhooks |
| `auditLog:monitor` | View the global audit log and per-record audit tabs |
| `queues:monitor` | View queue job status |
| `queues:manage` | Requeue and manage jobs |
| `webhooks:monitor` | View webhook delivery logs |
| `webhooks:manage` | Reprocess webhook deliveries |
| `crons:monitor` | View scheduled cron job status |
| `postman:access` | Access the HTTP Requester tool |
| `terminal:access` | Access the terminal tool |
| `application:versions` | View application version information |

---

---
url: /administration/currencies.md
---
# Currencies

The Currencies module is a read-only reference directory of all currencies supported by Payment Nexus. Currency configuration is managed at the system level and is not editable through the portal.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the directory | `currency:read` + `application:administer` |
| Open a currency record | `currency:read` + `application:administer` |
| Trigger a rate sync | `currency:sync` + `application:administer` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal currency identifier |
| **Symbol** | ISO currency code (e.g. `USD`, `EUR`, `BTC`) |
| **Name** | Full currency name (e.g. "US Dollar") |
| **Euro Exchange Rate** | The current exchange rate relative to EUR |
| **Updated At** | When the rate was last refreshed |

## Exchange rates

EUR is the system's base currency. Every other currency stores its rate as a ratio to EUR. Rates are updated automatically by a background sync service and are not manually editable. The **Updated At** column shows when the last successful sync occurred for each currency.

The EUR-normalised rate is used to compute the **Volume** metric — all payment amounts are converted to EUR at the rate recorded at the time of the transaction.

---

---
url: /administration/currencies/view.md
---
# Viewing a Currency

The currency detail page shows the full configuration for a single currency record. Field names below match what is shown in the UI.

## Fields

| Field | Description |
| :--- | :--- |
| **name** | Full currency name (e.g. "United Arab Emirates Dirham") |
| **symbol** | ISO currency code (e.g. `AED`) |
| **prefix** | Optional string prepended to displayed amounts |
| **suffix** | Optional string appended to displayed amounts |
| **precision** | Number of decimal places used when displaying amounts |
| **minDepositAmountUnfactored** | Minimum deposit amount before the factor is applied |
| **minDepositAmountFactor** | Scaling factor for the minimum deposit amount |
| **maxDepositAmountUnfactored** | Maximum deposit amount before the factor is applied |
| **maxDepositAmountFactor** | Scaling factor for the maximum deposit amount |
| **rateToBaseUnfactored** | Raw exchange rate value before the factor is applied |
| **rateToBaseFactor** | Divisor used to derive the actual rate (e.g. `1,000,000` means divide by 10⁶) |
| **createdAt** | When the currency record was first created |
| **updatedAt** | When the record was last updated by the sync service |

All fields are read-only. Currency configuration is managed at the system level.

## Navigation

From the view page you can:

* **List** — return to the Currencies directory

---

---
url: /administration/domains.md
---
# Domains

The Domains module is a read-only directory of all checkout domains registered in Payment Nexus. A domain is a fully qualified domain name (FQDN) that routes incoming checkout traffic to a specific tenant. Domains are managed through each tenant's own configuration — this module provides a system-wide view across all tenants.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the directory | `domain:read` + `application:administer` |
| Open a domain record | `domain:read` + `application:administer` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal domain identifier |
| **Fully Qualified Domain Name** | The hostname (e.g. `checkout.example.com`) |
| **Usage Environment** | Whether the domain is `production` or `sandbox` |
| **Description** | Optional note about the domain's purpose |
| **Tenant** | The tenant this domain is assigned to |

## Production vs Sandbox

Each domain is classified as either production or sandbox:

* **Production** — Handles live transactions.
* **Sandbox** — Used for testing and integration development. Can optionally be restricted to a whitelist of IP addresses so only designated test systems can reach it.

To add, edit, or remove domains for a tenant, navigate to that tenant's record and use the Domains section there.

---

---
url: /administration/domains/view.md
---
# Viewing a Domain

The domain detail page shows the full configuration for a single checkout domain record.

## Fields

| Field | Description |
| :--- | :--- |
| **tenant** | The tenant this domain is assigned to |
| **fqdn** | The fully qualified domain name (e.g. `checkout.example.com`) |
| **isPrimary** | Whether this is the tenant's primary production domain |
| **isSandbox** | Whether this is a sandbox domain used for testing |
| **sandboxIpWhitelist** | IP addresses permitted to access this domain (sandbox only) |
| **description** | Optional note about the domain's purpose |
| **createdAt** | When the domain record was created |
| **updatedAt** | When the record was last modified |

All fields are read-only from this view. To modify domain assignments, navigate to the tenant's record.

## Navigation

From the view page you can:

* **List** — return to the Domains directory

---

---
url: /administration/crm-integrations.md
---
# CRM Integrations

The CRM Integrations module manages the catalogue of CRM vendor adapters available in the system. Each entry represents a specific version of a CRM integration — the code that connects Payment Nexus to a customer relationship management platform. Release state management works identically to [PSP Integrations](/administration/psp-integrations/).

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the directory | `integrations:crm:read` + `application:administer` |
| Open an integration record | `integrations:crm:read` + `application:administer` |
| Change release state | `integrations:crm:update` + `application:administer` |
| Promote to dev-uat | `integrations:crm:dev-uat` + `application:administer` |
| Promote to production-uat | `integrations:crm:production-uat` + `application:administer` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal integration identifier |
| **Vendor** | Human-readable CRM vendor name |
| **Release Version** | The version string for this integration build |
| **Release State** | Current stage in the release pipeline |

CRM integrations use the same release pipeline as PSP integrations. See [PSP Integrations — Release States](/administration/psp-integrations/#release-states) for the full state definitions.

Integration records cannot be created or deleted through the UI — they are registered by the development and deployment process.

---

---
url: /administration/crm-integrations/view.md
---
# Viewing a CRM Integration

The CRM Integration detail page shows the current state of a single integration record.

## Fields

| Field | Description |
| :--- | :--- |
| **Vendor** | Human-readable CRM vendor name (e.g. `Demo`, `Antelope`) |
| **Release Version** | The version string for this integration build |
| **Release State** | Current stage in the release pipeline |

## Changing release state

Use the state control on the record to transition the integration to a new release state. Not all transitions are available to all users:

* Promotion to `dev-uat` requires `integrations:crm:dev-uat`
* Promotion to `production-uat` requires `integrations:crm:production-uat`
* General state updates require `integrations:crm:update`

For the full list of states and what they mean, see [PSP Integrations — Release States](/administration/psp-integrations/#release-states).

## Navigation

From the view page you can:

* **List** — return to the CRM Integrations directory

---

---
url: /administration/psp-integrations.md
---
# PSP Integrations

The PSP Integrations module manages the catalogue of PSP vendor adapters available in the system. Each entry represents a specific version of a PSP vendor integration — the code that connects Payment Nexus to a payment processor.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the directory | `integrations:psp:read` + `application:administer` |
| Open an integration record | `integrations:psp:read` + `application:administer` |
| Change release state | `integrations:psp:update` + `application:administer` |
| Promote to dev-uat | `integrations:psp:dev-uat` + `application:administer` |
| Promote to production-uat | `integrations:psp:production-uat` + `application:administer` |

## Directory columns

| Column | Description |
| :--- | :--- |
| **ID** | Internal integration identifier |
| **Key** | The integration's vendor identifier code |
| **Release Version** | The version string for this integration build |
| **Release State** | Current stage in the release pipeline |

## Release states

PSP integrations move through a defined pipeline of release states:

| State | Meaning |
| :--- | :--- |
| `dev-qa` | In active development and QA testing. Not visible to most users. |
| `dev-uat` | In user acceptance testing for development. Visible to most users but promotion is restricted to elevated roles. |
| `production` | Live and available for use in production tenants. |
| `production-uat` | Live in production with a pending update undergoing UAT. Minor instability may occur. |
| `production-qa` | Live in production with a pending update in QA. Increased risk of instability. |
| `deprecated` | Still functional but scheduled for removal. Existing assignments continue to work. |
| `suspended` | Temporarily disabled. Cannot process new transactions. |
| `removed` | Decommissioned. No longer available for use. |

Integration records cannot be created or deleted through the UI — they are registered by the development and deployment process.

---

---
url: /administration/psp-integrations/view.md
---
# Viewing a PSP Integration

The PSP Integration detail page shows the current state of a single integration record.

## Fields

| Field | Description |
| :--- | :--- |
| **Key** | The integration's vendor identifier code (e.g. `wire`, `praxis`) |
| **Release Version** | The version string for this integration build |
| **Release State** | Current stage in the release pipeline |

## Changing release state

Use the state control on the record to transition the integration to a new release state. Not all transitions are available to all users:

* Promotion to `dev-uat` requires `integrations:psp:dev-uat`
* Promotion to `production-uat` requires `integrations:psp:production-uat`
* General state updates require `integrations:psp:update`

For the full list of states and what they mean, see the [PSP Integrations directory](./index.md#release-states).

## Navigation

From the view page you can:

* **List** — return to the PSP Integrations directory

---

---
url: /administration/system-webhooks.md
---
# System Outbound Webhooks

System Outbound Webhooks configure the HTTP endpoints that receive platform-wide event notifications from Payment Nexus. Use this page when an operations, automation, monitoring, or integration system needs to be notified about activity that can span multiple tenants.

System webhooks are different from tenant outbound webhooks. Tenant webhooks are configured inside a single brand and only report events for that brand. System webhooks are configured at the platform level and can receive events from across the whole Payment Nexus environment.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View system webhooks | `system:webhooks:read` |
| Test a system webhook | `system:webhooks:read` |
| Add, edit, enable, disable, or delete system webhooks | `system:webhooks:manage` |

## Webhook table

The table lists every system webhook currently configured.

| Column | Description |
| :--- | :--- |
| **Description** | An optional label explaining what the webhook is used for |
| **Webhook URL** | The HTTP or HTTPS endpoint that receives event notifications |
| **Events** | The event types this webhook is subscribed to |
| **Enabled** | Whether Payment Nexus should currently send events to this endpoint |
| **Pre-Shared Key** | The secret used to sign outgoing payloads, shown in masked form |

## Toolbar and row actions

| Action | Description |
| :--- | :--- |
| **Refresh** | Reloads the webhook list from the backend |
| **Add** | Opens the form to create a new system webhook |
| **Edit** | Updates the webhook URL, description, events, enabled state, or pre-shared key |
| **Test** | Sends sample payloads for the webhook's subscribed events and reports whether the endpoint returned a successful response |
| **Delete** | Permanently removes the webhook |

## Adding or editing a webhook

The same fields are used when adding and editing a system webhook.

| Field | Required | Description |
| :--- | :--- | :--- |
| **Description** | No | A short label that helps operators identify the webhook's purpose |
| **Webhook URL** | Yes | The HTTP or HTTPS endpoint that receives event notifications |
| **Pre-Shared Key (PSK)** | Yes | A shared secret used to verify that deliveries came from Payment Nexus |
| **Events** | Yes | One or more event types to send to this endpoint |
| **Enabled** | — | Controls whether Payment Nexus currently sends events to this webhook |

::: warning
Changing the pre-shared key takes effect for future deliveries immediately. Coordinate key changes with the receiving system so it can verify new signatures before the webhook is relied on in production.
:::

## Available events

System webhooks can subscribe to account, configuration, operational, and payment events.

| Event | Fires when |
| :--- | :--- |
| `user.created` | A user account is created |
| `user.updated` | A user account is updated |
| `user.deleted` | A user account is deleted |
| `tenant.created` | A tenant is created |
| `tenant.updated` | A tenant is updated |
| `tenant.deleted` | A tenant is deleted |
| `psp.created` | A payment service provider record is created |
| `psp.updated` | A payment service provider record is updated |
| `psp.deleted` | A payment service provider record is deleted |
| `tenant_psp.created` | A tenant-to-PSP assignment is created |
| `tenant_psp.updated` | A tenant-to-PSP assignment is updated |
| `tenant_psp.deleted` | A tenant-to-PSP assignment is deleted |
| `role.created` | A role is created |
| `role.updated` | A role is updated |
| `role.deleted` | A role is deleted |
| `system.error` | Payment Nexus records an unhandled system error |
| `payment_intent_ticket.created` | A payment intent ticket is created |
| `payment_intent_ticket.updated` | A payment intent ticket is updated |
| `payment_intent_ticket.saved` | A payment intent ticket is created or updated |
| `payment_intent_ticket.canceled_to_succeeded_status_update_failed` | A payment ticket was canceled locally but a later provider update indicated success, and Payment Nexus could not safely apply that status change automatically |

## Payload and signature verification

Each delivery is a `POST` request with a JSON body and these headers:

| Header | Description |
| :--- | :--- |
| `X-Request-ID` | A unique UUID for this delivery |
| `X-Event` | The event type that triggered the delivery |
| `X-Timestamp` | ISO 8601 UTC timestamp of the delivery |
| `X-Signature` | A bcrypt hash for verifying authenticity |
| `User-Agent` | `Payment Nexus/{VERSION} ({ENVIRONMENT})` |

To verify a delivery, reconstruct the pre-hash string `{timestamp}|{psk}|{requestId}|{event}` using the values from the headers and your stored PSK, then verify it against `X-Signature` using bcrypt. Checking the timestamp also helps guard against replay attacks.

The body uses this shared envelope:

```json
{
  "requestId": "7c357b81-40c5-49f2-8826-38dfd40003eb",
  "event": "payment_intent_ticket.updated",
  "timestamp": "2026-05-25T12:00:00.000Z",
  "signature": "$2a$10$...",
  "data": {}
}
```

The contents of `data` depend on the event type.

## Payment event tenant context

Payment-related system webhook payloads include both the tenant and the payment ticket. This allows receiving systems to identify which brand the event belongs to without needing to infer it from the ticket alone.

```json
{
  "requestId": "7c357b81-40c5-49f2-8826-38dfd40003eb",
  "event": "payment_intent_ticket.canceled_to_succeeded_status_update_failed",
  "timestamp": "2026-05-25T12:00:00.000Z",
  "signature": "$2a$10$...",
  "data": {
    "tenant": {
      "id": 123,
      "name": "Example Brand"
    },
    "ticket": {
      "id": 456,
      "status": "canceled",
      "amount": {
        "value": "100.00",
        "currency": "USD"
      },
      "amountInBase": {
        "value": "90.00",
        "currency": "EUR"
      },
      "customer": {
        "eid": "crm-customer-id",
        "uid": 789
      },
      "meta": {
        "checkoutOrderId": "ORDER-123",
        "pspTxId": "provider-transaction-id",
        "pspTxInfo": null
      },
      "createdAt": "2026-05-25T11:30:00.000Z",
      "updatedAt": "2026-05-25T12:00:00.000Z"
    }
  }
}
```

::: tip
If a receiving system routes events by brand, use `data.tenant.id` as the stable identifier and `data.tenant.name` as the human-readable label for logs, alerts, and dashboards.
:::

## Other event payloads

Lifecycle events such as `user.created`, `tenant.updated`, or `role.deleted` include the affected model name, record ID, and a diff summary in `data`.

System error events include error details such as name, code, message, stack, cause, metadata, and Sentry tags where available. These events are intended for operational alerting and incident investigation.

## Testing a webhook

Use **Test** after creating or changing a webhook. The test action sends sample payloads for every event the webhook subscribes to and checks whether the receiving endpoint responds successfully.

For payment events, test payloads include sample tenant context:

```json
{
  "tenant": {
    "id": 0,
    "name": "Test Tenant"
  }
}
```

Successful tests confirm that the endpoint is reachable and accepts the payload shape. They do not confirm that the receiving system performs all downstream business logic correctly.

## Operational guidance

* Use narrow event subscriptions where possible so each receiving system only gets the events it needs.
* Keep disabled webhooks only when they are expected to be re-enabled; delete obsolete endpoints to reduce operational noise.
* Rotate pre-shared keys if an endpoint owner changes or a secret may have been exposed.
* Review outgoing webhook logs in [Debug Tools — Webhooks](/debug-tools/webhooks/) when investigating delivery failures.

---

---
url: /debug-tools.md
---
# Debug Tools

The Debug Tools module provides operational and diagnostic tools for monitoring and troubleshooting the Payment Nexus system. These tools are intended for operators and developers who need visibility into background processes, integration activity, and system state.

## Available tools

| Tool | Purpose |
| :--- | :--- |
| [System Audit Log](/debug-tools/system-audit-log/) | System-wide audit trail of all user and system actions |
| [HTTP Requester](/debug-tools/http-requester/) | Make arbitrary HTTP requests from the application server |
| [AMQP Queues](/debug-tools/queue-jobs/) | Monitor message queue depth, throughput, and backlog |
| [Webhooks](/debug-tools/webhooks/) | View and manage incoming and outgoing webhook traffic |
| [Cron Jobs](/debug-tools/cron-jobs/) | Monitor scheduled background jobs |
| [Versions](/debug-tools/versions/) | View application and dependency version information |

## Permissions

Access to debug tools requires `application:administer` in addition to the capability for each individual tool. See each tool's page for its specific permission requirement.

---

---
url: /debug-tools/system-audit-log.md
---
# System Audit Log

The System Audit Log provides a system-wide view of every audited action taken in Payment Nexus — across all users, tenants, and record types — in reverse chronological order.

For full documentation on what is audited, how to read audit entries, and how to use the record-level audit tabs, see the [Auditing](/globals/auditing) guide.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View the system audit log | `auditLog:monitor` + `application:administer` |

---

---
url: /debug-tools/http-requester.md
---
# HTTP Requester

The HTTP Requester is a Postman-style request builder built into Payment Nexus. Unlike a local tool, requests originate from the **application server** — meaning the server's IP address, DNS resolution, and network access apply, not yours. Use it to test PSP and CRM endpoints exactly as the application would hit them, or diagnose connectivity issues without leaving the portal.

::: warning
Requests are made from the server, not your browser. This is intentional — but it also means any request you send has the same network reach as the application itself.
:::

## Permissions

| Action | Permission required |
| :--- | :--- |
| Use the HTTP Requester | `postman:access` + `application:administer` |

## Making a request

1. Select the HTTP **Method** (GET, POST, PUT, PATCH, DELETE, HEAD)
2. Enter the target **URL**
3. Configure any of the tabs below as needed
4. Click **Send**

The response appears in the panel below the form. Click **Reset** to clear the form back to defaults.

::: tip
Form state is preserved in the URL — you can bookmark or share a pre-filled request.
:::

## Parameters

Add query string parameters as key/value pairs. Each parameter can be individually toggled on or off without removing it from the list. Parameters are appended to the URL as `?key=value`.

## Body

Only visible for methods that carry a body (POST, PUT, PATCH). Select a **Content-Type** and enter the raw body:

| Content-Type | Notes |
| :--- | :--- |
| `application/json` | Body is parsed and sent as a JSON object |
| `application/xml` | Sent as a raw string |
| `text/xml` | Sent as a raw string |
| `application/x-www-form-urlencoded` | Sent as a raw string |
| `text/plain` | Sent as a raw string |

## Authorization

| Mode | Behaviour |
| :--- | :--- |
| **None** | No authentication header added |
| **Basic** | Sends `Authorization: Basic <base64>` using the provided username and password |
| **Bearer** | Sends `Authorization: Bearer <token>` using the provided token |

## Headers

Add custom request headers as key/value pairs. Each header can be toggled on or off individually. The following headers are managed automatically — you don't need to set them manually:

* `Content-Type` — set from the Body tab when a body is present
* `Authorization` — set from the Authorization tab
* `User-Agent` — always sent as `Payment Nexus/{VERSION}`

## Pre-Request Script

A JavaScript snippet that runs on the server immediately before the request is dispatched. Use it to dynamically modify the request at the last moment — the classic use case is computing a time-sensitive HMAC signature and injecting it as a header.

The script receives a `ctx` object containing the full Axios request configuration. Modify it as needed and return it — the return value is what gets sent.

### Available globals

| Variable | What it is |
| :--- | :--- |
| `ctx` | The [Axios](https://axios.rest/) request config — `url`, `method`, `headers`, `params`, `data`, etc. |
| `bcrypt` | [bcryptjs](https://github.com/dcodeIO/bcrypt.js) — password hashing |
| `luxon` | [Luxon](https://moment.github.io/luxon/) — date/time parsing and formatting |
| `nodeCrypto` | Node.js `crypto` module — HMAC, SHA, AES, and other cryptographic operations |

### Example: add an HMAC-SHA256 signature header

```js
const timestamp = luxon.DateTime.now().toUnixInteger().toString()
const body = JSON.stringify(ctx.data ?? {})
const signature = nodeCrypto
  .createHmac('sha256', 'your-secret-key')
  .update(timestamp + body)
  .digest('hex')

ctx.headers['X-Timestamp'] = timestamp
ctx.headers['X-Signature'] = signature

return ctx
```

## Request Options

| Option | Default | Range | Description |
| :--- | :--- | :--- | :--- |
| **Timeout** | 5000 ms | 1000–60000 ms | How long to wait for a response before aborting |
| **Max Redirects** | 0 | 0–21 | How many HTTP redirects to follow automatically |

## Response

| Element | Description |
| :--- | :--- |
| **Status** | HTTP status code and text (e.g. `200 OK`, `404 Not Found`) |
| **Time** | Round-trip duration in milliseconds |
| **Size** | Response body size in bytes |
| **URL** | Final resolved URL (after any redirects) |
| **Body** | Response body with syntax highlighting for JSON and XML |
| **Headers** | All response headers as key/value pairs |

### Exporting a response

The response panel includes a copy menu to export the full request and response in several formats:

* **Markdown** — formatted document suitable for pasting into a ticket or chat
* **HTTP** — raw HTTP request/response format
* **Slack / Teams / WhatsApp / Telegram** — formatted for pasting directly into those platforms

---

---
url: /debug-tools/queue-jobs.md
---
# AMQP Queues

Payment Nexus uses [LavinMQ](https://lavinmq.com/) as its AMQP message broker to process background jobs asynchronously — inbound webhook callbacks from PSPs, outbound notifications to CRM systems, scheduled tasks, and more. The AMQP Queues page surfaces the real-time state of every queue in the broker so you can see what's flowing, what's stuck, and what has failed.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View queue status | `queues:monitor` + `application:administer` |
| Replay or discard messages | `queues:manage` + `application:administer` |

## Summary metrics

Four headline figures appear at the top of the page, updated in real time via WebSocket:

| Metric | What it shows |
| :--- | :--- |
| **Active Queues** | Queues with a current publish or consume rate greater than zero, shown as `active / total` |
| **Publish Rate** | Messages entering the broker right now, in messages per second |
| **Consume Rate** | Messages being delivered to or fetched by consumers right now, in messages per second |
| **Backlog** | Total messages waiting across all queues — the sum of ready and unacknowledged messages |

::: tip
A healthy system can show zero backlog while still flowing. **Backlog shows depth, not throughput.** A fast-draining queue may process thousands of messages per second while maintaining near-zero depth.
:::

## Operational queues

The main table lists all operational queues. Click any row to open the queue's detail page.

| Column | Description |
| :--- | :--- |
| **Name** | Queue identifier |
| **State** | Broker-reported queue state (e.g. `running`) |
| **Activity** | `Flowing` — active publish or consume rate; `Idle` — past activity but none now; `No activity yet` — never used |
| **Messages** | Total depth: ready + unacknowledged |
| **Ready** | Messages waiting to be delivered to a consumer |
| **Unacknowledged** | Messages delivered to a consumer but not yet acknowledged (in-flight) |
| **Consumers** | Number of active consumers connected to this queue |
| **Publish rate** | Messages per second currently entering this queue |
| **Consume rate** | Messages per second currently being delivered from this queue |
| **Published** | Lifetime total of messages published to this queue |
| **Consumed** | Lifetime total of messages consumed from this queue |

### Queue detail

The detail page repeats the same metrics as summary cards and adds a **Peek** action. Peeking loads up to 10 messages from the front of the queue and displays their routing key, payload size, and raw payload. Messages are immediately requeued after being peeked — it is a read-only operation.

## Dead-letter queues

Every operational queue has a corresponding dead-letter queue (DLQ), named `dlq.{queue-name}`. When a message is rejected or cannot be processed — for example because a PSP webhook payload was malformed or a downstream service was unavailable — it is routed to the DLQ rather than being silently dropped.

The DLQ section at the bottom of the main queues page lists all dead-letter queues with the same metrics as the operational table. Click a DLQ row to open its detail page, which shows the failed messages and provides four actions:

| Action | What it does |
| :--- | :--- |
| **Replay** | Move the oldest message back to its source queue for reprocessing |
| **Discard** | Permanently delete the oldest message |
| **Replay all** | Move all messages in the DLQ back to their source queue |
| **Discard all** | Permanently clear the entire DLQ |

Per-message replay and discard are also available directly in the message table rows. All destructive actions require confirmation.

::: warning
Replaying a message re-submits it to the same queue that originally rejected it. If the underlying problem has not been resolved, the message will fail again and return to the DLQ.
:::

---

---
url: /debug-tools/cron-jobs.md
---
# Cron Jobs

The Cron Jobs page lists every scheduled background job registered in Payment Nexus. Use it to confirm that recurring tasks are firing on time or to investigate a job that appears overdue.

Each job runs exactly once per interval, even when multiple instances of Payment Nexus are running simultaneously.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View cron job status | `crons:monitor` + `application:administer` |

## What is shown

The directory is searchable, filterable, sortable, and exportable. Each row represents a registered job:

| Column | Description |
| :--- | :--- |
| **ID** | Internal numeric identifier for the job |
| **Pattern** | Standard 5-field cron expression controlling when the job fires |
| **Last Run At** | Timestamp of the most recent execution |
| **Next Run At** | Timestamp of the next scheduled execution |

Jobs are read-only — there are no manual trigger or enable/disable controls. Schedule changes are made at the application configuration level.

::: tip
If **Next Run At** is significantly in the past, the job may be stuck or the scheduler may have restarted without recovering its state. Compare it against **Last Run At** to gauge how overdue the job is.
:::

## Registered jobs

Payment Nexus registers 14 cron jobs at startup. The majority are **tiered reconciliation jobs** — they ensure that Payment Intent Tickets are kept in sync with PSPs and CRMs. Older tickets are checked less frequently:

| Pattern | Purpose |
| :--- | :--- |
| `* * * * *` | Reconcile tickets from the last 5 minutes |
| `*/5 * * * *` | Reconcile tickets from 5–15 minutes ago |
| `*/5 * * * *` | Update currency exchange rates |
| `*/15 * * * *` | Reconcile tickets from 15–30 minutes ago |
| `*/15 * * * *` | Force CRM reconciliation for all tickets from the last 3 hours |
| `*/30 * * * *` | Reconcile tickets from 30 minutes–1 hour ago |
| `0 * * * *` | Reconcile tickets from 1–3 hours ago |
| `0 */3 * * *` | Reconcile tickets from 3–6 hours ago |
| `0 */6 * * *` | Reconcile tickets from 6–18 hours ago |
| `0 */12 * * *` | Reconcile tickets from 18–36 hours ago |
| `0 0 * * *` | Reconcile tickets from 1–3 days ago |
| `0 0 * * 0` | Reconcile tickets from 3–21 days ago |
| `0 0 1 * *` | Reconcile tickets from 21 days–3 months ago |

The reconciliation jobs work by re-querying the PSP and CRM for the latest payment status and updating tickets accordingly. Recent tickets are checked frequently because they are most likely to change; older tickets are checked just often enough to catch any delayed callbacks or retries.

---

---
url: /debug-tools/versions.md
---
# Versions

The Versions page shows the build-time version information for the Payment Nexus Management UI — what was deployed, where, and from which commit. All values are injected at build time; there is no live API call behind this page.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View version information | `application:versions` |

## What is shown

| Field | Description |
| :--- | :--- |
| **Version** | The build version of the Management UI (e.g. `v2.20260513.0`) |
| **Environment** | The deployment environment (`production`, `staging`, etc.) |
| **Commit SHA** | The Git commit that produced this build |
| **Dependencies** | Versions of key internal packages and framework libraries |

The dependency list shows 11 packages: the `@nhtio/*` internal libraries, plus [Nuxt](https://nuxt.com/), [Vue](https://vuejs.org/), and [Vuetify](https://vuetifyjs.com/). Each entry links to that package's documentation. Versions are read from the pnpm lockfile at build time.

::: tip
When reporting a bug or opening a support ticket, include the **Version** and **Commit SHA** — they uniquely identify the exact build and make it possible to reproduce and diagnose issues.
:::

---

---
url: /releases/2026-06-10/core.md
---

# Core — 10 June 2026

### Changed

* Updated the ValensPay PSP adapter to the latest version.

---

---
url: /releases/2026-06-02/core.md
---

# Core — 2 June 2026

### Added

* Support for Valenspay as a Payment Solution Provider (PSP).
* Ability to enable or disable Tenants and PSPs via the console.

### Changed

* Updated the VirtualPay adapter to the latest version.
* Improved cache handling to ensure changes to Tenants and PSPs are reflected immediately in the UI.

---

---
url: /releases/2026-06-08/core.md
---

# Core — 8 June 2026

### Changed

* Updated the TyltOB PSP adapter to improve integration stability.
* Updated the Antelope CRM adapter packages.

---

---
url: /releases/2026-06-02/management-ui.md
---

# Management UI — 2 June 2026

### Added

* New activation form for managing tenant onboarding and status.

### Fixed

* Corrected text wrapping for PSP activation titles in supported languages.

---

---
url: /releases.md
---

# Release Notes

What's shipped in Payment Nexus, newest first. Select a day to see what changed
across all components.

---

---
url: /releases/2026-06-10.md
---


---

---
url: /releases/2026-06-08.md
---


---

---
url: /releases/2026-06-02.md
---


---

---
url: /debug-tools/webhooks.md
---
# Webhooks

The Webhooks section provides visibility into webhook traffic flowing through Payment Nexus — both requests arriving from external systems and notifications dispatched to tenant or system endpoints.

## Permissions

| Action | Permission required |
| :--- | :--- |
| View webhook logs | `webhooks:monitor` + `application:administer` |
| Reprocess deliveries | `webhooks:manage` + `application:administer` |

## Incoming Webhooks

The **Incoming Webhooks** directory logs all webhook requests received by Payment Nexus from external systems (e.g. PSP callbacks, CRM notifications). Use this to verify that a callback was received, inspect its payload, or diagnose why an expected event did not trigger a downstream action.

## Outgoing Webhooks

The **Outgoing Webhooks** directory logs webhook notifications dispatched by Payment Nexus to tenant-configured endpoints and system-wide webhook endpoints. Use this to verify that a notification was sent, check delivery status, or reprocess a failed delivery.

For configuration details, see [Tenant Webhook Management](/tenants/integration/webhooks) and [System Outbound Webhooks](/administration/system-webhooks/).