migration from v1 - AEVI-AppFlow/pos-android-sdk GitHub Wiki

The second version of these APIs contain some breaking changes that means you will have to adapt your application if it is currently integrated with the first version. As a general rule - review the samples if unsure about what to do.

The in v1 separate APIs payment-service-api and flow-service-api have been merged in this version into a new payment-flow-service-api.

This means you have to update your dependencies accordingly to use com.aevi.sdk.pos.flow:payment-flow-service-api:<version> instead.

There is no longer any major distinction between what was previously known as flow services (aka VAAs) and payment services. A service simply defines what stages it wants to support and that determines what function(s) they can provide. A traditional payment application is a service that gets called during the TRANSACTION_PROCESSING stage, and optionally PAYMENT_CARD_READING and GENERIC.

FlowClient has been removed and all methods are now defined in PaymentClient to improve clarity of where to find things (in particular for JavaDocs). In addition, we have the following client changes

• getSystemSettings(), getFlowServices() and getPaymentServices() replaced by getPaymentSettings()
• subscribeToStatusUpdates() and getCurrentRequestStatus() removed as there was no use case for them
• processRequest() renamed to initiateRequest() to follow initiatePayment() naming

Important, the initiate method return types have also changed from Single to Completable. Read more at Handling responses.

There is no longer any need to define a service per stage, and the previous base services like BasePreFlowService etc are all gone.

This has been replaced with a new concept of "stage models", which are independent components that can be created from both service and activity contexts and provide all the relevant functions specifically for that stage. See PreTransactionModel as an example. There is one of these defined for each stage.

There is a new BasePaymentFlowService which can be extended for cases where processing should be service based. All that is required is that you override the correct method, like onPreTransaction(PreTransactionModel) and use the intent filter for that, and you will get a callback into that method when a request comes in. See PaymentService as an example of this.

In addition, there is a new solution for processing requests in an activity via another new service, ActivityProxyService, that can be used to proxy any request onto an activity. This is to avoid the boilerplate services that exists purely to sit between FPS and an activity. The ActivityProxyService can be defined to handle any number of stages, and proxies requests on to activities with the relevant stage intent action. See FlowServiceSample manifest for examples of how this is defined in the flow service sample (do note though that it is using a subclass of the API service to add function - this is not required).

The activities then add intent filters relevant for the stage it wants to handle, like com.aevi.sdk.flow.action.PROCESS_PRE_TRANSACTION_IN_ACTIVITY.

See Implementing Flow Services for documentation around this.

All intent actions have been updated to be consistent.

See IntentActions for the full list of action names to use in the manifest now.

Remember to update all your services and content providers or FPS won't find them.

Payment services, as in services that support transaction processing, which previously used the payment-service-api, no longer needs to define the configuration-authority meta-data for the service that implements the old com.aevi.sdk.pos.flow.action.PROCESS_PAYMENT. (The intent action should be replaced with com.aevi.sdk.flow.action.PROCESS_TRANSACTION)

Instead, your applications needs to update the intent filter for the service info provider to com.aevi.sdk.flow.action.PROVIDE_SERVICE_INFO

Flow services also need to update the intent action for their service info provider to com.aevi.sdk.flow.action.PROVIDE_SERVICE_INFO

As the APIs are merged, there is now also a single base service info provider that you need to extend from, and a single builder class to generate your service info.

public class SampleServiceInfoProvider extends BasePaymentFlowServiceInfoProvider

And the builder to use now for all flow services is PaymentFlowServiceInfoBuilder.

• withSupportedRequestTypes() and withSupportedTransactionTypes() have been replaced by the two methods below
• New method withCustomRequestTypes() that allows any flow service to define custom/bespoke request types, if any. Example is showLoyaltyPointsBalance from the samples. Should not be called unless there are custom types.
• New method withSupportedFlowTypes() allows a flow service to report which of the pre-defined flow types are supported, if any. See Request Types for more info.
• withPaymentMethods() replaced by withCanPayAmounts(boolean, paymentMethods)
• Support to set any custom / arbitrary data via withAdditionalInfo()

For payment service migration, note the following changes

• withTerminalId() removed - use AEVI DMS API for retrieving device ids
• New merchants model to represent merchants, use withMerchants(Merchant... merchants)
• withManualEntrySupport() and withPrintsReceipts() can now be set as additional data

The way transaction ids are managed have changed a bit. See Transactions for details.

There is no longer a way to specify a payment service via an id as per before, as flow configs alone now determine what applications are available for any flow and stage.

The way flows are managed has changed in order to improve its flexibility. The previous withTransactionType() method in PaymentBuilder has been replaced by two new methods - withPaymentFlow(String flowType) and withPaymentFlow(String flowType, String flowName). This is due to new support for multiple flows per type. A client can still set the type only and FPS will map that to available flows, which will only be one match in the majority of cases. In cases where there is more than one flow per type, a runtime selection dialog will be presented to allow the merchant/operator to choose.

For development, testing, prototyping, etc, setting the type only is the best approach. However, for production scenarios it is generally recommended to also explicitly specify the flow to use. In most acquirer environments the defined flows will be known up front and that information is provided to all developers.

There are too many minor changes to the models to cover here, so please see the change log for more details.

• PaymentStage enum is gone and replaced by the FlowStages string definitions
• TransactionRequest.getPaymentStage() now getFlowStage() and returns a string instead
• Basket and Customer are now first level citizens in Payment and TransactionRequest
• There can now be more than one basket, as any "upsells" provided by flow services will be represented in individual baskets
• TransactionRequest has a new getTransactionId() method that returns the id for the whole transaction