Documentation Index
Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
Use this file to discover all available pages before exploring further.
The AlgoVoi merchant dashboard is the primary web interface for tenants managing their payment operations. It is a React single-page application accessible at dash.algovoi.co.uk. All payment logic remains in the control plane; the dashboard is a display and configuration surface that operates exclusively through authenticated REST API calls to the control plane at api.algovoi.co.uk.
The dashboard is mobile-responsive and tested on desktop (1920×1080 and 1440×900) and tablet (768×1024) form factors.
Authentication and Session Management
Login
Tenants authenticate with email address and password. Multi-factor authentication (TOTP) is required at login. TOTP seeds are encrypted at rest using the platform’s document encryption key.
Session Model
| Parameter | Value |
|---|
| Session token type | JWT (signed HS256 by default; configurable to HS384 or HS512 per tenant tier) |
| Token lifetime | Configurable; default 8 hours |
| Refresh mechanism | Silent automatic refresh when token has less than 15 minutes remaining |
| Inactivity timeout | 30 minutes of inactivity triggers session expiry |
| Concurrent sessions | Permitted; each device receives an independent JWT |
Password Reset
Password reset is available via a time-limited email token. Token lifetime is 30 minutes. Token is single-use: it is invalidated on first use regardless of whether the password change completes. Password reset requires MFA confirmation if MFA is already enrolled. Resets are recorded in the audit_log chain.
MFA
TOTP-based MFA using RFC 6238 (TOTP) and RFC 4226 (HOTP). Compatible with Google Authenticator, Authy, Microsoft Authenticator, and any RFC 6238-compliant authenticator application. Setup generates a QR code encoding the provisioning URI. Recovery codes are generated at setup and are displayable once; they are hashed before storage.
Navigation Structure
The dashboard is divided into eight primary sections accessible from the left navigation panel:
| Section | Purpose |
|---|
| Payments | Full payment history across all chains and protocols |
| Checkout Links | Hosted payment link management |
| Mandates | Recurring mandate management |
| Recurring Authorities | Tier 2 standing authority management |
| Webhooks | Webhook endpoint configuration and delivery logs |
| API Keys | API key lifecycle management |
| KYC / KYB | Identity verification and compliance status |
| Settings | Account settings, security, and GDPR controls |
Payments Section
The payments section provides a full searchable, filterable history of all payments received by the tenant across all chains, assets, and protocols.
Filters
| Filter | Type | Values |
|---|
| chain | enum multi-select | algorand, voi, hedera, stellar, base, solana, tempo |
| asset | string | CAIP-19 asset identifier or display ticker (e.g. USDC) |
| date_from | date | ISO 8601 date |
| date_to | date | ISO 8601 date |
| status | enum | verified, reversed, disputed, pending |
| protocol | enum multi-select | checkout, x402, mpp, ap2, a2a, recurr |
| min_amount | decimal | Minimum amount in display currency (GBP equivalent) |
| max_amount | decimal | Maximum amount in display currency (GBP equivalent) |
Payment List Fields
Each row in the payments list displays:
| Field | Description |
|---|
| payment_id | Truncated UUID with copy-to-clipboard |
| tx_id | On-chain transaction ID, truncated, links to chain explorer |
| chain | Chain badge with chain icon |
| asset | Asset ticker |
| amount | Display amount with currency symbol |
| payer_address | Masked: first 6 and last 4 characters visible; full address available on expand |
| verified_at | Human-readable relative timestamp with ISO 8601 on hover |
| protocol | Protocol badge |
| status | Status badge (verified / reversed / disputed) |
| audit_chain_link | Link to the corresponding payment_ledger row in the audit bundle viewer |
Payment Detail Panel
Clicking any payment row opens a side panel with:
| Field | Description |
|---|
| Full payment_id | Full UUID, copyable |
| Full tx_id | Full on-chain transaction ID, copyable, with chain explorer link |
| Full payer_address | Full wallet address, copyable |
| chain_position | The chain_position of this row in the payment_ledger audit chain |
| content_hash | The SHA-256 content hash of this row, copyable |
| Settlement attestation | Link to the draft-hopley-x402-settlement-attestation receipt for this payment |
| Compliance receipt | Link to the compliance receipt (ALLOW / REFER / DENY) for this payment |
| Refund receipt | Present only if a refund was issued |
| Cancellation receipt | Present only if this payment was part of a cancelled mandate |
CSV Export
The full filtered payment history is exportable as CSV. The export includes all fields visible in the payment detail panel. Payer addresses are included in full in exports (not masked). Exports are recorded in the audit_log chain.
Checkout Links Section
List View
Each checkout link displays:
| Field | Description |
|---|
| token | The short token used in the hosted checkout URL (dash.algovoi.co.uk/pay/) |
| amount | Display amount |
| chain | Target chain |
| asset | Asset ticker |
| status | pending, paid, expired, or cancelled |
| created_at | Creation timestamp |
| paid_at | Payment timestamp (null if unpaid) |
| redirect_url | Destination after successful payment (masked to domain only in list view) |
Create Link
The link creation form accepts:
| Field | Type | Required | Description |
|---|
| amount | decimal | Yes | Payment amount |
| asset_id | string | Yes | CAIP-19 asset identifier |
| chain | enum | Yes | Target chain |
| redirect_url | string | Yes | Post-payment redirect destination. Validated against URL threat-intelligence feeds at creation time. |
| description | string | No | Shown to payer on hosted checkout page |
| expires_at | timestamp | No | Link expiry. If null, link does not expire. |
| metadata | object | No | Arbitrary key-value pairs attached to the payment on completion |
QR Code
Every checkout link has a QR code available on the detail view. The QR code encodes the full hosted checkout URL. It is downloadable as SVG or PNG at 512×512 pixels.
Re-Use
The re-use button on any existing link opens the create form pre-populated with the same amount, asset, chain, and description. redirect_url and expiry must be re-entered.
Mandates Section
The mandates section shows all recurring mandates associated with the tenant, across all lifecycle states.
Mandate List Fields
| Field | Description |
|---|
| mandate_id | Truncated UUID |
| payer_address | Masked wallet address |
| chain | Chain badge |
| asset | Asset ticker |
| cap_display | Cap amount in display currency |
| period | Human-readable period (e.g. “every 30 days”) |
| status | Status badge: pending, active, paused, revoked, expired, cancelled |
| next_due_at | Next scheduled pull timestamp |
| last_pull_at | Most recent successful pull timestamp |
Mandate Detail Panel
| Field | Description |
|---|
| Full mandate_id | Full UUID |
| Full payer_address | Full wallet address |
| activated_at | Activation timestamp |
| cancel_at | Scheduled cancellation date (if set) |
| cancel_reason | Cancellation reason (user_requested, merchant_requested, compliance_terminated, expired) |
| Pull history | Ordered list of all pull attempts with tx_id, amount, status, and timestamp |
| Cancellation receipt | Link to draft-hopley-x402-cancellation-receipt (present once cancelled) |
Safeguard Indicators
The mandate detail panel displays the three platform-wide safeguards as status indicators:
- Per-mandate cap: £100 maximum (enforced at control plane level)
- Per-account cap: £300 maximum across all active mandates for this payer account
- Maximum concurrent mandates: 3 per account
These limits are not configurable at tenant level. They are EMR 2011-aligned safeguards.
Cancel Mandate
Tenants can cancel an active or paused mandate via the dashboard. Cancellation records cancel_reason as merchant_requested. A cancellation receipt (per draft-hopley-x402-cancellation-receipt) is emitted automatically. The receipt is linked from the mandate detail panel and is also dispatched via the mandate.cancelled webhook event.
Recurring Authorities Section
Tier 2 standing authorities are higher-autonomy recurring arrangements where an AI agent or automated system pulls payments on a schedule against a pre-authorised cap, without re-requesting authorisation per pull.
Authority List Fields
| Field | Description |
|---|
| authority_id | Truncated UUID |
| payer_address | Masked wallet address |
| chain | Chain badge |
| asset | Asset ticker |
| cap_display | Lifetime or period cap in display currency |
| per_cycle_display | Per-pull maximum in display currency |
| period | Human-readable period |
| status | active, paused, revoked, or expired |
| next_due_at | Next scheduled pull |
| last_pull_at | Most recent successful pull |
Manual Pull
For catch-up or proration scenarios, a manual pull can be triggered from the authority detail panel. Manual pulls are subject to the same per_cycle_microunits cap as scheduled pulls. Manual pull events are recorded in the payment_ledger and negotiation_trace_events chains.
Pause and Resume
An active authority can be paused (no further scheduled pulls until resumed). A paused authority can be resumed. Both transitions are recorded in the compliance_events chain with actor and timestamp.
Webhooks Section
Webhook List Fields
| Field | Description |
|---|
| webhook_id | UUID |
| url | Destination URL (domain only visible in list; full URL visible on detail) |
| events | Array of subscribed event types |
| status | active or disabled |
| success_rate_7d | Percentage of successful deliveries in the past 7 days |
| last_delivery_at | Timestamp of most recent delivery attempt |
| last_delivery_status | success or failed |
Webhook Events
Tenants subscribe to specific event types. Available event types:
| Category | Event Types |
|---|
| Payments | payment.verified, payment.reversed, payment.disputed |
| Compliance | screening.hit, screening.flagged, kyc.approved, kyc.rejected, mainnet.activated, mainnet.suspended |
| Mandates | mandate.activated, mandate.charged, mandate.charge_failed, mandate.paused, mandate.revoked, mandate.expired, mandate.cancelled |
| Subscriptions | mpp_subscription.activated, mpp_subscription.charged, mpp_subscription.charge_failed, mpp_subscription.revoked, mpp_subscription.expired |
| Webhooks | webhook.delivery_failed (meta-event; always fires regardless of subscription) |
Delivery Statistics
The webhook detail panel shows:
| Metric | Description |
|---|
| Total deliveries | Lifetime count |
| Success count | HTTP 2xx responses |
| Failure count | Non-2xx responses or connection failures |
| Success rate (7d) | Rolling 7-day percentage |
| Average response time (7d) | Rolling 7-day average in milliseconds |
Delivery Log
The live delivery log shows the 100 most recent delivery attempts for each webhook endpoint:
| Column | Description |
|---|
| event_type | The event type that triggered this delivery |
| event_id | UUID of the specific event instance |
| attempted_at | Timestamp |
| http_status | Response status code (or connection_error / timeout) |
| response_body | First 512 characters of the response body |
| duration_ms | Round-trip time in milliseconds |
Test Delivery
The test delivery button sends a synthetic event of the selected event type to the webhook endpoint. Test deliveries are distinguishable by the event_id prefix test_. They are recorded in the delivery log but not in the audit chain.
Secret Rotation
Webhook payloads are signed with HMAC-SHA256 using a per-webhook secret. The dashboard provides:
- Generate new secret: immediately valid; old secret remains valid for a configurable grace period (default 24 hours) to allow recipient systems to rotate
- Grace period indicator: countdown to old secret expiry
- Revoke old secret immediately: terminates the grace period
The signing header format is: X-AlgoVoi-Signature: algvw_
API Keys Section
Key List Fields
| Field | Description |
|---|
| key_id | UUID |
| name | Human-assigned label |
| prefix | First 12 characters of the key (displayed permanently; full key shown once at creation only) |
| scopes | Array of authorised scopes |
| created_at | Creation timestamp |
| last_used_at | Timestamp of most recent authenticated request |
| status | active or revoked |
Scopes
At key creation, the tenant selects the minimum set of scopes required for the intended use. Available scopes include (but are not limited to):
| Scope | Access Granted |
|---|
| payments:read | Read payment history |
| payment_links:write | Create and manage checkout links |
| webhooks:write | Register and manage webhook endpoints |
| mandates:read | Read mandate state |
| mandates:write | Create and manage mandates |
| recurring:write | Manage standing authorities and trigger manual pulls |
| compliance:read | Read compliance and screening status |
| kyc:read | Read KYC/KYB status |
Key Lifecycle
Keys are shown in full only at creation. After the creation modal is dismissed, only the prefix is visible. Tenants should store keys in a secrets manager at creation time.
Key revocation is immediate. All requests authenticated with a revoked key are rejected with HTTP 401. Revocation is recorded in the audit_log chain.
KYC and KYB Section
KYC Status Tracker
The KYC section displays the current verification state as a progress indicator:
| State | Display | Description |
|---|
| not_started | Grey | No documents submitted |
| pending | Yellow | Documents in upload queue |
| submitted | Blue | Documents submitted; awaiting review |
| approved | Green | KYC approved; mainnet access granted (subject to mainnet_active flag) |
| rejected | Red | KYC rejected; reason displayed; re-submission available |
| expired | Orange | Periodic re-verification required |
Document Upload
Accepted document types:
- Passport (any ICAO-compliant jurisdiction)
- National identity card (EU, EEA, and other accepted jurisdictions)
- Driving licence (UK, EU, and other accepted jurisdictions)
Document requirements:
- JPEG, PNG, or PDF
- Maximum 10 MB per file
- All four corners must be visible
- No glare, obstruction, or cropping
Liveness check:
- Selfie video capture in-browser
- Anti-spoofing: printed photo, screen replay, and 3D mask detection
- Face-match against uploaded document photo
All documents are encrypted at rest immediately on receipt. Uploaded documents are not viewable in the dashboard after submission. The dashboard shows a submission receipt only.
KYB (Company)
Company applicants complete the KYB form with the following structure:
Section 1 — Company Details:
company_name, registered_number, jurisdiction_of_incorporation, registered_address (object: line1, line2, city, postcode, country), trading_name (if different), business_description, industry_sector (enum), years_in_operation, company_website
Section 2 — Beneficial Owners:
Array of UBO objects, one per beneficial owner with ownership exceeding 25%.
UBO object fields: full_name, date_of_birth, nationality, country_of_residence, ownership_percentage, is_director (boolean), is_pep (boolean, self-declared), document_type, document_reference
Section 3 — Financial Profile:
source_of_funds (enum: trading_revenue, investment_income, sale_of_assets, loan_proceeds, other), source_of_funds_description, anticipated_monthly_volume_gbp (enum: under_1000, 1000_to_10000, 10000_to_100000, over_100000), anticipated_payment_types (multi-select enum)
Section 4 — Documents:
certificate_of_incorporation, latest_filed_accounts (most recent full-year accounts), proof_of_trading_address (utility bill or bank statement dated within 3 months), ultimate_beneficial_owner_register_extract (where jurisdiction requires public UBO register)
Rejection and Re-Submission
If KYC or KYB is rejected, the rejection reason is displayed in generic form (consistent with SAMLA s.20 and GDPR data minimisation). Re-submission is permitted. Previous submissions are archived in the encrypted documents store.
Hosted Checkout Page
The hosted checkout page is accessible at dash.algovoi.co.uk/pay/ and is the payment surface shown to end customers.
Page Fields Displayed to Payer
| Field | Description |
|---|
| merchant_name | The tenant’s display name |
| amount | Display amount with asset ticker |
| chain | Target chain with chain icon |
| description | Optional description set by merchant at link creation |
| expires_at | Countdown timer if link has an expiry |
Wallet Connection Options
Connection options are presented per target chain:
| Chain | Wallet Options |
|---|
| Algorand | Pera Wallet, Defly, WalletConnect generic |
| VOI | Kibisis, WalletConnect generic |
| Solana | Phantom, Solflare, Backpack |
| Hedera | HashPack, Blade Wallet |
| Stellar | Freighter, LOBSTR |
| Base | MetaMask, WalletConnect generic, Coinbase Wallet |
| Tempo | MetaMask, WalletConnect generic |
xChain Option
A separate xChain tab allows the payer to pay from any supported EVM chain, routing settlement to the merchant’s target chain via Allbridge or CCTP V2 (Solana-destination). The payer selects their source chain and connects their source-chain wallet. The xChain flow:
- Payer selects source chain and connects source wallet
- Platform displays the bridged amount required on the source chain (accounting for bridge fees)
- Payer approves and signs the bridge transaction in their source wallet
- Platform monitors the bridge settlement and confirms receipt on the destination chain
- Payment is marked verified on the destination chain; redirect fires
Payment Status Polling
The hosted checkout page polls the payment status endpoint every 3 seconds after transaction submission. Status progression:
| Status | Display |
|---|
| pending | Spinner with “Waiting for confirmation…“ |
| confirming | Spinner with “Transaction detected, confirming…“ |
| verified | Green tick with “Payment confirmed” followed by redirect |
| failed | Red X with error message and retry option |
| expired | Orange clock with “This payment link has expired” |
Compliance Panel
The Compliance panel is accessible from the dashboard footer and from the KYC section.
| Item | Description |
|---|
| Current risk_tier | Badge with tier label and description |
| kyc_status | Current KYC status badge |
| mainnet_active | Boolean indicator |
| Audit chain heads | Live chain_position and content_hash for all five audit chains, refreshed every 60 seconds |
| Sanctions screening status | Last screening timestamp; flag if any pending MLRO review |
| Feed refresh timestamps | Last refresh time for each of the seven threat-intel feeds and three sanctions lists |
| Link to GET /compliance/attestation | Opens the raw JSON attestation in a new tab |
Audit Bundle Download
Tenants can download a scoped audit bundle directly from the Compliance panel. The download form accepts:
| Field | Type | Description |
|---|
| chain | enum | Which audit chain to bundle (or all) |
| date_from | date | Start of the requested window |
| date_to | date | End of the requested window |
| include_bridging_rows | boolean | Include rows needed to prove chain continuity (recommended: true) |
Settings Section
Account Settings
| Setting | Description |
|---|
| Display name | Tenant display name shown on hosted checkout pages and receipts |
| Email address | Primary contact email. Change requires re-verification via email link. |
| Notification preferences | Which dashboard-side email notifications to receive |
| Timezone | Display timezone for timestamps throughout the dashboard |
| Tenant ID | Non-editable UUID (needed for MCP server configuration) |
| Tenant short ID | Non-editable short identifier (used in MPP resource URLs) |
Security Settings
| Setting | Description |
|---|
| Password | Change password; requires current password + MFA confirmation |
| MFA | View TOTP setup; regenerate recovery codes; reset MFA (requires re-authentication) |
| Active sessions | List of all active JWT sessions with device hint and last activity; individual sessions can be revoked |
| Revoke all sessions | Revokes all active JWTs across all devices |
GDPR Controls
| Control | Description |
|---|
| Subject Access Request | Download a machine-readable copy of all personal data held about this account, excluding identity documents in encrypted document storage (covered separately by the document retention policy) |
| Erasure Request | Request deletion of personal data from live systems. Processed within 30 days. UK MLRs Reg 40 data retained in B2 Object Lock is outside erasure scope; this is documented in the request confirmation. |
