Flow Configurations - AEVI-AppFlow/pos-android-sdk GitHub Wiki

A flow configuration is a JSON structure that defines the flow meta-data, what stages it consists of and what applications to call for each stage, if any. See Example Flows for what a fully fledged sale flow and a standard generic flow might look like.

These flow configurations are created by AEVI and/or the acquirers and are bundled inside a Flow Configuration Provider (FCP), which is an application responsible for providing FPS and other components with runtime configuration details.

How AppFlow behaves is defined via these flow configurations, such as

  • What types of requests are supported (sale, refund, tokenisation, etc)
  • What flow services get called for any particular flow/type, in any given stage
  • What the rules of application selection are if there is more than one flow service for a stage

What flows are created and what they look like for any given environment is generally down to the acquirer and enabled device requirements. It is common for acquirers to offer app bundles via their various merchant offerings, in which case there is a set of flows associated with each bundle.

For development and testing purposes, we offer a special type of flow config provider as part of this SDK that allows developers to configure the flows dynamically via a user interface.

Flow name vs type

A flow has both a name and a type associated with it. This is due to the fact that AppFlow supports multiple flows per type, to allow for scenarios where different stages and/or applications can be used with the same type. As an example, there may be two different sale flows each with a different loyalty scheme and the merchant initiates the relevant one based on what scheme the customer is signed up with.

Clients must provide the flow type at a minimum, and optionally a flow name to explicitly specify what flow to use. If no name is provided and there are multiple flows available for the given type, a dialog will be presented allowing the merchant to select the desired flow.

Custom types

In addition to the pre-defined flows, FPS will also create ad-hoc flows dynamically based on the custom request types reported by the flow services. These are generic flows which typically only call a single application. It is however possible for more than one application to support a custom type, in which case the app selection will be done according to SINGLE_SELECT rules, described below.

If a flow service that has defined a custom request type is uninstalled or no longer defines it, the associated flow will also be removed.

App execution types

The flow configuration defines a field called appExecutionType that is associated with each stage. This determines how FPS will execute the applications in that stage.

  • SINGLE - Only a single application can be defined
  • SINGLE_SELECT - Multiple applications can be defined and runtime filtering and/or selection will determine one
  • MULTIPLE - Multiple applications can be defined and they will be called one by one in order of definition
  • DYNAMIC_SELECT - This is a special dev/test type (not allowed in prod) that can have an empty list of apps for full runtime selection of eligible apps

Initiating a flow

For client / POS applications, it is important to understand the relationship between a particular POS/payment function and the flow configurations.

In order to initiate any form of request, the flow type has to be provided. However, since AppFlow supports multiple flows per type, it is also possible to specify the flow name to select one specific flow.

There are two ways for POS applications to determine what flow name to use:

  • The available flows are known up front
  • The possible flows are looked up programmatically from desired type

The first case is fairly standard for POS applications where they are customised for a particular acquirer. In these cases, that acquirer project will define specifications that outline the available flows and the POS app can technically hard code the flow names to represent the function they want to initiate.

The second case would allow for dynamic choices of flows, but as FPS already supports this natively, it may not be as useful.

Getting called in a flow

When a flow service is called in the flow, the input request will contain a type which has been derived from the flow that is being processed. This type represents the function of the flow and will tell flow services what is expected of them. For instance, a payment app will handle sale and refund differently, just like a loyalty app technically could choose to refund points for one flow and reward points in another based on the type.