OBP-API for multi-bank Open Banking integrations

OBP-API's bank integration boundary

OBP-API addresses a specific integration problem: banking applications often need consistent account and payment operations even when the banks behind them use different core banking systems. The README says the platform abstracts away those system-specific characteristics so applications can interact with multiple banks on behalf of account holders. Its intended users are banks, financial application developers, and service teams building around Open Banking, XS2A, PSD2, or Open Finance.

The API surface is broader than a read-only account interface. The repository description includes accounts, transactions, counterparties, payments, entitlements, metadata, and internal banking and management APIs. OBP-API also supports configurable transaction views that account holders can share with trusted people or the public. It provides mechanisms for blurring sensitive information and enriching transactions with tags, comments, and images. These features make the platform relevant to products that need permissions and presentation controls around banking data, rather than only a standardized balance lookup.

This breadth also defines a boundary. OBP-API is not documented as a hosted data service that connects to every bank automatically. The README refers to connector configuration and mapped tests, but it does not provide a complete connector catalog or claim universal core banking compatibility. An adopting bank must verify that its own banking platform can be integrated and determine how much connector or mapping work remains.

Authentication choices and API version policy

OBP-API supports OAuth 2, OpenID Connect OIDC, Direct Login, and other authentication methods. OAuth 1.0a is no longer supported, so an existing client based on that protocol would need to change rather than treat OBP-API as a drop-in backend. Authentication selection affects client registration, token handling, and the permissions an application must request, which makes this an early architecture decision.

A single OBP instance can expose multiple API versions unless configuration deactivates them. The README directs users to a versioned root endpoint, such as `/obp/v2.0.0/root` or `/obp/v3.0.0/root`, to inspect status. Its history marks versions from `V1.2.1` through `V5.0.0` as stable on different calendar dates. Those examples describe sandbox history, not a guarantee that every production operator enables every version. The deployed properties configuration remains the controlling layer.

Version coexistence creates flexibility and upgrade work. Applications can remain aligned with an existing version while other clients move elsewhere, but operators must decide which versions remain enabled and manage behavior across them. The README does not provide an endpoint-level compatibility matrix. Client implementers should therefore inspect the root endpoint for their deployed instance and use the OBP API Explorer or imported Swagger definitions rather than assuming that every similarly named operation is unchanged.

Building the OBP-API http4s server

The documented local build targets JDK 25 (LTS), Scala 2.12.21, and Maven 3. The sdkman command reads the project configuration and installs the requested JDK. The README says that any OpenJDK 25 distribution is suitable and names Eclipse Temurin 25 and Azul Zulu 25 as examples.

If sdkman is already installed, use the repository's version definition to install that JDK:

sdk env install

After installing the JDK, build the `obp-api` module and its dependencies from the project root. This documented command skips both test layers and starts the packaged server:

MAVEN_OPTS="-Xms3G -Xmx6G -XX:MaxMetaspaceSize=2G" mvn -pl obp-api -am clean package -DskipTests=true -Dmaven.test.skip=true && \
java -jar obp-api/target/obp-api.jar

The memory settings reserve heap and metaspace space for the build and server. The http4s server reads `hostname` and `dev.port` from its properties file. Their documented defaults are `127.0.0.1` and `8080`, so a default local launch binds to the loopback interface on port 8080. The README does not document a complete first request with credentials, account context, or an expected response body. The versioned root endpoint is the documented place to inspect an API version's status.

The thin jar deployment constraint

The `obp-api.jar` produced by the documented build is not self-contained. Its runtime dependencies are copied into the sibling directory `obp-api/target/lib/`, while the jar manifest points to that directory through a `Class-Path` entry. Deploying only the jar breaks this arrangement. The artifact unit that must be copied is the jar together with `obp-api/target/lib/`.

This packaging choice affects continuous delivery, container images, and release directories. A deployment process that assumes `java -jar` can accept one binary file will fail unless it preserves the sibling library directory. The README also states that the manifest includes required `Add-Opens` entries for CGLib proxy generation, Kryo serialization, Pekko remoting, and Scala runtime reflection. Under `java -jar`, those manifest entries apply automatically.

That behavior changes when the application is launched through a custom classpath because manifest attributes are not honored in the same way. The repository documents a longer command that opens the relevant `java.base` packages and names `bootstrap.http4s.Http4sServer` as the entry point:

java --add-opens java.base/java.lang=ALL-UNNAMED \
     --add-opens java.base/java.lang.reflect=ALL-UNNAMED \
     --add-opens java.base/java.util=ALL-UNNAMED \
     --add-opens java.base/java.lang.invoke=ALL-UNNAMED \
     --add-opens java.base/java.util.jar=ALL-UNNAMED \
     --add-opens java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED \
     --add-opens java.base/java.io=ALL-UNNAMED \
     --add-opens java.base/java.util.concurrent=ALL-UNNAMED \
     --add-opens java.base/java.security=ALL-UNNAMED \
     -cp "obp-api/target/obp-api.jar:obp-api/target/lib/*" bootstrap.http4s.Http4sServer

Custom launchers must preserve those module-opening flags or reproduce the manifest configuration. This is a concrete maintenance boundary for replacing the documented launcher.

Connector setup and selective test execution

OBP-API does not eliminate bank-specific implementation work. Its stated purpose is to place a common abstraction above different core systems. The test instructions expose one concrete configuration choice: create `obp-api/src/main/resources/props/test.default.props` and set `connector=mapped`. The repository also includes a `test.default.props.template`, and the README advises disabling tests that do not fit a local setup, with `bank_account_creation_listener=false` given as an example.

For command-line test work, the README first shows how to set JVM options:

export MAVEN_OPTS="-Xmx3000m -Xss2m"

It then gives this command for one named ScalaTest suite:

mvn -DwildcardSuites=code.api.directloginTest test

The full test run writes output to `obp-api-test-results.txt`:

export MAVEN_OPTS="-Xss128m" && mvn clean test | tee obp-api-test-results.txt

The root repository also includes `run_specific_tests.sh`, `run_all_tests.sh`, and `run_tests_parallel.sh`, but the README does not document their arguments or explain when each should be used. Their interfaces should be inspected before placing them in automation.

A passing local test would not establish compatibility with every bank. The README does not identify a complete list of supported core banking products, required credentials, credential rotation procedures, or the complete mapping configuration format. Those omissions prevent a firm compatibility judgment for a particular institution.

OBP-API versus a direct bank integration

The meaningful alternative is not another named product. It is the conventional approach in which an application integrates directly with one bank's core system or published banking API. That approach can produce a smaller surface area when there is only one bank, one fixed API version, and no requirement to expose a reusable multi-bank layer.

OBP-API takes a different architectural position. It places standardized or configurable banking resources in front of heterogeneous core systems and adds access control, entitlements, transaction sharing, data blurring, and enrichment. The benefit is reuse across banks and a common surface for applications acting for account holders. The cost is a larger server, connector and mapping configuration, version policy, authentication selection, and a substantial test environment.

For a single-bank deployment with no reuse plan, that abstraction may outweigh the benefit. For an organization operating multiple banking integrations or exposing a broad catalog to internal and external consumers, the common interface is the main reason to consider OBP-API. The decision should be tied to the number and variety of connectors required, not to the project's support for Open Banking terminology alone.

Maintenance and dual-license obligations

The repository is not archived, and its last push was on 2026-10-16. It has no GitHub releases, so release discovery and upgrade planning cannot rely on a documented GitHub release history. The default branch is `develop`, which matters when evaluating whether a deployment should track that branch directly. The README does not state the production branching or release support policy, so deployment teams need confirmation from maintainers before treating `develop` as a production branch.

Licensing requires separate review. The project is dual licensed under the AGPL V3 and commercial licenses from TESOBE GmbH. An adopter must examine both the repository license and the commercial terms applicable to its intended use. This article does not interpret those legal obligations. Teams that require a different licensing arrangement cannot assume the AGPL route alone satisfies their policy.

Operationally, owners must account for Maven dependency upgrades, Scala code compatibility, properties files, connector mappings, enabled API versions, authentication configuration, and preservation of `obp-api/target/lib/`. The thin jar layout makes deployment discipline especially concrete: every upgrade must verify the jar and dependency directory are replaced as one unit, then confirm the configured hostname and port at startup.

Editorial conclusion

Banks and fintech teams that need a shared API layer across several core banking systems should evaluate OBP-API after confirming connector availability, authentication requirements, and deployment ownership. Organizations seeking a small standalone XS2A adapter should first inspect the connector implementation because OBP-API is a broad API platform, not a minimal protocol frontend. The first project-specific check is whether the intended core banking system has a suitable connector and whether the required endpoint versions are enabled in configuration.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. OpenBankProject/OBP-API on GitHub
4. Project website
5. README