# Architecture

This page explains the architectural components and the communication flow that power the Get Tap on Phone (App2App) integration. Understanding this architecture helps you design a robust integration between your Android application, the Tap on Phone application, and your backend systems.

## The Core Components

The App2App integration relies on four distinct components working together to securely authorize and process a payment.

1. **Your Application (Client App)**  
   This is your Electronic Cash Register (ECR) or Point of Sale (POS) Android application. It acts as the primary interface for the merchant. It manages the user session, the shopping cart, and initiates payment or initialization requests.  
2. **Tap on Phone Application (Whitelabel App)**  
   This is the secure payment application installed on the same Android device. It remains dormant until your application calls it. Once invoked, it takes over the screen to handle secure tasks like NFC card reading and PIN entry, then returns the result to your application.  
3. **Tap on Phone Backend**  
   This cloud-based platform routes the transaction data to the acquiring networks and manages the configuration of the mobile terminal. Crucially, it intercepts requests from the Tap on Phone app and asks your backend for permission to proceed.  
4. **Your Backend (Client Backend)**  
   This is your organization's server infrastructure. It hosts the Single Sign-On (SSO) authorization endpoint. It validates the user session and approves or denies sensitive operations based on the merchant's permissions.

## The Communication Flow

Because the Tap on Phone app operates securely and independently, it relies on your application and your backend to authenticate the user.

Here is the sequence of events when your application requests a protected operation (such as initializing the terminal or processing a refund):

1. **Initiation**: Your application sends a request to the Tap on Phone app on the local device, passing the `userId`, `merchantId`, and a secure `userToken`.  
2. **Validation Request**: The Tap on Phone app forwards this request to the Tap on Phone Backend.  
3. **SSO Permission Request**: The Tap on Phone Backend uses the `ClientID` to locate your specific SSO endpoint. It sends an API request to your backend containing the `userToken` and the requested operation.  
4. **Authorization**: Your backend verifies the token and the user's permissions, returning an HTTP `200 OK` response if approved.  
5. **Execution**: The Tap on Phone Backend signals the Tap on Phone app to proceed with the operation.  
6. **Completion**: The Tap on Phone app executes the operation (e.g., configuring the terminal or prompting for a card) and returns the final result back to your application.

## Android Communication Patterns

To facilitate the local communication between your application and the Tap on Phone app, the integration uses standard Android mechanics.

### Intents and the Activity Result API

For synchronous operations that require a user interface—such as initializing the application or processing a payment—you use **Android Intents**.

To receive the outcome of these intents, you must use the modern **Activity Result APIs** (introduced in AndroidX Activity `1.2.0` and Fragment `1.3.0`).

* You launch the intent using a registered launcher.  
* The Tap on Phone app processes the request and finishes its activity.  
* Your registered callback receives a `RESULT_OK` (success) or `RESULT_CANCELED` (failure or user cancellation), along with an `Intent` containing the detailed response data (extras).

### Broadcast Receivers

For asynchronous operations or background tasks that do not require an immediate user interface, the integration uses **Broadcasts**.

You use broadcasts to:

* **Check POS Status**: Verify if the terminal is fully initialized before attempting a transaction.  
* **Trigger Attestations**: Force a background security check to prevent delays during the checkout flow.  
* **Recover Transaction Status**: Query the status of a specific transaction UUID if your application crashed or missed the original Activity Result.  
* **Reset the POS**: Clear the current user session and configuration.

When you send a broadcast request to the Tap on Phone app, you can provide a custom `ResponseAction` string. The Tap on Phone app performs the requested action in the background and emits a response broadcast using that exact string, allowing your application to listen for the result.