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

A flow is simply a configuration that defines one to many stages and for each stage, defines what applications can be called and what data should be passed to and from them.

There are two types of flows - payment and generic. Payment flows are initiated via a Payment and always involves movement of money from one party to another as requested by a client (POS) app. Examples are purchases and refunds. The generic flows can on the other hand represent any function that is typical for POS/payments like tokenisation or reversals, but also custom functions as defined by flow services.

Payment flows

The most common flow is the sale flow, which is used for all standard transactions where a customer is charged for some goods or services.

Below is a diagram illustrating the sale flow. Note that Payment Services are just a type of flow services and integrates with the same API as any other flow service, but for clarity, are named differently here.

As a developer, you can provide flow service applications that target one or more stage(s) of the flow. The FPS will ensure that (if added to the flow configuration) your application is called at the correct stage and you are passed all the request details gathered for the transaction so far. Typically the flow will also ensure the request is fulfilled by the payment application that typically reads payment cards and processes the payments. Your application can be defined to be called at multiple stages of the flow. An example could be a loyalty points app, where you may want to offer a customer the option to use their points for a purchase before payment processing, and you may want to reward the customer with points after a successful purchase.

You can find more details about flow configurations here.

Pre-flow

This stage is executed immediately after the source Payment has been received and validated. It is executed only once per payment, before any actual transactions take place.

Pre-flow is designed to handle the fairly rare use cases where an application other than the POS application initiates a flow. As an example, a loyalty app might be the first point of interaction with a customer where they identify themselves. In order to pass this information onto a payment flow (without using bespoke integrations), the loyalty app can initiate a zero based amounts payment with associated customer data. The POS application will then be called in the pre-flow stage where it can perform its normal function and update the Payment model with relevant data before the flow continues.

Note; By default, pre-flow is only called for cases where the payment amounts are zero.

Split

If a split application is installed and the request has enabled split, the split stage will be executed where the application can split the requested amount into one or more individual transactions. The most common use case of this is to allow a group of customers to split the bill, either based on amount or via basket items.

See Considerations for Split applications for more details what is required from split apps.

The input request to the split stage is SplitRequest.

Pre-transaction

This stage allows an application to modify request data before any payment card is read.

For most applications, post-card-reading will be a more appropriate stage as card details may then also be available. This is explored in further depth in the API documentation.

The input model here is TransactionRequest.

Payment card reading

This is an optional stage that a payment app may or may not support (some payment services will not even process payments via cards).

If it is supported and the card reading is successful, card data will be available for the remaining stages.

Post-card-reading

This stage is executed after the optional payment card reading step, meaning there may or may not be valid card data available.

The input model here is TransactionRequest.

Payment processing

At this stage, the payment app will process the payment based on the data provided (which may or may not have been augmented in previous stages).

At the end of this stage, a TransactionResponse will be sent back dictating the outcome of the transaction.

Post-transaction

A TransactionSummary model will be passed to applications in this stage, which contains a breakdown of the input transaction data and a list of transaction responses for that transaction. It will also contain the card data if any was set by the payment application at either payment app stage.

Note that the only thing an application can augment at this point is adding transaction references.

Post-flow

This stage is executed after all transactions are completed and a final PaymentResponse object has been created which is available for applications here to read.

At this stage, no response is required or possible as nothing can be changed at this point.

Note: Only one post-flow application is supported at this stage.

Generic flows

The generic flows are a lot simpler than the payment flows and consists of only two possible stages.

Generic

The generic stage is where the request is processed. As an example, for a request of type tokenisation, this is where a payment app would read a card and generate token.

There can only be one service handling a generic request.

Post-generic

This is the generic equivalent of Post-flow, where an app gets called with the final response and can review that data. It can also add references to that response.