overview - AEVI-AppFlow/pos-android-sdk GitHub Wiki
The purpose of the AppFlow solution is to provide acquirers and merchants with flexible and powerful options for shaping their point of sale offering. This includes choices of standalone or integrated environments, a choice of numerous value added services that integrate seamlessly into the point of sale experience and a dynamic offering of payment solutions.
At its core, AppFlow enables applications to be called at different stages of the point of sale journey. What these points are and what applications are called is down to the flow applied to that particular request. The flow applied is determined by the type of the request, such as sale or reversal, which is one of the parameters an initiating application will set when creating a request.
Below is a simplified view of this solution.
As you can see from this diagram, the Flow Processing Service (FPS) is the core component that handles all requests and moves them through a flow. FPS is developed and maintained by AEVI; it can be installed onto any Android (API level 21+) device to facilitate this functionality. Once installed onto a device, developers will be able to use the AppFlow APIs defined here to initiate requests and implement value added services and payment applications. Whereas FPS in this context relates to financial functions, it is in fact agnostic of any particular domain and can be used for any purpose that requires calling a set of applications at different stages of a flow.
Most flows will be customised for the particular function they provide. For instance, a sale flow may be sent through a split stage (to split the bill) but that would not make sense for a refund flow. Flows are fully customisable. The production flows will usually be defined by the bank, acquirer or payment processor distributing AEVI enabled devices.
- Requests from a client app are processed through a flow
- Each flow consists of a number of stages.
- Acquirers, banks and payment processors can define any number of flows. These may be generic, or specific to an acquirer and/or a particular AEVI enabled device.
- Each stage in the flow can optionally execute a number of flow services. These are either statically defined in the flow or dynamically chosen at runtime based on their eligibility for that flow.
- Each flow service will process the data that has been sent to it and pass back a response. The type of data sent between FPS and the flow service for any given stage is determined by the data models for that stage.
If you are developing a client application (POS app), you don't necessarily need to worry about these details, but if you are developing a flow service then these stages indicate the times at which your flow service may be called.
This is explained in more detail in the Flow Stages and Flow Configurations sections.
There are two main groups of applications in AppFlow
- Client (POS) applications - the application used by the merchant to take orders, initiate and manage payments
- Flow services - these application can be called throughout the flow to provide services
Client applications are what the merchant/operator uses to input the details of a transaction, such as choosing items for a customer order or scanning item barcodes. Often this type of application is referred to as a POS app. In AppFlow, these applications make use the Payment Initiation API to create payment requests for processing and receiving the result of that processing.
Client applications have some limited influence over the flow itself. For example they can choose to enable or disable split, pass token details, etc.
Flow services are applications that adhere to the Payment Flow Service API and get called throughout a flow to perform desired functions. FPS will know when to call any given flow service based on the information exposed by the flow service and the flow configuration.
These services can be divided into two main groups;
- Value added services, such as loyalty or split bill
- Payment applications, which processes the actual payments
The latter, payment applications, are in this context defined as flow services that execute in the TRANSACTION_PROCESSING stage. They may optionally also support the PAYMENT_CARD_READING stage where a card may be presented separately to the processing of the payment, to allow for other flow services to react on the given card data, such as token or scheme. These form of applications are typically developed by or on behalf of the acquirer/bank.
The value added services can perform many different tasks that will benefit the merchant and/or customer. Typically these services will augment a request in some way by applying a discount, adding costs such as tax or fees, or in some cases perform operations such as cancelling the transaction. Some examples of value added services are
- loyalty programs
- charity donations
- split bill
- ratings
- advertising and promos
- currency conversion
- receipt printing/emailing
There is no limit on the number of flow services that can be called for any given flow or stage, but in practise it is rarely more than a few to a handful of applications.
If more than one flow service is eligible for a particular stage and a choice is required, FPS will present a selection dialog to the user/merchant allowing them to specify which flow service to use.
AppFlow consists of two separate APIs, each with one or many associated sample apps;
-
Payment Initiation API- Provides general flow and system information and allows apps to initiate financial requests -
Payment Flow Service API- Provides an integration point for flow services to be called throughout the flow
The Payment Initiation API allows an application (typically a POS app) to initiate a payment. It also provides various functions to query the system for information about the flow services and payment services available for use.
This is the API you should be looking at if you are building a POS application.
Please see Implementing POS Apps for detailed information.
The Payment Flow Service API allows for applications to be called throughout the flows and provide capabilities.
This is the API you should be looking at if you are building a value added service, such as loyalty, charity, currency conversion, receipt generation, printing, etc, or if you are building a payment application that can process payments.
Please see Implementing Flow Services for the basic introduction, and then follow on from the next steps defined on that page.
AppFlow has been designed with maximum flexibility in mind to ensure that the APIs do not limit what can be done. This is reflected via the generic Request and Response approach, the use of string constants as opposed to enums in the majority of cases and the ability to pass any custom or bespoke data via the AdditionalData fields in the various API models. The cost of all this flexibility is that it can sometimes be hard to know what data to provide for a request or expect from a response. See Requests & Data for more information.
It should be noted that although the APIs define POJOs for client apps to use, all data is represented as JSON. The POJOs are serialised to JSON whenever it is passed between applications and the system itself is mainly concerned with JSON structures.
The APIs are primarily Java based, but as the underlying representation is JSON there is no real language restriction from a system point of view.
Kotlin is implicitly supported due to its interoperability with Java.
Javascript is on the roadmap.
Other languages (compatible with the JVM) can be supported but may require a translation layer on the client side.
These APIs make extensive use of reactive (Rx) based principles. Therefore in the case of the Java API it makes heavy use of the RxJava library.
To read more about Rx principles and the RxJava library itself see the documentation here. For the remainder of this documentation it is assumed that the reader is familiar with asynchronous and event-based programming using observable streams.