From 102d32c930cc229dbeb2af90604052dc08968fdd Mon Sep 17 00:00:00 2001 From: Sean Dolbec Date: Fri, 13 Nov 2026 10:49:22 -0500 Subject: [PATCH] Dejavoo Tap to Pay on iPhone: decision, flow, security split, videos and plan Take payment goes into the existing iPhone app through Dejavoo's iPOSgo! deep linking. Notes cover how it works, what Apple and Dejavoo handle vs what Rupert must verify server-side, requirements, timing and open questions. Co-Authored-By: Claude Opus 5.5 --- docs/integrations/dejavoo-spin.md | 1 + .../integrations/dejavoo-tap-to-pay-iphone.md | 117 ++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/integrations/dejavoo-tap-to-pay-iphone.md diff --git a/docs/integrations/dejavoo-spin.md b/docs/integrations/dejavoo-spin.md index d4c92ce8..4ec27130 100644 --- a/docs/integrations/dejavoo-spin.md +++ b/docs/integrations/dejavoo-spin.md @@ -18,6 +18,7 @@ with Dejavoo or the processor before production. The meeting questions are in | "SPIn Proxy" | In the docs this is the portal's connection-troubleshooting tool (POS ↔ terminal), not a separate API. [S2] | Use when testing. | | iPOSpays Hosted Payment Page, Freedom to Design.js, iPOS Transact | Online card-not-present checkout and token charges. [S5] | Online store only. Out of scope here. | | Terminal app / deep linking (DvPayLite, DVStore) | Rupert would run as an Android app on the terminal. [S6] | Not now. Large effort and an app-store listing. | +| Tap to Pay on iPhone (iPOSgo! deep linking) | Rupert's iPhone app hands the amount to Dejavoo's iPOSgo! app, which takes the tap. | **Chosen 2026-11-13** as a Take payment button in the existing iPhone app. See [dejavoo-tap-to-pay-iphone.md](dejavoo-tap-to-pay-iphone.md). | | Batch Report API, Transaction Status Check API, FEED webhooks (HMAC) | iPOSpays reporting and event push. [S5] | Later, for settlement reconciliation. | ### Terminals diff --git a/docs/integrations/dejavoo-tap-to-pay-iphone.md b/docs/integrations/dejavoo-tap-to-pay-iphone.md new file mode 100644 index 00000000..e1a83175 --- /dev/null +++ b/docs/integrations/dejavoo-tap-to-pay-iphone.md @@ -0,0 +1,117 @@ +# Tap to Pay on iPhone with Dejavoo (iPOSgo!) + +Prepared 2026-11-13 from Dejavoo's public developer docs (read that day). Owner decision recorded the +same day. Related: [dejavoo-spin.md](dejavoo-spin.md) (counter terminals) and +[dejavoo-valmar-meeting-brief.md](dejavoo-valmar-meeting-brief.md). + +Keep TPNs, merchant codes, auth keys, device UDIDs, contact details and the store's product approvals +out of this public repository. + +## Decision + +Build card acceptance into the **existing Rupert iPhone app** as a **Take payment** button on the +register, not a separate "Rupert: POS" app. The register already runs inside the app, and a second app +would need its own App Store review. A POS-only app for store-owned phones can come later. + +## How it works + +Dejavoo's iPhone option is "deep linking": Rupert's app does not read the card itself. It hands the +amount to Dejavoo's own payment app, **iPOSgo!**, which takes the tap and hands the result back. + +1. The cashier rings up the sale in Rupert and taps **Take payment**. +2. Rupert's server records a payment attempt and the amount **before** anything is charged. +3. The Rupert app calls Dejavoo's Swift library (`import DeepLinking`, `Wrapper().startTransaction`), + which opens iPOSgo!. +4. The customer taps a contactless card or phone wallet on the iPhone. iPOSgo! can show its own tip, + amount breakdown and approval screens, each switchable. +5. iPOSgo! returns to Rupert with the result (approval code, last four digits, RRN, batch number, + amounts). +6. Rupert's server **confirms the payment with Dejavoo** before marking the sale paid, then prints or + sends the receipt. + +The store's phone needs both apps installed: Rupert and iPOSgo!. + +## Videos (Dejavoo's own, about 30–40 seconds each) + +- [A payment from start to finish](https://s3.us-east-1.amazonaws.com/assets.ipospays.com/Deeplinking+V2_1.mp4) +- [Adding Dejavoo's library to an iPhone app](https://media.publit.io/file/iOSDeepLinkingConfigureSDK/iOS-Deep-Linking-Configure-SDK.mp4) +- [Connecting the phone to the merchant account (TPN register)](https://s3.us-east-1.amazonaws.com/assets.ipospays.com/V2+Registration+Video.mp4) + +## What it supports + +Sale, refund (standalone, after settlement), void (before settlement, by RRN), pre-authorization and +ticket (capture by RRN), and batch settlement. Optional tip and fee amounts. Contactless only: no chip +insert or swipe on the iPhone. + +## Requirements + +- iPhone XS or later, iOS newer than 16.9, device region set to **US**. +- A merchant onboarded on iPOSpays (sandbox for testing, production for live) with a **Tap on Phone + (TOP) TPN**, and the **merchant code** from the portal: Settings → Generate ECOM/TOP Merchant Keys → + pick the TOP TPN. +- Accept Apple's Tap to Pay terms on the device (in iPOSgo!). +- Dejavoo supplies the library and a demo app through a Diawi install link after receiving the test + device's UDID. Use a separate test device and don't change its date or time during testing. +- URL scheme keys `invokeApplink` and `ogApplink` (case sensitive) in the app's configuration. +- Processors listed for iPhone Tap to Pay: TSYS, Fiserv Omaha, Fiserv North. **Confirm with Valmar in + writing** that a Tap to Pay account on one of these is approved for the store's hemp/CBD products. + +## Security: who handles what + +**Apple and Dejavoo:** reading the card, encryption, and keeping card numbers out of Rupert. Rupert +receives only the result fields; it never sees a card number. The store still completes its yearly PCI +self-assessment (Valmar says which form). + +**Rupert:** + +- **Never trust the returned "approved" by itself.** The result comes back through a URL scheme that + any app could open with a fake approval. The server marks a sale paid only after confirming the + transaction with Dejavoo (transaction status lookup or a matching FEED event, which Rupert already + receives). +- **Amount:** the server sets the amount; the returned amount must match. +- **No double charges:** a durable attempt before the tap; a lost or unclear result is looked up, + never retried as a new charge. Reuse the rules in `Pos::DejavooTerminalPayment`. +- **Permissions and audit:** who may take payments and refunds, and a log of every attempt. +- **Keep only whitelisted fields** (as the SPIn adapter does). Do not store `AcntFirst4`, tokens or + anything beyond what reconciliation needs. +- The merchant code and TPN live in encrypted per-workspace settings, never in the app binary. +- Per-workspace switch, off by default. + +## Plan and timing + +| Step | Needs | Rough time | +| --- | --- | --- | +| Tap with Dejavoo's demo app on the owner's iPhone | Library and demo app from Dejavoo | Same day it arrives | +| Test tap from Rupert's register (sandbox) | Library in hand, TOP TPN and merchant code | 1–2 days | +| Full version: refunds, voids, batch close, server confirmation, settings, tests | — | About a week more | +| Live payments at the store | Production TOP TPN boarded by Valmar with hemp/CBD approval; App Store update review | Valmar's timeline; review about 1–2 days | + +Sandbox payments move no money. + +## Status (2026-11-13) + +- iPOSpays sandbox merchant account is set up (from the ISV sandbox request, 2026-11-03). +- No written confirmation yet of approval for the iOS deep linking SDK; ask Dejavoo's ISV team to + confirm and send the library and demo app. +- Separately, a P18 Android terminal is being ordered in developer mode for terminal deep linking + (the Android counter-terminal path). It is not needed for iPhone Tap to Pay. +- Rupert has no payment code in the iPhone app yet. + +## Open questions for Dejavoo and Valmar + +1. Written confirmation that Rupert is approved for iPhone Tap to Pay deep linking (V2). +2. Does the sandbox account need a separate Tap on Phone TPN? Is one issued per phone? +3. Does Rupert's app need Apple's Tap to Pay entitlement, or only iPOSgo!? (Docs suggest only iPOSgo!.) +4. Which processor will the production TOP TPN use, and is hemp/CBD approved there in writing? +5. Is PIN debit supported on tap, and what happens above the contactless limit? +6. Can iPOSgo! return to Rupert automatically after approval (no extra taps for the cashier)? + +## Sources + +- [iOS deep linking v2](https://app.theneo.io/dejavoo/tap-to-pay-on-iphone/deep-linking/v2) and its + [TPN register](https://app.theneo.io/dejavoo/tap-to-pay-on-iphone/deep-linking/v2/tpn-register), + [perform transactions](https://app.theneo.io/dejavoo/tap-to-pay-on-iphone/deep-linking/v2/tpn-register/perform-transactions) + and [sample responses](https://app.theneo.io/dejavoo/tap-to-pay-on-iphone/deep-linking/v2/tpn-register/sample-responses) pages +- [Tap to Pay on iPhone overview](https://app.theneo.io/dejavoo/tap-to-pay-on-iphone/deep-linking) +- [iPOSpays Developer Central](https://docs.ipospays.com/) +- [Dejavoo ISV presentation](https://dejavoo.io/wp-content/uploads/2025/08/Dejavoo_Presentation_for_ISVs.pdf)