bopen Documentation

Welcome to the bopen documentation — the open banking A2A acquiring platform.

Last updated

21 July 2026 — Platform migrated to dev.bopen.tech on a fresh Control Tower managed account. Full three-dashboard suite deployed: Product Owner Portal (admin.dev.bopen.tech), expanded Acquirer Portal (acquirer.dev.bopen.tech), and new Payer Hub (my.dev.bopen.tech). SES fully live with DKIM verified. New features: dispute & refund management engine, widget branding studio, team RBAC, PDF settlement export, VRP mandate management, payer magic-link auth (email + SMS). See Getting Started for the current live URLs.

What is bopen?

bopen is a production-grade open banking platform connecting merchants to UK bank accounts via Open Banking / PSD2 A2A payment rails:

• Checkout Widget — 5-screen vanilla JS SPA (consent → bank → handoff → polling → receipt); QR on desktop, deep link on mobile; Quick Pay for returning payers; HMAC-signed webhook callbacks (apps/web/public/widget/)
• Consumer Checkout — multi-step Next.js payment flow with bank selection and SCA handling (apps/web)
• Product Owner Portal — Platform super-admin at admin.dev.bopen.tech — cross-tenant analytics, KYB control, ASPSP health matrix, dispute resolution
• Acquirer Portal — B2B merchant dashboard at acquirer.dev.bopen.tech — transactions, settlements, disputes, widget branding, team RBAC, developer tools
• Payer Hub — Consumer consent dashboard at my.dev.bopen.tech — magic-link auth, VRP mandate management, payment history, self-service disputes
• Dispute & Refund Engine — OBL-aligned dispute lifecycle: payer raises → merchant responds → platform resolves; webhooks on state changes
• Payment Service — Rust/Axum microservice: payment lifecycle, JWT validation, Keycloak realm provisioning, admin + payer APIs (services/payment-service)
• Keycloak IAM — ECS Fargate, FAPI baseline, realm-per-merchant for merchants, separate bopen-platform realm for internal staff
• Database — Versioned PostgreSQL migrations (001–013); consent-vs-execution model; keycloak_core schema isolated within shared RDS
• Infrastructure — CloudFormation IaC for AWS VPC, ECS, RDS, Amplify (5 apps), Keycloak, SES (infra/cloudformation)

Quick links

Area	Location	Description
Checkout Widget	apps/web/public/widget/	Embeddable 5-screen iframe widget
Widget loader	apps/web/public/v1/checkout.js	Single-script merchant integration
Webhook Engine	services/payment-service/src/webhook.rs	HMAC-SHA256 dispatch + retry scheduler
Product Owner Portal	apps/web/src/app/admin/	Platform super-admin dashboard
Acquirer Portal	apps/web/src/app/portal/	B2B merchant dashboard
Payer Hub	apps/web/src/app/payer/	Consumer consent & dispute hub
Payment Service	services/payment-service	Rust payment lifecycle + dispute + payer API
Keycloak stack	infra/cloudformation/templates/keycloak.yaml	IAM ECS deployment
SES stack	infra/cloudformation/templates/ses.yaml	Email domain + SMTP (live)
Admin Amplify	infra/cloudformation/templates/amplify-admin.yaml	admin.dev.bopen.tech
Portal Amplify	infra/cloudformation/templates/amplify-portal.yaml	acquirer.dev.bopen.tech
Payer Amplify	infra/cloudformation/templates/amplify-payer.yaml	my.dev.bopen.tech
Database Scripts	database/scripts	Roles, migrations (001–013), seed SQL
OpenAPI	openapi-3-0.yaml	Open Banking API specification

Data model

The PostgreSQL schema uses a consent-vs-execution model — a payment_consent is the user's authorisation grant from the bank; payment_intents are the physical executions linked to it. Migration 013 added the dispute & payer auth tables.

merchants ──< merchant_bank_accounts
    │         (+ branding_config JSONB, payout_held flag)
    │
    ├──< payment_consents  (SINGLE_IMMEDIATE | VARIABLE_RECURRING via control_parameters JSONB)
    │              │
    │              └──< payment_intents  (gross/fee/net amounts, end_to_end_id, refunded_amount)
    │                         │
    │                         ├──< payment_events  (append-only; changed_by, ordinal)
    │                         └──< disputes        (opened_by, reason, status, evidence)
    │
    └──< webhook_deliveries  (transactional outbox; exponential backoff; DEAD → replay)

bopen.payer_tokens    ── magic-link tokens for Payer Hub (SHA-256 hash, 10-min expiry)
bopen.platform_users  ── internal staff linked to bopen-platform Keycloak realm (OWNER/OPS/SUPPORT)
keycloak_core.*       ── Keycloak session/realm state (isolated schema, separate DB user)

See Database Schema for the full ER model, state machines, and migration run order.

IAM model

Two Keycloak realms serve different user populations:

• Merchant realms — Each acquirer gets a dedicated realm at auth.dev.bopen.tech/realms/{slug}. The payment API validates Bearer tokens (azp claim → merchants.client_id). New merchants self-register at /portal/register.
• bopen-platform realm — Internal bopen staff (OWNER / OPS / SUPPORT roles). Used for the Product Owner Portal. See Setting up the platform realm.
• Payer sessions — Magic-link based; HMAC-signed JWTs (not Keycloak). 15-minute session, stored in sessionStorage.

See Identity & Access Management for the full IAM architecture.

API documentation

The Open Banking API reference is generated from openapi-3-0.yaml and covers all endpoints, schemas, and environment base URLs.

Getting started

See the Getting Started guide to set up your local development environment and run the full stack.