Purchase flow — SDK bridge

The end-to-end purchase flow and why it must stay SDK-mediated.

Purchases are the highest-stakes integration surface. They are SDK-mediated by design, and this guide explains the full flow plus the invariants.

Why SDK-mediated?

The SDK core is the only place that knows the purchase endpoint paths (/api/v1/security/pin-session, .../{id}/verify, /api/v1/security/events). Your game provides business data only. This keeps every client in the ecosystem on the same, enforced, secure path — including the environment pre-flight that a hand-rolled client would skip.

The flow

your game                        PurchaseClient                backend
     │ mint(itemId, amount, purchaseId, platform, details)
     ├─► check_environment_integrity()
     │      └─ risks? ─────────────► Blocked + ENV_COMPROMISED
     │                                                        (no request)
     │
     ├─► POST /api/v1/security/pin-session
     │      ◄─ { sessionId, sessionToken, expiresInMs, envLevel }
     │
     player enters PIN
     │
     ├─► verify_pin(sessionId, sessionToken, pin, VerifyRequest)
     │      └─ POST /api/v1/security/pin-session/{id}/verify
     │           ◄─ Valid | WrongPin{locked,attempts} | Failed{code,message}
     │
     └──► report_security_event(...)   // best-effort audit (202)

The pre-flight gate

• Risks DEVICE_ROOTED / DEBUGGER_ATTACHED → level COMPROMISED → blocked.
• Any other risk (screen capture, suspicious accessibility) → WARN → blocked.
• Clean host → SAFE → a one-time PIN session is minted.

When blocked, an ENV_COMPROMISED security event is reported best-effort, and no purchase request is sent.

Verification invariants

Verified sessions are consumed on success and failures are rate-limited. verify_pin is single-shot — never retry it.

• amount travels as a decimal string on the wire.
• Always send a fresh idempotencyKey per authorized withdrawal.
• destinationAddress is the single authorization target — validate it carefully before asking the player to approve.
• x-secure-session carries the minted sessionToken; the bearer access token authorizes the SDK side of the call.

Wallet custody boundary

The SDK never sees, holds, or signs wallet private keys. The player authorizes a withdrawal by PIN; MusterBox’s custody layer (multi-party computation) executes it. Never pass a wallet key or mnemonic to the SDK, and never log custody material.

Rules of the order

1. Mint a PIN session only from a clean environment.
2. Show the PIN prompt; never log the PIN.
3. Verify once; handle WrongPin (retry with feedback) vs Failed (session/transport) differently.
4. On Valid, proceed with fulfillment; on locked, stop.

Next: Environment integrity & anti-tamper.