Application Startup and User Login

When the application starts, it verifies that the version is current and if it requires an upgrade by sending the apiKey

Each apiKey is unique for each application release. The application can be:

If the application is compatible, then it will request a list of available Issuers for that App. If more than one issuer is available, then the application will request the user to select the issuer from the list of available issuers.

The selected Issuer will be stored in the configuration settings to avoid asking the same question again, but enabling the user to change it if necessary. An example of this is if the user goes to another island, as each island will run its own cards, merchants, and currency.

Once the application loads, if the application has a stored session token it will send the userID and Session Token to the FEP by calling

If the session token is valid, then the application will continue.

If the FEP rejects the session token, then the mobile application will request the user to insert credentials or create a new user.

User Login

The mobile application will check if the session keep alive flag is set and if the session parameters are stored. If so, then it will connect to the application to verify that the session parameters are still valid. To do this it will perform.

Sending the session information header (see below).

If user information is returned successfully, then the application shall continue processing and the user is logged into the application.

If the request return failure (ERROR XXXX Invalid Session Token), then the application will request the user its email and login password to stablish a new session. The mobile application will connect to the FEP sending credentials to obtain a token.

The FEP will reply the session token that will be used in subsequent calls.

Subsequent calls shall include the following header:

{ 
	"UserGUID":"sdfsdgdsfdsfs",
	"SessionTK":"sdlknwlkclkdnlkndlkvdlkndv",
}

If KeepAlive is true, then the mobile application shall store the returned data between application restarts. The FEP will maintain the session alive.

FEP shall perform session garbage collection following the following rules:

Once successfully logged, the user shall update its tokens information by requesting the Token List:

Register New User

If the mobile application need to register a new user, then the application will request a new user, by sending new user Email, Full name, Password, device ID, device platform, device name and if the user wants to keep connected when application is closed.

The FEP confirms the creation of the new user that will be pending until confirmed by responding to the sent email. The mobile application will store selected user id and the flag if the user wants to maintain session in the user configuration section.

The FEP application will create the new user but it will be pending activation. It will also generate a new user request record and send an email with a link to the user request item to confirm. The request will hold information related to the request and if the page is accessed the request will be executed and the user enabled.


Once the user responds to the mail, the user will be enabled for login. The Email will contain the following link:

User Forgot Password

In case the user forgets his/her password, then the mobile application will request the user email and connect to the FEP requiring a password reset to the following endpoint:

The FEP application will NOT perform an immediate password reset but generate a new user request and send an email with a link to the user request item to confirm. The request will hold information related to the request and if the page is accessed the request will be executed and the password changed.

Register New Card

If the mobile application need to register a new card, then the application will request a new encryption key, by calling:

The FEP shall respond a list of available card types for the current issuer in use. The list will include a URL to retrieve a card information picture to be displayed at the mobile application.

Once the user selects the card type and types the card PAN to be registered, the mobile application will request an encryption token.

With the card data encrypted using the returned key and encryption method, the mobile application shall post the card information to create a new token. Two encryption Types are available:

Notes: The host decides what encryption method will use. The application should be designed to implement new encryption methods in the future. We can implement a different encryption method at the host if the mobile development environment does not support RSA 1024 and has a library that supports another asymmetric encryption method.

The FEP will respond with a token to represent the card, and additional non-confidential information. It may also return the card balance if available from the acquirer. The mobile application shall accommodate the display of the card balance if available.

Delete Existing Card

When the mobile user decides to delete a card, it will select the card token to be deleted.

The mobile application will check card balance, by sending card token information request. To obtain the card credit, the mobile application will request:

The FEP will respond with the card token information, including the card balance if available from the acquirer. The mobile application shall accommodate the display of the card balance if available.

If the Card balance is not 0 or null, the mobile application will display the remaining credit and indicate the user of the remaining credit, and that it can be consumed by using the physical card.

If confirmed, the mobile application will then connect to the FEP to request the token deletion

Find Sites

If the user wants to find sites, the mobile application shall open google maps with a radius of the application. To obtain the site list within this area, the mobile application shall request site information by calling:

The mobile application will then open a map with the sites in place. If the user changes zoom level, the request will be executed again with the distance value updated. The application pins should allow seeing information of the site, and route to destination.

The list of services will be reported by a string for which each letter will represent:

Other services may be added to the list.

Sell Fuel

When the user selects Sell Fuel, the application will request current location and its information. For this purpose, the application will send the FEP a find sites request with current location and distance = 0, using the same entry point used to locate sites:

Distance Parameter may be omitted and will be considered as 0 value.

The FEP will return a LIST of sites containing a single site if the user is within the site geo fence, and null is the user is not at the site.

If no site is returned, then the application will allow the user to manually select a site using the find sites component. Once selected, the application will request the user to confirm fuelling at this site as he is away from the location.

Once site is selected, the user will have to select PumpID (a value within 1 and the QtyPumps reported by the FEP), amount to fuel (with a default value contained in FullTankAmount configuration parameter) and payment Token (not required if user has a single token).

The application will call pumps authorize request to start sale.

Possible Response Codes:

If 000 - No Error, Pump is authorized and ready to start fueling. At this point, the application will poll every 5 second for pump status. User may cancel the transaction until user starts fueling.

To poll pump status, the following command is sent to the FEP:

Possible Pump Status

A successfully authorized transaction may only be cancelled if the transaction is in either Reserved or Authorized status. To cancel the transaction, the following command must be sent to the FEP:

Possible Response Codes:

Once the user finishes fueling, the FEP will prepare the receipt and make it available to the user. Once the pump is back to available status 0, the mobile app may request the receipt through the receipt ID.

The mobile application shall offer the user the possibility to view the transaction receipt, depending on the value of the DisplayReceipt user configuration parameter (never, always, ask).

If the FEP returns card balance for the token used during the transaction (card balance is not null), then the application must request the new card balance by requesting the token info to the FEP:

View Mobile Receipts

When the user enters the view last receipts, the application will request the FEP the last “n” receipts.

Note: The amount of receipts that the application will request will be configurable by the user.

To obtain the last receipts, the user will request:

Limit will identify the quantity of receipts required (amount of receipts per page) and Page will define the initial receipt to be returned.

So initially, the request will be: Limit=10 and Page=0 (or no page parameter), and the FEP will reply the last 10 receipts. If the user selects to see more, then the mobile application will request Limit=10, page=1, and the FEP will return the receipts 11 to 20 ordered by last date. Receipts will only include those performed by the mobile application user.

Configure User

USE CASE PENDING DEVELOPMENT

Parameters to be updated (Draft – Under development)