@mindtdilly / Omnipay
Code Commits Issues Pulls Sessions CI/CD
feat/agentic-commerce-x402-local-sim
feat/agentic-commerce-x402-local-sim feat/checkout-funding-ach main
mdx 182 lines 6.72 KB
Raw
1 ---
2 title: "Integrate ProcureNet Checkout into Your Application"
3 sidebarTitle: "Integrate Checkout"
4 description: "Embed ProcureNet's AI-orchestrated checkout flow into your app — from collecting buyer signals to advancing through session states."
5 ---
6
7 ProcureNet's checkout orchestration flow starts the moment you send buyer signals to the session API. The platform scores those signals using the Wallet Confidence Score (WCS) engine, selects the right transport layer, and returns a session your frontend connects to in real time. This guide walks you through every step, from collecting buyer hints to advancing the session to a completed state.
8
9 <Steps>
10
11 ### Collect Buyer Signals
12
13 Before starting a session, gather the buyer signals you have available. ProcureNet's WCS engine weights each signal and assigns a score out of 200. The higher the score, the richer the prefill data you get and the more optimized the transport.
14
15 <CardGroup cols={2}>
16 <Card title="customerId" icon="fingerprint">
17 **100 pts** — Your internal customer identifier. The single highest-value signal. Always pass this when the buyer is authenticated.
18 </Card>
19 <Card title="email" icon="envelope">
20 **40 pts** — Buyer's email address. Optional but strongly recommended for guest or partially-identified buyers.
21 </Card>
22 <Card title="phone" icon="phone">
23 **40 pts** — Buyer's phone number. Combines with email to push partial sessions closer to the resolved threshold.
24 </Card>
25 <Card title="deviceId" icon="mobile">
26 **20 pts** — A stable device fingerprint. Optional, but it can be the deciding factor for crossing key score thresholds.
27 </Card>
28 </CardGroup>
29
30 The WCS engine uses these scores to classify the session into one of three modes:
31
32 | Score Range | Mode | Transport |
33 |---|---|---|
34 | ≥ 100 | `resolved` | SSE |
35 | 40 – 99 | `partial` | WebSocket |
36 | < 40 | `anonymous` | WebSocket |
37
38 <Tip>
39 Pass `deviceId` alongside `email` or `phone` to reach a WCS of 100 even without a `customerId`. A score of 100 unlocks the `resolved` mode and SSE transport — which enables full prefill. You can also combine all four signals for a maximum score of 200.
40 </Tip>
41
42 ### Start the Orchestration Session
43
44 Call `POST /api/v7/orchestrate` with your buyer hints and transaction details. This endpoint does not require authentication — include whatever buyer signals you have available. The response includes the `session_id`, WCS score, resolved mode, and the transport your client should connect to.
45
46 ```typescript
47 const res = await fetch('https://api.procurenet.io/api/v7/orchestrate', {
48 method: 'POST',
49 headers: {
50 'Content-Type': 'application/json'
51 },
52 body: JSON.stringify({
53 amount: 250.00,
54 currency: 'USD',
55 hints: {
56 customerId: 'cust_123',
57 email: 'buyer@example.com'
58 }
59 })
60 });
61
62 const { session_id, wcs_score, mode, transport } = await res.json();
63 ```
64
65 Store `session_id` — every subsequent API call in this checkout flow requires it.
66
67 ### Connect to the Session Stream
68
69 Use the `transport` value from the previous response to open the appropriate real-time connection to your session.
70
71 <Tabs>
72 <Tab title="SSE (resolved mode)">
73 Use SSE when `transport` is `"sse"`. This is the most reliable transport for fully-identified buyers.
74
75 ```typescript
76 const eventSource = new EventSource(
77 `https://api.procurenet.io/api/v7/sessions/${session_id}/stream`,
78 { withCredentials: true }
79 );
80
81 eventSource.onmessage = (event) => {
82 const data = JSON.parse(event.data);
83 console.log('Session state:', data.state);
84 };
85 ```
86 </Tab>
87 <Tab title="WebSocket (partial / anonymous)">
88 Use WebSocket when `transport` is `"websocket"`. This handles partial and anonymous sessions.
89
90 ```typescript
91 const ws = new WebSocket(
92 `wss://api.procurenet.io/api/v7/sessions/${session_id}/stream`
93 );
94
95 ws.onmessage = (event) => {
96 const data = JSON.parse(event.data);
97 console.log('Session state:', data.state);
98 };
99 ```
100 </Tab>
101 </Tabs>
102
103 ### Handle Prefill for Resolved Sessions
104
105 If `mode` is `"resolved"` (WCS ≥ 100), call `GET /api/v7/sessions/{id}/prefill` to retrieve stored buyer data and pre-populate your checkout form. This endpoint requires a Bearer JWT and is only available for resolved sessions.
106
107 ```typescript
108 const prefillRes = await fetch(
109 `https://api.procurenet.io/api/v7/sessions/${session_id}/prefill`,
110 {
111 headers: {
112 'Authorization': `Bearer ${token}`
113 }
114 }
115 );
116
117 const prefillData = await prefillRes.json();
118 // prefillData contains address, payment method hints, and buyer profile fields
119 ```
120
121 <Note>
122 Calling `/prefill` on a `partial` or `anonymous` session returns a `403`. Always guard this call with a `mode === 'resolved'` check.
123 </Note>
124
125 ### Set the Funding Method
126
127 Once the buyer has selected a payment method, register it against the session by calling `POST /api/v7/sessions/{id}/funding-method`. This endpoint requires a Bearer JWT.
128
129 ```typescript
130 const fundingRes = await fetch(
131 `https://api.procurenet.io/api/v7/sessions/${session_id}/funding-method`,
132 {
133 method: 'POST',
134 headers: {
135 'Content-Type': 'application/json',
136 'Authorization': `Bearer ${token}`
137 },
138 body: JSON.stringify({
139 type: 'card',
140 token: 'pm_tok_visa_4242'
141 })
142 }
143 );
144 ```
145
146 ### Advance Through Session States
147
148 Call `POST /api/v7/sessions/{id}/transition` to move the session forward through ProcureNet's state machine. Transitions are event-driven — pass the target event name to advance. This endpoint requires a Bearer JWT.
149
150 ```typescript
151 const transitionRes = await fetch(
152 `https://api.procurenet.io/api/v7/sessions/${session_id}/transition`,
153 {
154 method: 'POST',
155 headers: {
156 'Content-Type': 'application/json',
157 'Authorization': `Bearer ${token}`
158 },
159 body: JSON.stringify({ event: 'confirm' })
160 }
161 );
162
163 const { state } = await transitionRes.json();
164 console.log('New session state:', state);
165 ```
166
167 Listen on your stream connection for real-time state change events alongside explicit transition calls.
168
169 </Steps>
170
171 ## Migrating from the Legacy Payments Route
172
173 <Warning>
174 `POST /api/payments/route` is deprecated and will be removed in a future release. Migrate to `POST /api/v7/orchestrate` as soon as possible to gain WCS scoring, session streaming, and prefill support.
175 </Warning>
176
177 The legacy `POST /api/payments/route` endpoint does not support WCS scoring, session streaming, or prefill. To migrate:
178
179 1. Replace calls to `/api/payments/route` with `POST /api/v7/orchestrate`.
180 2. Update your response handling to read `session_id`, `wcs_score`, `mode`, and `transport` from the new response shape.
181 3. Connect to the session stream using the transport returned in step 2.
182 4. Use `/funding-method` and `/transition` to replace any inline payment routing logic you had in the old flow.