@mindtdilly / Omnipay
Code Commits Issues Pulls Sessions CI/CD
feat/checkout-funding-ach
feat/agentic-commerce-x402-local-sim feat/checkout-funding-ach main
mdx 104 lines 5.28 KB
Raw
1 ---
2 title: "ProcureNet Session Lifecycle and State Transitions"
3 sidebarTitle: "Session Lifecycle"
4 description: "Understand how ProcureNet sessions progress through states from creation to completion, and how to drive each transition correctly."
5 ---
6
7 Sessions are the core unit of a ProcureNet procurement flow. Every buyer interaction — from the moment checkout begins to the final payment confirmation — is tracked inside a single session object. Each session moves through a well-defined state machine: states advance in a fixed order, illegal transitions are rejected with deterministic error codes, and every successful transition emits a real-time event over the session's transport channel. Understanding the lifecycle helps you build reliable integrations that handle retries, timeouts, and escrow correctly.
8
9 ## Session States
10
11 A session passes through the following states in order. Not every session visits every state — the `escrow_pending` state only applies to high-value transactions.
12
13 <CardGroup cols={2}>
14 <Card title="created" icon="circle-plus">
15 The session has been initialized by `POST /api/v7/orchestrate`. The WCS score, mode, and transport have been assigned. No payment data has been provided yet.
16 </Card>
17 <Card title="active" icon="circle-play">
18 The buyer's transport connection has been established (SSE or WebSocket). The session is live and accepting input.
19 </Card>
20 <Card title="funded" icon="circle-dollar-sign">
21 A funding method has been successfully set via `POST /api/v7/sessions/{id}/funding-method`. The session is ready to proceed to completion or escrow.
22 </Card>
23 <Card title="escrow_pending" icon="lock">
24 For high-value transactions only. Escrow has been initiated and is awaiting acceptance via `POST /api/v7/sessions/{id}/escrow-accept`.
25 </Card>
26 <Card title="completed" icon="circle-check">
27 The procurement flow finished successfully. The session is now immutable.
28 </Card>
29 <Card title="cancelled" icon="circle-xmark">
30 The session was cancelled before completion. No charges were processed.
31 </Card>
32 </CardGroup>
33
34 <Note>
35 Illegal state transitions — such as attempting to accept escrow on a session that is not yet funded — are rejected synchronously with a deterministic error code in the response body. Build your integration to check for these codes rather than relying on HTTP status alone.
36 </Note>
37
38 ## Driving a Session Through Its Lifecycle
39
40 Follow these steps to move a session from creation to completion.
41
42 <Steps>
43 <Step title="Create the session">
44 Call `POST /api/v7/orchestrate` with your buyer signals in the `hints` object. The response returns a `session_id`, `wcs_score`, `mode`, and `transport`. Store the `session_id` — every subsequent call requires it.
45
46 ```bash
47 curl -X POST https://api.procurenet.io/api/v7/orchestrate \
48 -H "Content-Type: application/json" \
49 -d '{
50 "hints": {
51 "customerId": "cust_123",
52 "email": "buyer@example.com"
53 }
54 }'
55 ```
56 </Step>
57
58 <Step title="Connect to the real-time transport">
59 Use the `transport` value from the response to open the correct channel. Resolved sessions use SSE; partial and anonymous sessions use WebSocket. See [Orchestration Modes](/concepts/orchestration-modes) for connection examples.
60 </Step>
61
62 <Step title="Set the funding method">
63 Call `POST /api/v7/sessions/{id}/funding-method` with the buyer's chosen payment method. This advances the session from `active` to `funded`.
64
65 ```bash
66 curl -X POST https://api.procurenet.io/api/v7/sessions/sess_abc/funding-method \
67 -H "Authorization: Bearer <JWT>" \
68 -H "Content-Type: application/json" \
69 -d '{ "method": "usdc", "network": "base" }'
70 ```
71 </Step>
72
73 <Step title="Accept escrow (high-value transactions only)">
74 If the transaction value exceeds the escrow threshold, the session enters `escrow_pending`. Call `POST /api/v7/sessions/{id}/escrow-accept` to acknowledge the escrow terms and advance the session.
75
76 ```bash
77 curl -X POST https://api.procurenet.io/api/v7/sessions/sess_abc/escrow-accept \
78 -H "Authorization: Bearer <JWT>"
79 ```
80 </Step>
81
82 <Step title="Advance to completion">
83 Call `POST /api/v7/sessions/{id}/transition` to move the session toward `completed`. You may need to call this endpoint more than once if your flow has intermediate steps — each call advances the state machine by one step.
84
85 ```bash
86 curl -X POST https://api.procurenet.io/api/v7/sessions/sess_abc/transition \
87 -H "Authorization: Bearer <JWT>" \
88 -H "Content-Type: application/json" \
89 -d '{ "action": "confirm" }'
90 ```
91 </Step>
92 </Steps>
93
94 ## Session Expiry
95
96 Sessions have a finite lifetime. If a session expires before you complete all transitions, any further API calls against that session ID return **410 Gone**. When you receive a 410, you must create a new session from scratch — expired sessions cannot be resumed or extended.
97
98 <Warning>
99 Do not cache session IDs across user visits or browser reloads without validating that the session is still active. Always check for 410 responses and handle them by restarting orchestration.
100 </Warning>
101
102 <Tip>
103 Every state transition emits an event over the session's transport channel. Subscribe to these events in your UI to drive real-time progress indicators without polling the API.
104 </Tip>