|
1
|
--- |
|
2
|
title: "POST /api/v7/orchestrate — Start Procurement Session" |
|
3
|
sidebarTitle: "POST /orchestrate" |
|
4
|
description: "Start a procurement session. ProcureNet scores buyer identity hints and returns a session ID, WCS score, routing mode, and transport channel." |
|
5
|
--- |
|
6
|
|
|
7
|
The `/api/v7/orchestrate` endpoint is the entry point for every procurement session. You submit a transaction amount, currency, and optional buyer identity hints; ProcureNet's Wallet Confidence Score (WCS) engine evaluates those hints, assigns a score from 0 to 200, and returns a session ID along with the resolved routing mode and the transport channel your client should open. No authentication is required on this call — the WCS engine derives trust from the hints you supply, not from a credential. |
|
8
|
|
|
9
|
## Request Body |
|
10
|
|
|
11
|
<ParamField body="amount" type="number" required> |
|
12
|
The transaction amount in the specified currency. For example, `1500.00`. |
|
13
|
</ParamField> |
|
14
|
|
|
15
|
<ParamField body="currency" type="string" required> |
|
16
|
ISO 4217 currency code for the transaction. For example, `"USD"` or `"EUR"`. |
|
17
|
</ParamField> |
|
18
|
|
|
19
|
<ParamField body="hints" type="object"> |
|
20
|
Optional buyer identity signals used to calculate the WCS. The more signals you provide, the higher the score and the more prefill and SSE transport features become available. |
|
21
|
|
|
22
|
<Expandable title="hints fields"> |
|
23
|
<ParamField body="hints.customerId" type="string"> |
|
24
|
A known, persistent customer ID from your system. Contributes **100 points** to the WCS — the single highest-weight signal. Providing this alone is sufficient to reach the `resolved` threshold. |
|
25
|
</ParamField> |
|
26
|
|
|
27
|
<ParamField body="hints.email" type="string"> |
|
28
|
The buyer's email address. Contributes **40 points** to the WCS. |
|
29
|
</ParamField> |
|
30
|
|
|
31
|
<ParamField body="hints.phone" type="string"> |
|
32
|
The buyer's phone number in E.164 format (e.g., `"+15551234567"`). Contributes **40 points** to the WCS. |
|
33
|
</ParamField> |
|
34
|
|
|
35
|
<ParamField body="hints.deviceId" type="string"> |
|
36
|
A device fingerprint or identifier for the buyer's current device. Contributes **20 points** to the WCS. |
|
37
|
</ParamField> |
|
38
|
</Expandable> |
|
39
|
</ParamField> |
|
40
|
|
|
41
|
<Note> |
|
42
|
The maximum possible WCS is **200** (all four hints provided). A score of **≥ 100** resolves the session to `resolved` mode with SSE transport. Scores of **40–99** produce `partial` mode, and scores **below 40** produce `anonymous` mode — both use WebSocket transport. |
|
43
|
</Note> |
|
44
|
|
|
45
|
## Request Example |
|
46
|
|
|
47
|
```typescript |
|
48
|
const res = await fetch('https://api.procurenet.io/api/v7/orchestrate', { |
|
49
|
method: 'POST', |
|
50
|
headers: { 'Content-Type': 'application/json' }, |
|
51
|
body: JSON.stringify({ |
|
52
|
amount: 1500.00, |
|
53
|
currency: 'USD', |
|
54
|
hints: { |
|
55
|
customerId: 'cust_8f2a1b', |
|
56
|
email: 'buyer@example.com', |
|
57
|
phone: '+15551234567', |
|
58
|
deviceId: 'dev_9c3d2e' |
|
59
|
} |
|
60
|
}) |
|
61
|
}); |
|
62
|
|
|
63
|
const session = await res.json(); |
|
64
|
// { |
|
65
|
// session_id: 'sess_abc123', |
|
66
|
// wcs_score: 200, |
|
67
|
// mode: 'resolved', |
|
68
|
// transport: 'sse' |
|
69
|
// } |
|
70
|
``` |
|
71
|
|
|
72
|
## Response Fields |
|
73
|
|
|
74
|
<ResponseField name="session_id" type="string" required> |
|
75
|
The unique session identifier. Pass this as the `{id}` path parameter in all subsequent session calls: prefill, transition, escrow-accept, and funding-method. |
|
76
|
</ResponseField> |
|
77
|
|
|
78
|
<ResponseField name="wcs_score" type="integer" required> |
|
79
|
The calculated Wallet Confidence Score, ranging from `0` to `200`. Reflects the sum of the hint weights provided. |
|
80
|
</ResponseField> |
|
81
|
|
|
82
|
<ResponseField name="mode" type="string" required> |
|
83
|
The resolved session classification. One of: |
|
84
|
|
|
85
|
| Value | WCS Range | Meaning | |
|
86
|
|---|---|---| |
|
87
|
| `resolved` | ≥ 100 | Full buyer identity confirmed; prefill available | |
|
88
|
| `partial` | 40–99 | Partial identity; limited prefill | |
|
89
|
| `anonymous` | < 40 | No reliable identity signals | |
|
90
|
</ResponseField> |
|
91
|
|
|
92
|
<ResponseField name="transport" type="string" required> |
|
93
|
The recommended transport channel for real-time session events. `sse` for `resolved` sessions; `websocket` for `partial` and `anonymous`. |
|
94
|
</ResponseField> |
|
95
|
|
|
96
|
## Response Example |
|
97
|
|
|
98
|
```json |
|
99
|
{ |
|
100
|
"session_id": "sess_abc123", |
|
101
|
"wcs_score": 200, |
|
102
|
"mode": "resolved", |
|
103
|
"transport": "sse" |
|
104
|
} |
|
105
|
``` |
|
106
|
|
|
107
|
## WCS Score Reference |
|
108
|
|
|
109
|
<CardGroup cols={3}> |
|
110
|
<Card title="resolved" icon="circle-check"> |
|
111
|
Score **≥ 100** — Full prefill access, SSE transport, all session features unlocked. |
|
112
|
</Card> |
|
113
|
<Card title="partial" icon="circle-half-stroke"> |
|
114
|
Score **40–99** — Reduced prefill, WebSocket transport required. |
|
115
|
</Card> |
|
116
|
<Card title="anonymous" icon="circle-xmark"> |
|
117
|
Score **< 40** — No prefill available, WebSocket transport required. |
|
118
|
</Card> |
|
119
|
</CardGroup> |
|
120
|
|
|
121
|
## Error Codes |
|
122
|
|
|
123
|
| HTTP Status | Description | |
|
124
|
|---|---| |
|
125
|
| `400 Bad Request` | Missing required fields (`amount` or `currency`), or malformed request body. | |
|
126
|
| `422 Unprocessable Entity` | Field validation failed — for example, an unrecognized `currency` code. | |
|
127
|
| `500 Internal Server Error` | WCS engine or orchestration pipeline failure. Retry with exponential backoff. | |