|
1
|
--- |
|
2
|
title: "Escrow Accept — Confirm High-Value Procurement Session" |
|
3
|
sidebarTitle: "POST /escrow-accept" |
|
4
|
description: "Accept escrow for a high-value procurement session. Writes an immutable audit trail entry before confirmation. This action cannot be undone." |
|
5
|
--- |
|
6
|
|
|
7
|
When a procurement session involves a transaction above the high-value threshold, ProcureNet moves the session into `escrow_pending` state and requires explicit escrow acceptance before payment can proceed. This endpoint records your acceptance, writes an immutable audit trail entry, and advances the session so the payment pipeline can continue. Because this action has legal and financial consequences, the endpoint requires a valid Bearer JWT and performs strict session-scope verification before committing anything. |
|
8
|
|
|
9
|
## Authentication |
|
10
|
|
|
11
|
<Warning> |
|
12
|
This endpoint requires a valid Bearer JWT in the `Authorization` header. Requests without a token, or with an expired or malformed token, receive `401 Unauthorized`. A valid token that does not own the session receives `403 Forbidden`. |
|
13
|
</Warning> |
|
14
|
|
|
15
|
``` |
|
16
|
Authorization: Bearer <your_jwt> |
|
17
|
``` |
|
18
|
|
|
19
|
## Path Parameters |
|
20
|
|
|
21
|
<ParamField path="id" type="string" required> |
|
22
|
The session ID returned by `POST /api/v7/orchestrate`. The session must currently be in `escrow_pending` state. |
|
23
|
</ParamField> |
|
24
|
|
|
25
|
## Request Body |
|
26
|
|
|
27
|
No request body is required. Send the request with no body, or an empty JSON object. |
|
28
|
|
|
29
|
## Request Example |
|
30
|
|
|
31
|
```typescript |
|
32
|
const sessionId = 'sess_abc123'; |
|
33
|
|
|
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 eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', |
|
40
|
'Content-Type': 'application/json' |
|
41
|
} |
|
42
|
} |
|
43
|
); |
|
44
|
|
|
45
|
const result = await res.json(); |
|
46
|
// { |
|
47
|
// "session_id": "sess_abc123", |
|
48
|
// "status": "escrow_accepted", |
|
49
|
// "audit_entry_id": "audit_7x9k2m", |
|
50
|
// "accepted_at": "2026-04-01T15:04:22Z" |
|
51
|
// } |
|
52
|
``` |
|
53
|
|
|
54
|
## Response Fields |
|
55
|
|
|
56
|
<ResponseField name="session_id" type="string" required> |
|
57
|
Echoes back the session ID for correlation. |
|
58
|
</ResponseField> |
|
59
|
|
|
60
|
<ResponseField name="status" type="string" required> |
|
61
|
The new session status after acceptance. Will be `"escrow_accepted"` on success. |
|
62
|
</ResponseField> |
|
63
|
|
|
64
|
<ResponseField name="audit_entry_id" type="string" required> |
|
65
|
The unique identifier for the immutable audit trail record written at the moment of acceptance. Retain this value for compliance and dispute resolution. |
|
66
|
</ResponseField> |
|
67
|
|
|
68
|
<ResponseField name="accepted_at" type="string" required> |
|
69
|
ISO 8601 timestamp of when the escrow acceptance was recorded. This timestamp is co-written to the audit trail and cannot be amended. |
|
70
|
</ResponseField> |
|
71
|
|
|
72
|
## Response Example |
|
73
|
|
|
74
|
```json |
|
75
|
{ |
|
76
|
"session_id": "sess_abc123", |
|
77
|
"status": "escrow_accepted", |
|
78
|
"audit_entry_id": "audit_7x9k2m", |
|
79
|
"accepted_at": "2026-04-01T15:04:22Z" |
|
80
|
} |
|
81
|
``` |
|
82
|
|
|
83
|
<Warning> |
|
84
|
**Escrow acceptance is irreversible.** Once this endpoint returns `200`, the audit trail entry is sealed and cannot be modified or deleted. Ensure the buyer has explicitly confirmed the transaction before calling this endpoint. If you need to cancel after acceptance, contact ProcureNet support — a manual reversal process exists but is subject to review. |
|
85
|
</Warning> |
|
86
|
|
|
87
|
## Typical Flow |
|
88
|
|
|
89
|
<Steps> |
|
90
|
<Step title="Detect escrow_pending state"> |
|
91
|
After calling `POST /api/v7/sessions/{id}/transition`, check whether the response `current_state` is `escrow_pending`. This indicates the transaction exceeded the high-value threshold. |
|
92
|
</Step> |
|
93
|
<Step title="Present escrow disclosure to the buyer"> |
|
94
|
Display the transaction amount, escrow terms, and an explicit confirmation prompt to the buyer. Do not call this endpoint until the buyer actively confirms. |
|
95
|
</Step> |
|
96
|
<Step title="Call escrow-accept"> |
|
97
|
Send the `POST` request with the session ID and your Bearer JWT. Store the `audit_entry_id` from the response in your own records. |
|
98
|
</Step> |
|
99
|
<Step title="Proceed to funding"> |
|
100
|
After a successful `200` response, call `POST /api/v7/sessions/{id}/funding-method` to complete the payment setup. |
|
101
|
</Step> |
|
102
|
</Steps> |
|
103
|
|
|
104
|
## Error Codes |
|
105
|
|
|
106
|
| HTTP Status | Description | |
|
107
|
|---|---| |
|
108
|
| `401 Unauthorized` | Missing, expired, or invalid Bearer JWT. | |
|
109
|
| `403 Forbidden` | The authenticated identity does not match the session owner, or the session is not in `escrow_pending` state. | |
|
110
|
| `404 Not Found` | No session exists for the provided `id`. | |
|
111
|
| `409 Conflict` | Escrow has already been accepted for this session. Check your `audit_entry_id` from the original call. | |
|
112
|
| `410 Gone` | The session has expired. Start a new session with `POST /api/v7/orchestrate`. | |
|
113
|
| `500 Internal Server Error` | Audit trail write failure. The acceptance was **not** recorded. Safe to retry. | |