Introduction to App2App Integration

When you use the App-to-App (App2App) integration mode, your existing Android application (the Client App) works alongside the Tap on Phone application (the Whitelabel App) installed on the same mobile device.

In this setup, your application acts as the primary interface for the merchant, while the Tap on Phone app handles the secure, PCI-compliant payment processes. You communicate with the Tap on Phone app using standard Android Intents.

Division of Responsibilities

To ensure security and flexibility, the responsibilities are strictly divided between your application and the Tap on Phone application.

Your Application (Client App)

Your application manages the overall business logic and merchant experience. You are responsible for:

• User Authentication: Logging in the merchant and managing their session.
• Transaction Initiation: Triggering the payment, refund, or cancellation requests with the correct amounts and identifiers.
• Receipt Management: Generating, displaying, and sending digital receipts (e.g., via email or QR code) to the customer.
• Reporting: Managing transaction history, sales data, and business reporting.
• Post-Transaction Flows: Handling loyalty programs or other custom checkout steps.

Tap on Phone Application (Whitelabel App)

The Tap on Phone application is dedicated entirely to the payment execution phase. Its responsibilities include:

• Card Reading: Securely reading the customer’s contactless card or digital wallet (e.g., Google Pay, Apple Pay).
• PIN Management: Handling secure PIN entry when required by the transaction amount or card issuer.
• Transaction Status: Displaying the immediate, real-time result of the payment processing (Approved or Declined) before returning control to your app.

Communication Mechanisms

Your application interacts with the Tap on Phone application using standard Android communication protocols:

• Intents and Activity Results: You use Android Intents to launch specific actions in the Tap on Phone app, such as initializing the terminal or processing a purchase. To retrieve the outcome of these actions (like the transaction result), you should use the Activity Result APIs.
• Broadcast Receivers: For background processes or asynchronous requests—such as checking the POS status, forcing a security attestation, or recovering a lost transaction receipt—you send and listen for Android Broadcasts.

The Role of Single Sign-On (SSO)

Because the Tap on Phone app only handles payments, it does not know who the current user is. To authorize transactions securely, the solution uses a Single Sign-On (SSO) architecture.

Every time you send an Intent to the Tap on Phone app, you must include a userId and a userToken. The Tap on Phone backend intercepts the request and communicates with your backend server to validate the userToken. The Tap on Phone app only proceeds with the transaction or initialization once your backend approves the operation.