Waller API Documentation

Key concepts

Waller is first and foremost an OpenAPI aggregation and normalization service. It aims to provide a unified interface which mobile clients (iOS/Android) can use for any partner bank integration without modifying their mechanics.

Security considerations

Waller should not know any long-lived user secrets. In this sense the mobile client is responsible for obtaining an authentication parameter (short-lived secret such as a JWT token) directly from a partner bank using a user's login/password (or any other form of long-lived secrets) combination or any other mechanism implemented by the partner. The client then passes this authentication parameter to the Waller service when making requests. This is done intentionally to minimize risks related to keeping user secrets in backend systems.

When this is not possible because the partner implements a mechanism such as mTLS or non-proxyable data, please communicate with us to find the correct delegation mechanic which should be implemented. In this sense a bank's customer DELEGATES waller to act on his behalf without disclosing any long-lived secrets provided by the partner bank.

Architecture overview

Waller provides a REST-API to mobile clients (iOS/Android) which use it to submit three main types of requests ()

  1. Listing available accounts a user holds at a partner bank
  2. Listing transactions for an account held at a partner bank
  3. Submitting transactions for execution for an account held at a partner bank

This is the minimal set of operations expected to be supported by a partner. Some partners may have larger scopes (subscribe to products, brokerage, etc...) - in this case please contact us directly for us to support such features.

Upon receiving a request through the REST-API it is sent over ZMQ asynchornously (publishes) to the adapter responsible for communication with the partner bank's back-end. The REST request has a hard timeout of 30 seconds to receive a response for a given task (otherwise it responds with a 504 error code).

Upon receiving the request the adapter performs the corresponding operations to honor it and publishes the result back to the Waller systems. The data is exchanged is using an envelope-payload format, where the envelope contains data specific to the ZMQ message and the payload is the actual result of the operation where the adapter has mapped the DTO received from the partner bank into a Waller DTO.

Building an adapter to a new partner bank

Please refer to the Swagger page to find the exact definitions of the DTOs.

Requests (DTOs sent by Waller to the Adapater)

Responses (DTOs you will send to Waller from the Adapter)

!!! IMPORTANT NOTICE ABOUT SUBMITTING TRANSACTIONS TO PARTNER BANKS !!!

When receiving a AsyncTransactionRequest from Waller, please inject the transactionId into a field which is supported field by the partner bank (this can be a memo field or anything provided by them). This is the only way to track transactions submitted by us. Only Waller-to-Waller transactions should be persisted, all other transactions are not to be stored in the database. The identifier returned by the bank should be stored as well if one is returned.

We no longer expect to receive a response from an adpater when submitting a transaction for exeution via the REST-API - this operation is fully asynchronous. The method simply returns back the transaction object back to the client with the identifier assigned by Waller. Its state can be later obtained by requesting a list of transactions.