Manual Tap (NFC) Overview

1. Feature Abstract

"Manual Tap" is a Close-Proximity Payment feature enabling SAGIO App users to pay at SAGIO Merchants using stablecoins (USDC/Eurite) over the Base network.

Unlike traditional "Tap to Pay" where the Merchant acts as the Reader (reading a customer's card), SAGIO implements a "Reverse Tap" architecture.

2. The "Reverse Tap" Architecture

Core Concept

• Merchant = Beacon (Passive Tag)
  The Merchant POS broadcasts the transaction intent. It acts effectively as a dynamic QR code that broadcasts via radio waves (NFC) instead of light.
• Customer = Reader (Active Scanner)
  The Customer's phone energizes the field and reads the transaction data from the Merchant devices.

Roles & Responsibilities

Role	Application	Technology	Responsibility
Emitter	Merchant POS (Android)	Android HCE (HostApduService)	Broadcasts intentId as an NDEF record when in "Awaiting Payment" state.
Reader	Customer Wallet (iOS/Android)	CoreNFC / Android Reader Mode	Scans for SAGIO tags, parses intentId, and initiates payment flow.
Orchestrator	x402 Facilitator API	REST + EIP-2612 Permit	Generates intentId, provides EIP-712 typed data, verifies signatures, and settles payment on-chain.

3. High Level User Flow

1. Initiation: Merchant enters amount (e.g., $15.00) and taps "Charge".
2. Broadcasting:
   • Backend generates a payment_intent via the x402 Facilitator.
   • Merchant POS displays a QR Code AND silently starts Host Card Emulation (HCE) broadcasting sagio://pay/{intentId} via NFC.
3. Discovery:
   • Customer unlocks SAGIO Wallet and taps "Pay".
   • Customer holds phone near Merchant POS.
4. Handshake:
   • Customer phone detects the NDEF message.
   • OS/App routing captures sagio:// link and extracts intentId.
5. Resolution:
   • Customer app queries Facilitator for a session (Typed Data) using the intentId.
   • Customer reviews merchant details and amount on their screen.
6. Settlement (x402 One-Confirm):
   • Customer signs the EIP-712 Permit payload (biometric/pin).
   • Signature is submitted to the x402 Facilitator.
   • Facilitator verifies the signature and executes the transaction on-chain (Base).
   • Merchant POS detects success via status polling or WebSocket and shows "Success" screen.
   • Merchant HCE service is terminated.

4. Critical Constraints

4.1 Worldline Coexistence

The Merchant POS hardware runs the Worldline Tap-to-Pay SDK, which claims exclusive access to the NFC Controller in Reader Mode.

• Conflict: We cannot be in Reader Mode while Worldline is active.
• Solution: We operate in Card Emulation Mode (HCE), which uses a different routing table in the NFC Controller. However, we must strictly manage the lifecycle to ensure we don't interfere with Worldline's background polling if applicable.

4.2 Security

• Payload: The NFC signal contains ONLY the intentId (via the deep link URI).
• No Sensitive Data: Never broadcast amounts, merchant keys, or customer artifacts over NFC.
• Attestation: The intentId is a temporary pointer. Validation happens over authenticated HTTPS calls from the Customer Wallet to the Facilitator.

4.3 Fallback

NFC is fallible (hardware case thickness, antenna placement). The UI must ALWAYS display a QR Code containing the identical URI (sagio://pay/{intentId}) as the primary visual fallback.