Connect-Day Register — what waits for the real contracts
The eSIM store runs on a mock provider and a mock payment gateway during development. The mock is a stand-in, never the product. Some capabilities were deliberately not built, because their real shape depends on contracts we do not have yet. This page is the single list of those items, so nothing is silently forgotten and nobody mistakes a parked item for a missing one.
Every item states what it is, why it is parked, and what unblocks it.
Not on this list: the seven shipped follow-up commits of the 2026-08-06 batch on PR #84 — iccidSuffix on issued profiles, paymentId on the order views, throttleNoteAr localized throttle note, kill-switch read exemption for owned-order reads, admin stuck-order recovery, the expected-price guard, and the tightened SAR/USD FX bounds. Those are committed work, not parked work.
Gate 1 — Real eSIM provider contract
These need a signed provider whose API and commercial terms answer questions the mock cannot.
| Item | What it is | Why it waits |
|---|---|---|
| Provider hook + startup guard | Mechanical enforcement of the issuance idempotency contract (retry with the same orderId must never create a second billable profile) when a real adapter registers | The contract is documented on issueProfile today. Enforcement can only be verified against a real adapter |
| Reissue / transfer | Issue a replacement profile for a burned or lost eSIM (deleted profile, wiped phone, new device) | Reissue is a provider capability with commercial terms: who pays the second issuance, does data carry over, is it capped. Guessing against the mock risks a rewrite. Until then, support handles these cases manually and the apps promise nothing |
| Network / operator display | Show which local network the eSIM uses at the destination | Only the provider's catalog knows the carrier mapping, and providers differ in whether and how they expose it |
| Usage / expiry API | Data-usage meters and expiry countdowns | Usage happens on a foreign operator's network. Only the provider can report it. "Starts on first use" expiry is equally invisible without their signal |
| Top-up execution | Actually topping up an existing eSIM (the catalog already serves canTopUp as display info) | Needs provider top-up SKUs, pricing, and an apply-to-this-ICCID API |
| Provider health + sync history | Admin visibility: provider up or down, last sync result, per-run counts | Meaningful only with a real, occasionally failing provider. The sync worker already computes run results and can persist them when this lands |
Note for provider selection: reissue capability and a usage API should be evaluation criteria when choosing the real provider. A provider without reissue makes lost-phone support permanently manual.
Gate 2 — Real payment provider (PSP) contract
These need the contracted PSP because the PSP defines them.
| Item | What it is | Why it waits |
|---|---|---|
| 3DS flows | Card authentication challenges during payment | Which flows, and how they render, depend on the PSP. The intent endpoint already returns a clientSecret so a confirmation step can be inserted without redesign |
| Billing descriptor | The merchant text on the customer's card statement | Defined with the PSP contract |
| Processing currency | Store charges process in USD; local activation charges process in SAR. A cardholder whose card runs in another currency pays their bank's conversion spread on the USD charge | If international sales become a real segment, multi-currency acquiring (charging USD cards in USD) is a PSP capability to buy then. Order rows already snapshot presentment, charge, and rate, so no data-model change is needed |
| Capture model revisit | Today: charge-on-pay. Alternative: authorize at checkout, capture only after the eSIM issues, void on failure | Authorize-then-capture would largely dissolve the "customer paid, fulfillment failed" problem, but it is a PSP capability. Revisit deliberately at contract day |
| Refund mechanics | The API path that moves money back | PSP-defined. The policy half is Gate 3 |
Gate 3 — Business decisions (no external contract needed)
Nothing blocks these except a decision. They are queued, not blocked.
| Item | What it is | Who decides |
|---|---|---|
| Refund policy | Is there a refund window? Automatic refund when fulfillment permanently fails? Who authorizes one? | Product / legal (lead) |
| VAT split on receipts | Receipts today show a SAR total only. ZATCA-relevant once real money flows: split into net + VAT (15%) | Finance / lead. Accounting logic, buildable any time |
| CST licensing check | Confirmation that reselling foreign-network eSIMs from KSA needs no telecom license. No public ruling exists — long lead time, start early | Legal / telecom counsel, before any real sale |
| ZATCA position | Treatment of sales used outside the Kingdom (use-and-enjoyment rule) + deemed-supplier exposure on the domestic leg | Tax advisor / ZATCA ruling, before any real sale |
| International expansion path | Widening past the KSA/GCC launch scope: own OSS registrations + tax engine, or a Merchant-of-Record platform (hybrid possible). Full background on the Currency & Market model page | Lead + Ahmed, at expansion time |
Register approved 2026-08-05. Source analyses: the Plan 007 review and fact-check, the connect-day answers sheet shared with the mobile side, and the PR #84 review rounds.