Skip to content

docs: test mode — concept page, authentication page, test-first quickstart#79

Open
riveign wants to merge 11 commits into
mainfrom
docs/test-mode
Open

docs: test mode — concept page, authentication page, test-first quickstart#79
riveign wants to merge 11 commits into
mainfrom
docs/test-mode

Conversation

@riveign

@riveign riveign commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

What

Public docs coverage for test mode, targeting the Jul 15 GA. Follows the Test Mode — Public Docs Alignment doc + the comments on it. Opened as a draft to iterate on — comment freely.

New pages

  • payments/merchant/test-mode — the concept page: account-level test/live, switch-by-key (no test flag/param anywhere), wcp_test_ prefix, what test payments do/don't do (no on-chain execution, synthetic test:{paymentId} tx hash, fixed 1-unit amounts), webhooks fire in test mode, go-live path. Includes an environment diagram with test mode in purple (per Rocky's diagram ask + Tomas R.'s purple-as-test-color proposal).
  • api-reference/authentication — the previously-missing auth page: Api-Key header, test vs live key semantics, 401/403, key safety.

Edits

  • Quickstart reframed test-first: step 1 creates a test key, examples use wcp_test_, synthetic txId in the status example, closing "Go live" section.
  • Overview — test-before-live line + Merchant Quickstart / Test Mode cards in Get Started.
  • Wallet AI-prompt blurbs (flutter + react-native) — the two contradictory "Test Payment Links" sections now agree (dashboard self-serve); the docs' last "sandbox" mention is gone (canonical term: test mode).
  • Nav (docs.json) — both version blocks updated.

Decisions baked in (from the alignment thread)

  • Devs use the same API as today — the environment is selected by the key alone.
  • Docs explicitly state that responses/webhooks carry no environment field (it's determined by your key).
  • The &_t=1 gateway tag is treated as an implementation detail — not documented.

Not in this PR (follow-ups)

  • OpenAPI snapshots are stale — they still advertise the dead not_sandbox_api_key enum. They should be regenerated, not hand-edited, so the JSONs are untouched here.
  • BX page — Rocky asked whether test mode needs a page on the buyer-experience side; open question, happy to add in a follow-up.
  • Dashboard screenshots of test-key provisioning (and purple test-mode UI) once the GA build is final.

mint broken-links passes.

🤖 Generated with Claude Code

@riveign @claude
docs: add test mode concept + authentication pages, reframe quickstar…
720a70d 
…t test-first

- New payments/merchant/test-mode page: account-level test/live model,
  switch-by-key, wcp_test_ prefix, synthetic tx hashes, webhook behavior,
  go-live path; env diagram in purple (test-mode color)
- New api-reference/authentication page: Api-Key header, test vs live
  key semantics, no environment field on responses
- Quickstart reframed test-first with wcp_test_ examples + go-live section
- Overview: test-before-live messaging + merchant/test-mode cards
- Reconcile the two contradictory wallet Test Payment Links blurbs;
  remove the last "sandbox" mention (term is "test mode")

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign riveign marked this pull request as ready for review July 10, 2026 07:39
riveign and others added 10 commits July 10, 2026 10:32
@riveign @claude
chore: retrigger preview deployment
99c1e02 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): feedback round — realistic amounts, pilot framing, d…
351050f 
…ashboard walkthrough, no webhook mentions

- Amounts: test options now quote from the requested amount at real
  exchange rates (pay-core #1028) — replaces stale fixed-1-unit claim
- Replace go-live framing with the pilot limit: live env starts in
  pilot, Pilot to Live card, Request to go live flow (MX #798 copy)
- New dashboard walkthrough: create a test payment + Simulation
  actions status transitions (with state diagram)
- Quickstart: test-vs-live intro up front; 'From test to live' =
  same six steps with a live key
- Remove all webhook mentions (not released yet), incl. pre-existing
  quickstart tip; purple = docs convention only (dashboard uses env
  selector)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): status simulation via hosted payment page Test Conso…
71aba9a 
…le + dashboard menu

Verified against buyer-experience: purple test banner + Test Console
(Confirm success / Simulate failure / Expire / Cancel) + simulated
Test Wallet on the payment page; purple claim extended to payment page.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): add Simulation actions screenshot
f1bd00c 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): add dashboard + payment-page screenshots
49aae37 
Environment selector, create-payment dialog, payment-created link,
hosted payment page (purple banner + Test Console), and Test Console
actions. Pilot to Live card shot pending team update.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): drop 'environment' wording, merchant step, leaner im…
1b8b9aa 
…age layout

- Say test/live *mode* everywhere; never 'environment' (incl. table
  headers and the no-env-field warnings)
- Create-a-test-payment: add the create-merchant step (per-mode data)
- One screenshot in the create section; payment page + Test Console
  side by side in columns (fixes stacked/overlapping frames)
- Remove now-unused env-selector + payment-created screenshots
- 'Allowed status transitions' subtitle over the state diagram
- Drop leftover webhooks mention in the intro

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): add margin between stacked image frames
5b36c82 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(test-mode): move page into the WalletConnect Pay section
b7018ff 
payments/merchant/test-mode → payments/test-mode; nav entry moves to
the WalletConnect Pay group (both version blocks) so the Merchants
section opens with Quickstart. All links updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
chore: remove local mise.toml committed by mistake
f1527d2 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@riveign @claude
docs(nav): place Test mode after CEX Coverage
64ba6b2 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
rtomas
rtomas approved these changes Jul 13, 2026
View reviewed changes

@rtomas rtomas left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer mermaid without the actions buttons

Comment thread payments/test-mode.mdx

Test and live are separated at the **account level**, and you choose the mode by **which API key you use**. There is no `test` flag or mode parameter on any request — a payment created with a test key is a test payment, and a payment created with a live key is a live payment.

```mermaid

@rtomas rtomas Jul 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```mermaid
```mermaid actions={false}

Comment thread payments/test-mode.mdx

Whichever surface you use, a test payment can only move along these paths:

```mermaid

@rtomas rtomas Jul 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```mermaid
```mermaid actions={false}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rtomas rtomas rtomas approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@riveign @rtomas