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

Guides


Reference values

AEVI defined keys, values and formats

This section provides AEVI defined reference data, value and formats for AppFlow.

On the right, you will find a series of links to pages that describe different types of data that can be passed via AppFlow. As an example, there is a page that outlines the keys for various additional amounts that can be set and added to a payment flow.

The various pages also link to defined constants that can be referenced from your code. See api-constants for more details.

Although AEVI does not force nor restrict what keys or values are used by applications, developers should always look to this for commonly used values to ensure consistency with other applications.

If something you consider as common or general is missing here, or you have questions, please contact AEVI or raise a ticket for it.

See our how to guide for AdditionalData for detailed information about how to read or write data of any type.

General

These flags are used for various purposes where the concepts covered are required. As an example, if any scenario requires an amount to be passed, the data key "amount" as outlined here should be used.

Data key Value type Format / Example Used to
"transactionId" String alpha-numeric Specify a particular transaction
"amounts" Amounts Represents amounts To pass amounts outside of Payment
"amount" Amount Represents an amount To pass amount details
"basket" Basket Represents a basket To pass a basket outside of Payment
"customer" Customer Customer data To pass a Customer model outside of Payment
"taxInfo" TaxInfo Represents tax See Tax Info

Payment Flow Input

These flags can be provided in the Payment or Request additional data by the client, or any flow service, to instruct or inform applications in the flow. For flags relevant for payment applications specifically, see next section.

Data key Value type Format / Example Used to
"transactionLanguage" String ISO 639-1 two-letter language code, example "en" Used to instruct other applications of the language of the transaction, allowing them to show text, etc in the correct language
"accessibleMode" Boolean true / false Whether or not apps should cater for visual impairment

Input to payment apps specifically

These flags, in addition to the more generic ones above, can be provided in the Payment (or Request) additional data by the client, or any flow service, to instruct or inform payment applications.

Data key Value type Format / Example Used to
"merchantId" String alpha-numeric Used to specify what merchant initiated the flow in the case of multi-merchant environments
"cardEntryMethods" String[] ["insert", "swipe", "tap"] Used to instruct the payment app what card entry methods to make available to the customer
"cardNetworks" String[] ["visa", "mastercard", "jcb"] Used to instruct the payment app what card schemes to allow for card presentation
"accountTypes" String[] ["savings", "credit"] Used to instruct the payment app what account types to support for the transaction

Payment Methods

For use by flow services to report what payment methods they support, and what payment method was used for a given transaction.

What payment methods are supported can be retrieved via PaymentFlowServices.getAllSupportedPaymentMethods() or for individual flow services via PaymentFlowServiceInfo.getSupportedPaymentMethods().

What payment method was used for a particular transaction can be retrieved via TransactionResponse.getPaymentMethod().

See PaymentMethods for defined constants.

Payment method Description
"card" Paid via payment card
"cash" Paid with cash
"points" Used points from a loyalty scheme
"reward" Used a reward or bonus obtained in a previous transaction
"cheque" Paid with cheque
"bankTransfer" Transferred money from bank account
"gift" Paid using a prepaid stored-value money card
"ebt" Paid using a Electronic Benefit Transfer (EBT) card
"invoice" Paid via invoice

Card Details

Card details may be set by payment application in either the PAYMENT_CARD_READING stage (if supported) or in the TRANSACTION_PROCESSING stage.

See CardDataKeys for the keys.

Key Value type Format / Example
"network" String See CardNetworks
"entryMethod" String See CardEntryMethods
"authorisationMethod" String See CardAuthorisationMethods
"accountType" String See AccountTypes
"aid" String "A0000000031010"
"serviceCode" String As per ISO 7813
"cvv" String "123"
"languages" String[] ISO 639-1 ["en", "sv"]

Customer Details

Customer details can be set via the addCustomerDetails() and they can be read via the getCustomerDetails() method.

See CustomerDataKeys for defined keys.

Data key Value type Format / Example
"firstName" String "John"
"middleNames" String[] ["Bob", "Dorian"]
"surname" String "Doe"
"phone" String International "+44 123 456789"
"email" String "john.doe@gmail.com"
"address" String "123 Android Boulevard"
"postcode" String "92060", "W1 W1A"
"city" String "Los Angeles"
"country" String "Puerto Rico"

Account Types

These values can be provided by a POS application to specify what account types should be used, if applicable.

See AccountTypes for defined values.

Account type Description
"credit" Credit account
"debit" Debit account
"savings" Savings account
"cheque" Cheque account
"prepaid" Pre-paid account

Additional Amounts

When creating or augmenting a request, it is possible to add amounts additional to the base amount. Typical examples of such amounts are tip, tax, fees, etc. Below are some defined identifiers for various types of amounts to help applications know what is what.

See Dealing with amounts for a general overview of amounts in AppFlow.

Note that tax (GST, VAT, etc) should not be set this way. The base amount should always be inclusive of tax. If you have requirements to specify or retrieve the tax amounts, please contact AEVI to discuss.

See AmountIdentifiers for defined values.

Amount identifier Description
"tip" Tip amount
"cashback" Cashback/cashout amount
"surcharge" Surcharge fee
"charityDonation" Donation to a charity

Basket Data

General basket data keys.

Key Value Type Format / Example
"taxInfo" TaxInfo See Tax Info

BasketItemModifier types

Type Description
"tax" Represents tax applied to the item, such as value added tax or state tax
"extra" Item extras/add-ons, such as add "Cheese" for a Burger or "Extra shot" for a Coffee
"deduction" Item deduction, such as remove "Fries" from a Burger Meal
"discount" Discount applies to the item, such as "Half price off"

Transaction Response References

The TransactionResponse class contains a number of fields that can be used to pass back processing information, such as outcome, response codes, etc. There may however be other bits of information that may be relevant to pass back either from a particular flow service, or for particular scenarios and use cases. This can be set via transaction references.

Please see ReferenceKeys for defined keys.

These references are all from the perspective of the app/system that processed the request. In the case of a payment application, it is in the context of an acquirer/bank system.

Reference key Value type Description
"merchantId" String Id of merchant
"merchantName" String Merchant name
"terminalId" String Terminal id
"transactionDateTime" long Milliseconds since epoch