@mindtdilly / Omnipay-2
Code Commits Issues Pulls Sessions CI/CD
main
feat/agentic-commerce-x402-local-sim feat/checkout-funding-ach main
mdx 104 lines 4.92 KB
Raw
1 ---
2 title: "ProcureNet Orchestration Modes: Resolved, Partial, Anonymous"
3 sidebarTitle: "Modes"
4 description: "Explore how ProcureNet's three orchestration modes shape the checkout experience, transport protocol, and available prefill data for each session."
5 ---
6
7 Orchestration modes define the capabilities and experience of a checkout session. ProcureNet assigns a mode to every session at creation time, derived directly from the buyer's [Wallet Confidence Score (WCS)](/concepts/wallet-confidence-score). The mode is fixed for the lifetime of that session — it determines which real-time transport protocol to use, whether prefill data is available, and how much information the buyer will need to provide manually. Choosing which signals to supply at orchestration time is therefore the most important decision you make when starting a procurement flow.
8
9 ## Resolved Mode (WCS ≥ 100)
10
11 Resolved mode activates when ProcureNet has high confidence in the buyer's identity — typically when a `customerId` is present. This is the premium checkout experience.
12
13 <CardGroup cols={2}>
14 <Card title="Transport" icon="signal-stream">
15 **Server-Sent Events (SSE)** — a lightweight, unidirectional stream that delivers session events with minimal overhead.
16 </Card>
17 <Card title="Prefill" icon="wand-magic-sparkles">
18 **Available** — call `GET /api/v7/sessions/{id}/prefill` to retrieve the customer's saved profile and payment preferences. Requires a Bearer JWT.
19 </Card>
20 </CardGroup>
21
22 In resolved mode, ProcureNet pre-populates checkout fields using the buyer's stored data, reducing friction to near zero for returning customers. The prefill endpoint returns structured profile and payment-preference objects that your UI can apply directly.
23
24 ```bash
25 curl https://api.procurenet.io/api/v7/sessions/sess_abc/prefill \
26 -H "Authorization: Bearer <JWT>"
27 ```
28
29 ## Partial Mode (WCS 40–99)
30
31 Partial mode activates when ProcureNet recognizes some signals — such as an email or phone number — but lacks a confirmed customer identity. The session proceeds interactively.
32
33 <CardGroup cols={2}>
34 <Card title="Transport" icon="arrows-rotate">
35 **WebSocket** — a full-duplex channel that supports both sending and receiving messages, suitable for guided multi-step flows.
36 </Card>
37 <Card title="Prefill" icon="ban">
38 **Not available** — the buyer must supply any missing identity and payment information during the session.
39 </Card>
40 </CardGroup>
41
42 In partial mode, your UI should guide the buyer through completing their profile. Collecting a `customerId` during this flow and using it in a new session will upgrade the experience to resolved mode.
43
44 ## Anonymous Mode (WCS < 40)
45
46 Anonymous mode activates when ProcureNet has no reliable signals about the buyer. This covers guest checkouts and first-time visitors.
47
48 <CardGroup cols={2}>
49 <Card title="Transport" icon="arrows-rotate">
50 **WebSocket** — same bidirectional channel as partial mode, supporting the full interactive checkout flow.
51 </Card>
52 <Card title="Prefill" icon="ban">
53 **Not available** — the buyer completes the full checkout form from scratch, with no prior data applied.
54 </Card>
55 </CardGroup>
56
57 Anonymous mode imposes no restrictions on transaction completion — it simply means more manual input is required. Consider prompting buyers to create an account during or after checkout so future sessions benefit from a higher WCS.
58
59 ## Connecting to the Transport
60
61 Once you have a `session_id` and know the `transport` from the `POST /api/v7/orchestrate` response, open the appropriate real-time connection.
62
63 <Tabs>
64 <Tab title="SSE (Resolved)">
65 Server-Sent Events are native to the browser. Open the stream with `EventSource` and listen for named session events.
66
67 ```javascript
68 const source = new EventSource('/api/v7/sessions/sess_abc/stream');
69
70 source.addEventListener('state_change', (event) => {
71 const data = JSON.parse(event.data);
72 console.log('New state:', data.state);
73 });
74
75 source.addEventListener('error', () => {
76 source.close();
77 });
78 ```
79 </Tab>
80 <Tab title="WebSocket (Partial / Anonymous)">
81 WebSocket provides full-duplex communication. Use the secure `wss://` scheme in production.
82
83 ```javascript
84 const ws = new WebSocket('wss://api.procurenet.io/api/v7/sessions/sess_abc/ws');
85
86 ws.onopen = () => {
87 console.log('Session channel open');
88 };
89
90 ws.onmessage = (event) => {
91 const data = JSON.parse(event.data);
92 console.log('Session event:', data);
93 };
94
95 ws.onerror = (error) => {
96 console.error('WebSocket error:', error);
97 };
98 ```
99 </Tab>
100 </Tabs>
101
102 <Tip>
103 Upgrading a session from anonymous or partial to resolved is not possible in-place. To give a buyer the resolved experience after collecting additional signals mid-flow, create a new session via `POST /api/v7/orchestrate` and pass the newly gathered signals in the `hints` object. The new session will receive the higher WCS and switch to SSE automatically.
104 </Tip>