Integration Flow
Architecture
System actors and request flow for the Mini App integration.
Architecture
Mini App integration has 3 operator-owned backend responsibilities:
- call launch API
- implement wallet adapter
- implement webhook receiver
OpenPoly owns the Mini App UI, Opinion market engine, shared Polyflight engine, execution state, and callback dispatch.
Actors
- operator backend
- operator wallet service
- operator webhook receiver
- OpenPoly operator API
- OpenPoly Mini App client
- OpenPoly execution and webhook systems
End-to-end shape
sequenceDiagram participant O as Operator Backend participant P as OpenPoly Operator API participant C as Mini App Client participant W as Operator Wallet participant H as Operator Webhook Receiver O->>P: POST /api/operator/launch P-->>O: launch_url + expires_at O->>C: redirect user to launch_url C->>P: redeem launch token P-->>C: Mini App session C->>P: quote and submit Opinion order or Polyflight ticket P->>W: exact native debit/credit/reversal as needed W-->>P: wallet operation result P-->>C: updated order, ticket, or payment state P->>H: signed webhook event H-->>P: 2xx or retryable failure
Core invariants
- browser never receives operator API key
- browser never receives wallet adapter secret
- launch token is short-lived and single-use
- wallet mutation and Polynion DB write are not one atomic transaction
- webhook delivery happens after business state commit
- Polyflight wallet amounts are native IDR; its frozen FX observation affects shared-flight comparison only
- one operator wallet outage does not change a committed Polyflight result
- callback replay/backfill delivers notifications; it never reruns the underlying trade, redemption, or wallet mutation
- operator reporting and support cannot authorize a monetary correction; wallet-outcome decisions require authorized Polynion review
What operator builds
- server-side launch call
- wallet adapter endpoints
- webhook receiver with dedupe
- dashboard configuration and operational process
What Polynion provides
- Mini App UX
- quote and execution engine
- session and launch token handling
- operator-facing reporting APIs
- webhook dispatch and replay surfaces
Separate the control planes
| Surface | Purpose | Credential boundary |
|---|---|---|
| Operator API | Backend launch and scoped reporting/configuration | Server-held API key, or authorized dashboard staff session. |
| Operator Dashboard | Human operations, evidence inspection, support, and requests | Staff login; page visibility follows effective scopes. |
| Mini App client | End-user quotes, orders, tickets, and proof | Redeemed user session; never the operator API key. |
| Wallet adapter | Operator ledger reads and idempotent mutations | Dedicated wallet credentials and optional signing. |
| Webhook receiver | Durable business-event ingestion | Raw-body HMAC verification and event_id deduplication. |
Support conversations are shared within an operator, but remain separate from user sessions and Polyflight purchase tickets. Market requests require staff consent and Polynion approval; visibility configuration alone does not create a private market.