AEVI v2 Simple Payment API

AEVI has provided a "payment initiation" API referred to as the Simple Payment API for many years now. This is a simple activity-based API that allows a VAA to initiate payments against a single payment app installed on the device.

AppFlow is not a direct replacement for this API as it is much broader than that, but we definitely recommend using the new APIs for any new development.

We will be referring to any applications using this old API as legacy apps.

Existing legacy API applications

AppFlow provides full compatibility support for existing applications that are integrated with the legacy APIs. This means that a legacy VAA can still initiate payments as per before, and legacy Payment Apps can still accept request and process payments as per before.

There are however a few restrictions;

• Split payments is not supported as the legacy APIs have no mechanism of passing back more than one transaction
• Post-card-reading flow apps will never receive card data from legacy Payment Apps
• Multiple payment apps in a flow is not supported when there are legacy payment apps installed

Legacy components

Whereas FPS itself supports calling into legacy Payment Apps, additional components are required to support the legacy VAA use cases.

There are two different adapter applications intended for two different scenarios.

Payment Request Legacy App

Payment Request Legacy App (PRLA) is required when there is no legacy Payment App on the device. PRLA essentially acts as a fully fledged legacy payment app and proxies the requests through to AppFlow. This is required due to how the legacy APIs are designed, where the legacy VAA calls directly into the legacy Payment App via intent.

PRLA does two things;

1. It will handle legacy PaymentAppConfiguration request by querying FPS for available payment apps, and then using a converter to map the AppFlow PaymentFlowServiceInfo objects into the legacy PaymentAppConfiguration objects. If there is more than one payment application, the flow configurations will be parsed to find the eligible candidate. If none can be chosen via this process, the legacy support will report back a failure.

2. It will handle legacy AeviRequest intents, convert the model to a AppFlow Payment or Request and route it to FPS via the Payment Initiation API.

Note that PRLA should not ever be installed alongside a real legacy Payment App as multiple legacy Payment Apps is not supported.

Payment Flow Legacy App

Unlike PRLA, Payment Flow Legacy App (PFLA) is intended to be used when there is a legacy Payment App installed.

PRLA is not involved in the legacy PaymentAppConfiguration requests. These go straight from the legacy VAA into the legacy Payment App via intent, as FPS has no way of intercepting this.

PRLA will however be able to intercept requests from v2.5.1+ VAAs via a special hook added, allowing it to perform the same function as PRLA and proxy these requests through to FPS.

Migration

Payment apps

For payment apps that do not wish to support the separate card reading step, the migration process is fairly straightforward.

1. Replace the activity that implements the intent action com.aevi.payment.CONFIGURATION with a PaymentFlowServiceInfoProvider, return the relevant model and update the manifest.
2. Replace the activity that implements the intent action com.aevi.payment.REQUEST with an implementation of BasePaymentFlowService and update manifest according to docs. This service handles what corresponds to the following in the legacy API: PAYMENT, MOTO_PAYMENT, REFUND, MOTO_REFUND, PRE_AUTHORISATION, COMPLETION, DEPOSIT
3. Ensure that required legacy API parameters are added as references to the AppFlow TransactionResponse. These ensure backwards compatibility with any legacy VAAs. The keys that should be added as references to all TransactionResponses are merchantId, merchantName, terminalId and transactionDateTime.
4. Add an implementation of BaseGenericService to handle what in legacy APIs is known as REVERSAL, TOKEN and RECEIPT requests
5. You can now wire up these services to the same activity/fragment UI that were used previously for legacy

VAAs / POS apps

The complexity of migration for VAAs / POS apps depend on whether they want to support split scenarios via AppFlow. For non-split scenarios, the migration to AppFlow is fairly straightforward. To add support for split as well does however make the process fairly complex.

For non-split scenarios, the main differences from a POS app point of view are,

• Unbound request/transaction types - AppFlow supports custom request and transaction types
• Monetary representation is in subunit form via a long instead of BigDecimal
• Native basket support
• Native customer details support
• Support for arbitrary data models being passed
• A request (of type Payment) can result in multiple transaction responses
• A request (of type Payment) can be partially fulfilled, leaving it to the POS app to decide what to do

The last point has the biggest impact, as there can be scenarios where a portion of the request is paid via loyalty points in a flow application, followed by the payment service declining the remainder. This must be handled by the POS application in a sensible way.

For split scenarios, please contact AEVI for assistance.