# Switch Direct Connectivity — Worklist (Deferred)

**Part of:** Acquiring Platform Transformation program (Workstream D).
**Status:** see [`docs/ACQUIRING_PLATFORM_PROGRESS.md`](../ACQUIRING_PLATFORM_PROGRESS.md). Explicitly deferred — `mercury_device_middlelayer` is **not** to be touched in
this program's current pass. This is a worklist entry for when it is picked up, not a design
document.

---

## Why deferred

`mercury_device_middlelayer` already has substantial existing architecture for this. Its own
`docs/UPSTREAM_NETWORK_ARCHITECTURE.md` documents a pluggable multi-network system:

- `UpstreamRouter`, `UpstreamConnectionManager`, `UpstreamHealthMonitor`, and per-network
  `NetworkConnector` GenServers under a `NetworkConnectorSupervisor`
- BIN-range / MTI-pattern / field-value routing rules
- Connection pooling, health monitoring, circuit breakers, weighted load balancing
- Already scaffolded for Visa/Mastercard/Amex/Discover connectors, currently pointed at
  placeholder hosts (`visa-processor.example.com` etc.)

Separately, `acquirer/ysp/` (the current external acquirer) and `acquirer/mastercard/`
(actually the MPGS *gateway*, not a direct network connection) are the existing
`Acquirer.Behaviour` adapter implementations — the precedent for adding new adapters without
touching existing ones.

Given this architecture already exists, redesigning it now would be premature and against
explicit instruction. This worklist captures what's left, for later.

> **Non-disruption**: when this workstream is picked up, the rule carries over from every
> other workstream in the program — `acquirer/ysp/` and the rest of today's switch behavior
> are never modified. New adapters are added *alongside* it, and per-merchant routing config
> decides which path a given merchant's transactions take, so YSP-routed merchants see zero
> behavior change on the day direct-connect adapters ship.

---

## Worklist (not started)

1. **Operational, not code** — real network credentials, SSL certs
   (`config :da_product_app, :upstream_ssl`), and formal scheme certification testing against
   the already-built `NetworkConnector`/`UpstreamRouter` architecture, for Mastercard MIP and
   Visa VAP specifically. Today's config is Visa/Mastercard/Amex/Discover-shaped generically,
   not MIP/VAP-specific: **confirm whether the existing connector design maps directly, or
   needs protocol-level adjustments for MIP/VAP's specific connection requirements.**

2. **New adapter modules**, if the direct-connect path needs acquirer-side transaction
   processing logic beyond the network-connector layer: `acquirer/mastercard_mip/` and
   `acquirer/visa_vap/`, implementing the existing `Acquirer.Behaviour`, alongside — never
   replacing — `acquirer/ysp/`. Existing customers keep routing through YSP while
   direct-connect customers route to the new adapters, selected via the existing
   `upstream_router.ex` / `gateway_router.ex` config-driven mechanism. **This is the concrete
   mechanism for supporting both customer types without disrupting the current
   implementation.**

3. **Data integration (later)** — once Scheme Management Phase 2 (BIN/IIN Management) exists,
   replace the static BIN-range routing rules in `config/upstream_networks.exs` and the
   hardcoded PAN-prefix detection in `switch/routing_rules.ex` with live lookups against
   `scheme_core`'s BIN data. Likely via Scheme Management Phase 13's external lookup API, with
   local caching (`cachex`, already a dependency) since this sits on the switch's hot
   transaction path.

4. **Settlement feed** — the switch needs to emit a transaction dump for
   `settlement_core`'s new `mercury_switch/` ingestion namespace (see
   `docs/Clearing-System/requirement-summary.md` §3.0). The data already exists in the
   switch's `pos_transaction`/`pos_temp_transaction` tables; what's needed is the export
   mechanism (file or internal). **This is the one item that unblocks other workstreams**, so
   it may be worth pulling forward ahead of items 1-3.

---

## Related

- `mercury_device_middlelayer/docs/UPSTREAM_NETWORK_ARCHITECTURE.md` — the existing design
- `docs/Clearing-System/requirement-summary.md` — consumes item 4's dump
- `docs/Scheme-System/implementation-plan.md` — Phase 2 supplies item 3's BIN data
- `docs/Terminal-Management/direct-acquiring-extension.md` §2.5 — the switch's `crypto/` PIN
  translation path stays with the switch, not `TmsCore.KeyManagement`

## Explicit non-goals of this document

No code changes, no schema design, no adapter implementation detail — a pointer and a
worklist, nothing more, until this workstream is picked up.