1. Documentation
  2. AppFlow
  3. Introduction
  4. Guides

Guides


Version 2.1.0

v2.1.0 comes with a fair few relevant new features and behavioural changes. It is a non-breaking upgrade for existing v2.0.X integrations with a few recommended changes to make the most of this new release.

Please see the Upgrade from 2.0.0 Guide for information on how to upgrade from an existing v2.0.X integration.

General

  • Major redesign of the AppFlow UI, including the configuration provider
  • New diagnostics screen to help troubleshoot problems and upload logs for off-device review
    • Uploading of logs require the AEVI Data Storage App - please contact AEVI for assistance with this
  • Websockets are now fully supported as an alternative for Android Messenger for AppFlow application IPC (to work around Android Binder limits)
  • New flow stage FULFILLED_CHECK that supports offering alternative in-flow payment methods if a transaction is declined or partially fulfilled
  • New AppFlowSettings model that contains configurable parameters such as date formats, etc that may be relevant for any application integrated with AppFlow.
  • The api-constants library now also holds models relevant for passing as additional data (starting with TaxInfo and TaxRate)

Initiation API

  • New feature: Ability to query for previous flow responses- A Payment can now specify a payment method which will have two effects
    • FPS will filter eligible payment apps based on reported payment methods
    • A payment app can internally auto-select payment method if more than one is supported
  • New types of errors added to ErrorConstants
    • noFlowServices
    • noAvailableFlow
    • duplicateRequestId
    • invalidFlowIdentifier

Flow Service API

  • New concept of flow service events which flow services can (should) subscribe to
    • FPS will now send an event to indicate that a response with augmentations was accepted or rejected via this
    • The Resume function is now sent as an event for flow services to manage
    • See Handling Events for more details
  • Flow services can now add entries to the audit log via a new stage model method
  • A flow service may now be requested to execute in the background via a new flag in the Request model
  • A new method has been added in PaymentFlowServiceInfoProvider to report back any errors with the data reported. See onServiceInfoError().
  • It is now optional for TRANSACTION_PROCESSING applications (payment apps) to report supported currencies and default currency,
  • It is now mandatory for any application that wishes to pay amounts (incl payment apps) to report canPayAmounts(true) via the PaymentFlowServiceInfoProvider.

Model Additions

Basket now have the following new concepts. See the new basket docs for details.

  • Basket can be marked as a "primary basket", which indicates it was set by the initiating application
  • BasketItem now has a measurement field for when an item is measured with a unit (such as "1.25 kg")
  • BasketItem now supports modifiers to associate information with it (such as tax, extras, discounts, etc)
  • BasketItem now support additional data for arbitrary extra data

Upgrade to v2.1.X

This guide helps you upgrade your v2.0.X AppFlow integration to the new v2.1.X release.

POS applications (initiators)

Error handling

As per the release notes, there are four new error constants that your POS application should look out for. See Handling errors for how to handle the errors.

Querying for responses

PaymentClient has a new method that allows querying for responses to previous flows. This may not generally be useful for POS applications that keep their own transaction history, but in the event where a response has not been received as expected, this can be used to query for the outcome of that flow.

Setting payment method

The Payment model now has a field for payment method, which FPS will use to filter eligible payment applications and payment apps internally can use to pre-select what method to use. This should only be set in scenarios where there is a specific requirement to use a particular payment method and hence payment app. In general, it is best to leave it blank to let AppFlow and the merchant decide what payment method to use.

New basket concepts

There are a few new basket concepts to support more complex scenarios. See the new basket docs for details.

Flow services

Handling flow service events

It is strongly recommended that your flow service is updated to handle the new flow service events. In particular, the resume function will not work otherwise, and it is also advisable to track whether or not the flow service augmentation was accepted or not.

Audit logging

Your flow service can now add entries to the audit log, which are primarily intended for troubleshooting purposes. If your application makes certain decisions based on some criteria, or can not perform its function for some reason, it is advisable that you log this into the audit log.

Background execution

The generic Request model now has a flag that can be queried via shouldProcessInBackground() method. This flag can be set by the initiating (POS) app or via the flow configuration to indicate that this flow should not be visible to users. It is highly recommended this flag is checked and if your service can not process the request in the background when requested, it should send back a failed response explaning this. See the tokenisation handling in GenericStageHandler in the samples as an example.

If your service can process in the background when the flag is set, it simply means that no activities or other form of UI should be launched - it should all be handled in the service.

PaymentFlowServiceInfo errors

There is a new optional method that can be overridden from BasePaymentFlowServiceInfoProvider in order to receive a callback for when the getPaymentServiceInfo() call has failed or validation of the data failed. The method has the signature protected boolean onServiceInfoError(@NonNull String errorType, @NonNull String errorMessage).

The errorType variable can be mapped to one of the constants in ServiceInfoErrors. The errorMessage is for informative purposes.

Payment apps

It is no longer mandatory for payment applications to report supported currencies, but it is still recommended where possible. This change is to support currency-agnostic payment method such as cash.

On the other hand, it is now mandatory for payment applications to set the canPayAmounts(true) in the PaymentFlowServiceInfo to indicate that it can pay amounts.