|
1
|
--- |
|
2
|
title: "Use Escrow Flows for High-Value Procurement Sessions" |
|
3
|
sidebarTitle: "Escrow Flows" |
|
4
|
description: "Trigger and accept ProcureNet escrow on high-value sessions to satisfy compliance requirements and generate an immutable procurement audit trail." |
|
5
|
--- |
|
6
|
|
|
7
|
For high-value procurement transactions, ProcureNet automatically routes sessions through an escrow acceptance step before funds are committed. This provides a legally meaningful checkpoint — an authorized party explicitly accepts the transaction terms — and writes an immutable audit trail entry that cannot be altered or deleted after acceptance. If your account has a transaction threshold configured, any session that crosses it will pause at `escrow_pending` and wait for an authorized call to proceed. |
|
8
|
|
|
9
|
## When Escrow Is Triggered |
|
10
|
|
|
11
|
ProcureNet transitions a session to the `escrow_pending` state automatically when the transaction amount exceeds your account's configured threshold. You do not need to request this manually. Once a session enters `escrow_pending`, it will not advance until an authorized party calls the escrow acceptance endpoint. |
|
12
|
|
|
13
|
<Info> |
|
14
|
Your transaction threshold is defined by your account policy. To review or adjust your threshold, contact ProcureNet support. |
|
15
|
</Info> |
|
16
|
|
|
17
|
## How the Escrow Flow Works |
|
18
|
|
|
19
|
<Steps> |
|
20
|
|
|
21
|
### Session Reaches `escrow_pending` |
|
22
|
|
|
23
|
When the session amount exceeds your threshold, ProcureNet pauses the session and emits an `escrow_pending` state event on your session stream. Listen for this state on your SSE or WebSocket connection to trigger any UI-level review prompt. |
|
24
|
|
|
25
|
### Authorized Party Reviews Transaction Details |
|
26
|
|
|
27
|
Before calling the escrow acceptance endpoint, the authorized buyer or delegated party should review the transaction amount, funding method, and any procurement contract terms associated with the session. This review step is your compliance window. |
|
28
|
|
|
29
|
### Call `POST /api/v7/sessions/{id}/escrow-accept` |
|
30
|
|
|
31
|
Send a `POST` request to the escrow acceptance endpoint with a valid Bearer JWT. The JWT must belong to the authorized buyer or a delegated party with escrow acceptance permissions. |
|
32
|
|
|
33
|
```typescript |
|
34
|
const res = await fetch( |
|
35
|
`https://api.procurenet.io/api/v7/sessions/${sessionId}/escrow-accept`, |
|
36
|
{ |
|
37
|
method: 'POST', |
|
38
|
headers: { |
|
39
|
'Authorization': `Bearer ${jwtToken}`, |
|
40
|
'Content-Type': 'application/json' |
|
41
|
} |
|
42
|
} |
|
43
|
); |
|
44
|
|
|
45
|
if (res.ok) { |
|
46
|
console.log('Escrow accepted, session advancing to funded state'); |
|
47
|
} |
|
48
|
``` |
|
49
|
|
|
50
|
### ProcureNet Writes the Audit Trail Entry |
|
51
|
|
|
52
|
Immediately upon acceptance, ProcureNet records an immutable audit trail entry capturing the session ID, accepting party identity, timestamp, and transaction details. This entry is written before the session advances and cannot be modified or deleted. |
|
53
|
|
|
54
|
### Session Advances to `funded` |
|
55
|
|
|
56
|
After the audit trail is written, ProcureNet transitions the session to the `funded` state and resumes the orchestration flow. Your session stream will emit the new state. |
|
57
|
|
|
58
|
</Steps> |
|
59
|
|
|
60
|
## Authorization Requirements |
|
61
|
|
|
62
|
<Note> |
|
63
|
Only the authorized buyer or a delegated party holding a valid Bearer JWT with escrow acceptance permissions can call `POST /api/v7/sessions/{id}/escrow-accept`. Calls with an unauthorized or expired JWT return `403 Forbidden`. |
|
64
|
</Note> |
|
65
|
|
|
66
|
Ensure your JWT is issued with the correct claims before calling this endpoint. If you are delegating escrow acceptance to a procurement agent or system account, verify that the delegated JWT has the `escrow:accept` scope. |
|
67
|
|
|
68
|
<Warning> |
|
69
|
Escrow acceptance is irreversible. Once you call the endpoint, the audit trail entry is written and the session advances. There is no undo operation — if you need to stop the transaction after acceptance, you must raise a support ticket for manual escalation. |
|
70
|
</Warning> |
|
71
|
|
|
72
|
## Frequently Asked Questions |
|
73
|
|
|
74
|
<Accordion title="What counts as a high-value transaction?"> |
|
75
|
The threshold is defined by your account's transaction threshold policy and is set during account configuration. ProcureNet compares the session's `amount` field against this threshold to determine whether to enter the `escrow_pending` state. Contact ProcureNet support to review or request a change to your account's threshold. |
|
76
|
</Accordion> |
|
77
|
|
|
78
|
<Accordion title="Can I cancel after escrow is accepted?"> |
|
79
|
No. Once escrow is accepted, the session must proceed to completion. The audit trail entry is immutable and the session state cannot be rolled back programmatically. If you need to halt the transaction after acceptance, contact ProcureNet support to raise a manual escalation ticket — the support team can intervene before funds are fully committed. |
|
80
|
</Accordion> |
|
81
|
|
|
82
|
<Accordion title="What happens if the escrow-accept call fails?"> |
|
83
|
If the endpoint returns a non-2xx response, the session remains in `escrow_pending` and no audit trail entry is written. Retry the call after resolving the issue (for example, refreshing an expired JWT). The session will not time out of `escrow_pending` automatically unless your account has an inactivity policy configured. |
|
84
|
</Accordion> |
|
85
|
|
|
86
|
<Accordion title="Can I automate escrow acceptance?"> |
|
87
|
Yes. You can call `POST /api/v7/sessions/{id}/escrow-accept` from a server-side service as long as the request includes a valid Bearer JWT with the appropriate permissions. Ensure your automated system includes adequate review logic before accepting — the acceptance is irreversible. |
|
88
|
</Accordion> |