|
1
|
--- |
|
2
|
title: "GET /api/v7/sessions/{id}/prefill — Buyer Prefill Data" |
|
3
|
sidebarTitle: "GET /prefill" |
|
4
|
description: "Retrieve cached buyer profile and payment preferences for a resolved session. Only available when the session's Wallet Confidence Score is 100 or above." |
|
5
|
--- |
|
6
|
|
|
7
|
When ProcureNet resolves a session with a Wallet Confidence Score of 100 or higher, it caches the buyer's known profile data and makes it available through the prefill endpoint. Fetching this data lets your checkout UI pre-populate name, address, and payment preference fields, reducing friction for returning buyers. If the session was classified as `partial` or `anonymous`, this endpoint returns `403` — you must present the buyer with a manual entry form instead. |
|
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`. |
|
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`. This scopes the prefill lookup to the correct buyer session. |
|
23
|
</ParamField> |
|
24
|
|
|
25
|
## Request Example |
|
26
|
|
|
27
|
```typescript |
|
28
|
const sessionId = 'sess_abc123'; |
|
29
|
|
|
30
|
const res = await fetch( |
|
31
|
`https://api.procurenet.io/api/v7/sessions/${sessionId}/prefill`, |
|
32
|
{ |
|
33
|
method: 'GET', |
|
34
|
headers: { |
|
35
|
'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', |
|
36
|
'Content-Type': 'application/json' |
|
37
|
} |
|
38
|
} |
|
39
|
); |
|
40
|
|
|
41
|
const prefill = await res.json(); |
|
42
|
// { |
|
43
|
// "customer": { |
|
44
|
// "name": "Jordan Reeves", |
|
45
|
// "email": "buyer@example.com", |
|
46
|
// "address": { |
|
47
|
// "line1": "123 Main St", |
|
48
|
// "city": "Austin", |
|
49
|
// "state": "TX", |
|
50
|
// "zip": "78701", |
|
51
|
// "country": "US" |
|
52
|
// } |
|
53
|
// }, |
|
54
|
// "payment_preferences": ["usdc", "card"] |
|
55
|
// } |
|
56
|
``` |
|
57
|
|
|
58
|
## Response Fields |
|
59
|
|
|
60
|
<ResponseField name="customer" type="object" required> |
|
61
|
A profile object containing the buyer's known identity fields. The exact shape depends on what was available when ProcureNet built the WCS profile. |
|
62
|
|
|
63
|
<Expandable title="customer fields"> |
|
64
|
<ResponseField name="customer.name" type="string"> |
|
65
|
The buyer's full name as stored in the resolved profile. |
|
66
|
</ResponseField> |
|
67
|
|
|
68
|
<ResponseField name="customer.email" type="string"> |
|
69
|
The buyer's email address. |
|
70
|
</ResponseField> |
|
71
|
|
|
72
|
<ResponseField name="customer.address" type="object"> |
|
73
|
Structured shipping or billing address, when available. |
|
74
|
</ResponseField> |
|
75
|
</Expandable> |
|
76
|
</ResponseField> |
|
77
|
|
|
78
|
<ResponseField name="payment_preferences" type="string[]" required> |
|
79
|
An ordered list of the buyer's preferred payment methods, from most to least preferred. Possible values include `"usdc"`, `"card"`, and `"bank_transfer"`. Use this list to rank the options you present in your funding-method UI. |
|
80
|
</ResponseField> |
|
81
|
|
|
82
|
## Response Example |
|
83
|
|
|
84
|
```json |
|
85
|
{ |
|
86
|
"customer": { |
|
87
|
"name": "Jordan Reeves", |
|
88
|
"email": "buyer@example.com", |
|
89
|
"address": { |
|
90
|
"line1": "123 Main St", |
|
91
|
"city": "Austin", |
|
92
|
"state": "TX", |
|
93
|
"zip": "78701", |
|
94
|
"country": "US" |
|
95
|
} |
|
96
|
}, |
|
97
|
"payment_preferences": ["usdc", "card"] |
|
98
|
} |
|
99
|
``` |
|
100
|
|
|
101
|
<Tip> |
|
102
|
Use `payment_preferences[0]` as the default selection in your funding-method UI, then pass it to `POST /api/v7/sessions/{id}/funding-method` when the buyer confirms. |
|
103
|
</Tip> |
|
104
|
|
|
105
|
## Eligibility Check |
|
106
|
|
|
107
|
Before calling this endpoint, inspect the `mode` field from your `POST /api/v7/orchestrate` response: |
|
108
|
|
|
109
|
<Tabs> |
|
110
|
<Tab title="Eligible — resolved"> |
|
111
|
```typescript |
|
112
|
if (session.mode === 'resolved') { |
|
113
|
const prefill = await fetchPrefill(session.session_id, jwt); |
|
114
|
populateCheckoutForm(prefill); |
|
115
|
} |
|
116
|
``` |
|
117
|
</Tab> |
|
118
|
<Tab title="Not eligible — partial / anonymous"> |
|
119
|
```typescript |
|
120
|
if (session.mode !== 'resolved') { |
|
121
|
// Skip prefill — render manual entry form |
|
122
|
renderManualEntryForm(); |
|
123
|
} |
|
124
|
``` |
|
125
|
</Tab> |
|
126
|
</Tabs> |
|
127
|
|
|
128
|
## Error Codes |
|
129
|
|
|
130
|
| HTTP Status | Description | |
|
131
|
|---|---| |
|
132
|
| `401 Unauthorized` | Missing, expired, or invalid Bearer JWT. | |
|
133
|
| `403 Forbidden` | The session's WCS is below 100 (`partial` or `anonymous` mode). Prefill is not available for this session. | |
|
134
|
| `404 Not Found` | No session exists for the provided `id`. | |
|
135
|
| `500 Internal Server Error` | Profile data lookup failure. Retry the request. | |