@facto-to/card 0.0.0-stage → 0.0.1-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +63 -2
- package/dist/card-inbox-DzsHFRPT.d.cts +312 -0
- package/dist/card-inbox-DzsHFRPT.d.ts +312 -0
- package/dist/chunk-KBS2PWM4.js +2 -0
- package/dist/cli/index.js +6 -0
- package/dist/docs/README.md +9 -0
- package/dist/docs/authentication.md +96 -0
- package/dist/docs/authorization-binding.md +182 -0
- package/dist/docs/authorizations.md +182 -0
- package/dist/docs/concepts.md +36 -0
- package/dist/docs/deliveries.md +170 -0
- package/dist/docs/errors.md +100 -0
- package/dist/docs/getting-access.md +56 -0
- package/dist/docs/idempotency.md +78 -0
- package/dist/docs/integration-checklist.md +15 -0
- package/dist/docs/integration.zh.md +59 -0
- package/dist/docs/interlace-adapter-v1.md +87 -0
- package/dist/docs/interlace-adapter-v1.zh.md +87 -0
- package/dist/docs/not-yet-available.md +13 -0
- package/dist/docs/quickstart.md +126 -0
- package/dist/docs/reconciliation.md +86 -0
- package/dist/docs/reference/api.md +2541 -0
- package/dist/docs/reference/events.md +639 -0
- package/dist/docs/reference/schemas.json +6603 -0
- package/dist/docs/reference/schemas.md +1001 -0
- package/dist/docs/simulator.md +235 -0
- package/dist/docs/versioning.md +9 -0
- package/dist/index.cjs +3 -0
- package/dist/index.d.cts +987 -0
- package/dist/index.d.ts +987 -0
- package/dist/index.js +2 -0
- package/dist/source/build.mjs +5 -0
- package/dist/source/package.json +16 -0
- package/dist/source/src/connect/cli/deliveries.ts +48 -0
- package/dist/source/src/connect/cli/index.ts +57 -0
- package/dist/source/src/connect/server/card-binding-assertion.ts +312 -0
- package/dist/source/src/connect/server/card-client.ts +1018 -0
- package/dist/source/src/connect/server/card-delivery.ts +301 -0
- package/dist/source/src/connect/server/card-events.ts +473 -0
- package/dist/source/src/connect/server/card-idempotency.ts +27 -0
- package/dist/source/src/connect/server/card-inbox.ts +82 -0
- package/dist/source/src/connect/server/card-intent-token.ts +588 -0
- package/dist/source/src/connect/server/card-polling.ts +69 -0
- package/dist/source/src/connect/server/card-signing.ts +115 -0
- package/dist/source/src/connect/server/card-transport.ts +282 -0
- package/dist/source/src/connect/server/errors.ts +280 -0
- package/dist/source/src/connect/server/fixtures/engine/card-events.synthetic.ts +84 -0
- package/dist/source/src/connect/server/retry-after.ts +12 -0
- package/dist/source/src/connect/testing/card-inbox.ts +124 -0
- package/dist/source/src/connect/testing/card-scenarios.ts +243 -0
- package/dist/source/src/connect/testing/card-simulator-vectors.ts +262 -0
- package/dist/source/src/connect/testing/card-simulator.ts +531 -0
- package/dist/source/src/connect/testing/interlace-card-transactions.ts +704 -0
- package/dist/source/src/connect/testing/pure-sha256.ts +123 -0
- package/dist/source/src/connect/wire.d.ts +544 -0
- package/dist/source/src/index.ts +163 -0
- package/dist/source/src/testing-browser.ts +24 -0
- package/dist/source/src/testing.ts +26 -0
- package/dist/source/tsconfig.json +20 -0
- package/dist/testing-browser.d.ts +220 -0
- package/dist/testing-browser.js +5 -0
- package/dist/testing.cjs +6 -0
- package/dist/testing.d.cts +199 -0
- package/dist/testing.d.ts +199 -0
- package/dist/testing.js +5 -0
- package/package.json +60 -4
|
@@ -0,0 +1,2541 @@
|
|
|
1
|
+
# Card API reference
|
|
2
|
+
|
|
3
|
+
Find each provider operation, its request fields and response shapes below. See the [schema appendix](schemas.md) for nested types and conditional rules; the [machine-readable schemas](schemas.json) retain structural constraints.
|
|
4
|
+
|
|
5
|
+
All requests require the four authentication headers described in [authentication](../authentication.md). The SDK supplies `program_id` from its configured scope. Credentials, effective grants and any approved coverage must all match the environment and connection.
|
|
6
|
+
|
|
7
|
+
## Operation capabilities
|
|
8
|
+
|
|
9
|
+
| Operation | Capability and purpose |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `POST /api/card/authorizations` | `authorization_event.write` |
|
|
12
|
+
| `POST /api/card/authorizations/lookup` | `authorization_status.read`; approved authorization-read purpose |
|
|
13
|
+
| `POST /api/card/authorizations/{external_id}/facts` | `authorization_event.write` |
|
|
14
|
+
| `POST /api/card/bindings/lookup` | `binding_status.read` |
|
|
15
|
+
| `POST /api/card/connect/intents/{id}/cancel` | `subject_assertion.write` |
|
|
16
|
+
| `GET /api/card/connect/intents/{id}/cards` | `subject_assertion.write` |
|
|
17
|
+
| `PUT /api/card/connect/intents/{id}/cards` | `subject_assertion.write` |
|
|
18
|
+
| `POST /api/card/connect/sessions` | `subject_assertion.write` |
|
|
19
|
+
| `GET /api/card/connect/sessions/{id}` | `subject_assertion.write` |
|
|
20
|
+
| `POST /api/card/connect/sessions/{id}/cancel` | `subject_assertion.write` |
|
|
21
|
+
| `GET /api/card/connect/sessions/{id}/proof-challenge` | `subject_assertion.write` |
|
|
22
|
+
| `POST /api/card/connect/sessions/{id}/provider-proof` | `subject_assertion.write` |
|
|
23
|
+
| `GET /api/card/deliveries/dead-letters` | `binding_status.read` |
|
|
24
|
+
| `POST /api/card/deliveries/dead-letters/{id}/replay` | `binding_status.read` |
|
|
25
|
+
| `POST /api/card/deliveries/reconciliations/list` | `event_delivery.read`; approved delivery-read purpose and coverage |
|
|
26
|
+
| `POST /api/card/deliveries/replays` | `event_delivery.read`; separately approved history-replay purpose and selection |
|
|
27
|
+
| `POST /api/card/events` | `card_lifecycle_event.write` |
|
|
28
|
+
|
|
29
|
+
## POST /api/card/authorizations
|
|
30
|
+
|
|
31
|
+
Submit an initial card swipe authorization for admission and settlement execution.
|
|
32
|
+
|
|
33
|
+
### Request headers and path parameters
|
|
34
|
+
|
|
35
|
+
| Name | Location | Required | Constraints |
|
|
36
|
+
| --- | --- | --- | --- |
|
|
37
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
38
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
39
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
40
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
41
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
42
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
43
|
+
|
|
44
|
+
### Request body
|
|
45
|
+
|
|
46
|
+
Body required.
|
|
47
|
+
|
|
48
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
49
|
+
| --- | --- | --- | --- | --- |
|
|
50
|
+
| `amount` | string | Yes | min length 1; max length 64 | Decimal amount for the operation. |
|
|
51
|
+
| `cardholder_verification` | [`CardholderVerification`](schemas.md#cardholderverification) | Yes | — | Cardholder verification evidence. |
|
|
52
|
+
| `client_transaction_id` | string | No | min length 1; max length 256 | Caller-provided transaction correlation identifier. |
|
|
53
|
+
| `currency` | string | Yes | one of `USD`, `USDC` | ISO or token currency code. |
|
|
54
|
+
| `deadline_at` | string | No | format date-time | Effective decision deadline. |
|
|
55
|
+
| `decision_mode` | string | No | one of `asynchronous`, `synchronous` | Requested asynchronous or synchronous decision mode. |
|
|
56
|
+
| `decision_timeout_ms` | integer | No | min 50; max 5000 | Requested synchronous decision time limit in milliseconds. |
|
|
57
|
+
| `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
|
|
58
|
+
| `external_card_id` | string | Yes | min length 1; max length 512 | Opaque card identifier assigned by the partner. |
|
|
59
|
+
| `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
|
|
60
|
+
| `merchant_country` | string | No | min length 1; max length 8 | ISO country code reported for this transaction. |
|
|
61
|
+
| `merchant_mcc` | string | No | min length 0; max length 16 | Merchant category code reported for this transaction. |
|
|
62
|
+
| `merchant_name` | string | No | min length 0; max length 256 | Merchant name reported for this transaction. |
|
|
63
|
+
| `occurred_at` | string | No | format date-time | Time when the event or authorization occurred. |
|
|
64
|
+
| `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
|
|
65
|
+
| `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
|
|
66
|
+
| `supplier_transaction_id` | string | No | min length 1; max length 256 | Partner transaction identifier for this operation. |
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
Conditional rules:
|
|
70
|
+
|
|
71
|
+
- `decision_timeout_ms` and `deadline_at` are allowed only for synchronous original authorizations; synchronous approval is currently closed.
|
|
72
|
+
|
|
73
|
+
### Responses
|
|
74
|
+
|
|
75
|
+
#### HTTP 200
|
|
76
|
+
|
|
77
|
+
#### Variant 1: AuthorizationAccepted
|
|
78
|
+
|
|
79
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
80
|
+
| --- | --- | --- | --- | --- |
|
|
81
|
+
| `charge_id` | string | Yes | min length 1; max length 255 | Public charge identifier. |
|
|
82
|
+
| `status` | string | Yes | equals `processing` | Reported status; interpret in the context of this response. |
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
#### Variant 2: SynchronousAuthorizationApproved
|
|
86
|
+
|
|
87
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
88
|
+
| --- | --- | --- | --- | --- |
|
|
89
|
+
| `charge_id` | string | Yes | — | Public charge identifier. |
|
|
90
|
+
| `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
|
|
91
|
+
| `decided_at` | string | Yes | format date-time | Time at which a decision was recorded. |
|
|
92
|
+
| `decision` | string | Yes | equals `approved` | Synchronous decision. |
|
|
93
|
+
| `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
|
|
94
|
+
| `status` | string | Yes | equals `approved` | Reported status; interpret in the context of this response. |
|
|
95
|
+
|
|
96
|
+
#### HTTP 400
|
|
97
|
+
|
|
98
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
99
|
+
| --- | --- | --- | --- | --- |
|
|
100
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
101
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
102
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
103
|
+
|
|
104
|
+
#### HTTP 401
|
|
105
|
+
|
|
106
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
107
|
+
| --- | --- | --- | --- | --- |
|
|
108
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
109
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
110
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
111
|
+
|
|
112
|
+
#### HTTP 402
|
|
113
|
+
|
|
114
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
115
|
+
| --- | --- | --- | --- | --- |
|
|
116
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
117
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
118
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
119
|
+
|
|
120
|
+
#### HTTP 403
|
|
121
|
+
|
|
122
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
123
|
+
| --- | --- | --- | --- | --- |
|
|
124
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
125
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
126
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
127
|
+
|
|
128
|
+
#### HTTP 404
|
|
129
|
+
|
|
130
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
131
|
+
| --- | --- | --- | --- | --- |
|
|
132
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
133
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
134
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
135
|
+
|
|
136
|
+
#### HTTP 408
|
|
137
|
+
|
|
138
|
+
#### Variant 1: SynchronousAuthorizationDeclined
|
|
139
|
+
|
|
140
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
141
|
+
| --- | --- | --- | --- | --- |
|
|
142
|
+
| `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
|
|
143
|
+
| `decided_at` | string | Yes | format date-time | Time at which a decision was recorded. |
|
|
144
|
+
| `decision` | string | Yes | one of `declined`, `self_reversed_timeout` | Synchronous decision. |
|
|
145
|
+
| `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
|
|
146
|
+
| `error` | string | Yes | — | Machine-readable error code. |
|
|
147
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
148
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
#### Variant 2: AuthorizationDeadlineExceeded
|
|
152
|
+
|
|
153
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
154
|
+
| --- | --- | --- | --- | --- |
|
|
155
|
+
| `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
|
|
156
|
+
| `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
|
|
157
|
+
| `error` | string | Yes | equals `decision_deadline_exceeded` | Machine-readable error code. |
|
|
158
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
159
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
160
|
+
|
|
161
|
+
#### HTTP 409
|
|
162
|
+
|
|
163
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
164
|
+
| --- | --- | --- | --- | --- |
|
|
165
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
166
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
167
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
168
|
+
|
|
169
|
+
#### HTTP 422
|
|
170
|
+
|
|
171
|
+
#### Variant 1: AuthorizationError
|
|
172
|
+
|
|
173
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
174
|
+
| --- | --- | --- | --- | --- |
|
|
175
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
176
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
177
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
#### Variant 2: SynchronousAuthorizationDeclined
|
|
181
|
+
|
|
182
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
183
|
+
| --- | --- | --- | --- | --- |
|
|
184
|
+
| `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
|
|
185
|
+
| `decided_at` | string | Yes | format date-time | Time at which a decision was recorded. |
|
|
186
|
+
| `decision` | string | Yes | one of `declined`, `self_reversed_timeout` | Synchronous decision. |
|
|
187
|
+
| `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
|
|
188
|
+
| `error` | string | Yes | — | Machine-readable error code. |
|
|
189
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
190
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
191
|
+
|
|
192
|
+
#### HTTP 423
|
|
193
|
+
|
|
194
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
195
|
+
| --- | --- | --- | --- | --- |
|
|
196
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
197
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
198
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
199
|
+
|
|
200
|
+
#### HTTP 429
|
|
201
|
+
|
|
202
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
203
|
+
| --- | --- | --- | --- | --- |
|
|
204
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
205
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
206
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
207
|
+
|
|
208
|
+
#### HTTP 500
|
|
209
|
+
|
|
210
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
211
|
+
| --- | --- | --- | --- | --- |
|
|
212
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
213
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
214
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
215
|
+
|
|
216
|
+
#### HTTP 503
|
|
217
|
+
|
|
218
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
219
|
+
| --- | --- | --- | --- | --- |
|
|
220
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
221
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
222
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
223
|
+
|
|
224
|
+
### Known error codes
|
|
225
|
+
|
|
226
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`, `authorization_admission_closed`, `route_not_payable`, `consent_scope_not_payable`, `spending_limit_exceeded`, `onchain_insufficient_balance`, `yield_source_underfunded`, `sync_approval_admission_closed`, `decision_deadline_exceeded`, `internal_error`
|
|
227
|
+
|
|
228
|
+
Unknown codes may also occur.
|
|
229
|
+
|
|
230
|
+
## POST /api/card/authorizations/lookup
|
|
231
|
+
|
|
232
|
+
Look up the current authorization projection by external authorization ID, supplier transaction ID, idempotency key, or charge ID.
|
|
233
|
+
|
|
234
|
+
### Request headers and path parameters
|
|
235
|
+
|
|
236
|
+
| Name | Location | Required | Constraints |
|
|
237
|
+
| --- | --- | --- | --- |
|
|
238
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
239
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
240
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
241
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
242
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
243
|
+
|
|
244
|
+
### Request body
|
|
245
|
+
|
|
246
|
+
Body required.
|
|
247
|
+
|
|
248
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
249
|
+
| --- | --- | --- | --- | --- |
|
|
250
|
+
| `criteria` | one of the variants below | Yes | — | Exactly one authorization lookup selector. |
|
|
251
|
+
| `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
**criteria variants**
|
|
255
|
+
|
|
256
|
+
#### Variant 1: AuthorizationRefLookup
|
|
257
|
+
|
|
258
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
259
|
+
| --- | --- | --- | --- | --- |
|
|
260
|
+
| `by` | string | Yes | equals `external_authorization_id` | Selects the lookup identity. |
|
|
261
|
+
| `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
|
|
262
|
+
| `fact_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | No | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
|
|
263
|
+
| `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
|
|
264
|
+
| `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
#### Variant 2: SupplierTransactionRefLookup
|
|
268
|
+
|
|
269
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
270
|
+
| --- | --- | --- | --- | --- |
|
|
271
|
+
| `by` | string | Yes | equals `supplier_transaction_id` | Selects the lookup identity. |
|
|
272
|
+
| `fact_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | No | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
|
|
273
|
+
| `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
|
|
274
|
+
| `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
|
|
275
|
+
| `supplier_transaction_id` | string | Yes | min length 1; max length 256 | Partner transaction identifier for this operation. |
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
#### Variant 3: AuthorizationIdempotencyLookup
|
|
279
|
+
|
|
280
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
281
|
+
| --- | --- | --- | --- | --- |
|
|
282
|
+
| `by` | string | Yes | equals `idempotency_key` | Selects the lookup identity. |
|
|
283
|
+
| `idempotency_key` | string | Yes | min length 16; max length 255 | Original idempotency key used for the authorization. |
|
|
284
|
+
| `operation` | string | No | equals `create_authorization` | Idempotent operation category. |
|
|
285
|
+
| `original_credential_key_id` | string | Yes | min length 1; max length 255 | Key ID that signed the original authorization. |
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
#### Variant 4: AuthorizationChargeIdLookup
|
|
289
|
+
|
|
290
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
291
|
+
| --- | --- | --- | --- | --- |
|
|
292
|
+
| `by` | string | Yes | equals `charge_id` | Selects the lookup identity. |
|
|
293
|
+
| `charge_id` | string | Yes | min length 1; max length 255 | Public charge identifier. |
|
|
294
|
+
|
|
295
|
+
### Responses
|
|
296
|
+
|
|
297
|
+
#### HTTP 200
|
|
298
|
+
|
|
299
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
300
|
+
| --- | --- | --- | --- | --- |
|
|
301
|
+
| `authorization` | [`AuthorizationProjection`](schemas.md#authorizationprojection) | No | — | Authorization projection, when observed. |
|
|
302
|
+
| `observed_at` | [`AuthorizationTimestamp`](schemas.md#authorizationtimestamp) | Yes | format date-time | Time of the returned observation. |
|
|
303
|
+
| `resolution` | string | Yes | one of `resolved`, `pending`, `unknown`, `not_observed` | Lookup resolution. |
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
Conditional rules:
|
|
307
|
+
|
|
308
|
+
- If resolution is `not_observed`, not (`authorization` is present).
|
|
309
|
+
- If resolution is `resolved`, `authorization` is present and authorization.processing_status is one of `succeeded`, `failed`.
|
|
310
|
+
- If resolution is `pending`, `authorization` is present and authorization.processing_status is one of `processing`.
|
|
311
|
+
- If resolution is `unknown`, `authorization` is present and authorization.processing_status is one of `indeterminate`.
|
|
312
|
+
|
|
313
|
+
#### HTTP 400
|
|
314
|
+
|
|
315
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
316
|
+
| --- | --- | --- | --- | --- |
|
|
317
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
318
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
319
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
320
|
+
|
|
321
|
+
#### HTTP 401
|
|
322
|
+
|
|
323
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
324
|
+
| --- | --- | --- | --- | --- |
|
|
325
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
326
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
327
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
328
|
+
|
|
329
|
+
#### HTTP 403
|
|
330
|
+
|
|
331
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
332
|
+
| --- | --- | --- | --- | --- |
|
|
333
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
334
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
335
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
336
|
+
|
|
337
|
+
#### HTTP 404
|
|
338
|
+
|
|
339
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
340
|
+
| --- | --- | --- | --- | --- |
|
|
341
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
342
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
343
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
344
|
+
|
|
345
|
+
#### HTTP 409
|
|
346
|
+
|
|
347
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
348
|
+
| --- | --- | --- | --- | --- |
|
|
349
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
350
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
351
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
352
|
+
|
|
353
|
+
#### HTTP 503
|
|
354
|
+
|
|
355
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
356
|
+
| --- | --- | --- | --- | --- |
|
|
357
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
358
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
359
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
360
|
+
|
|
361
|
+
### Known error codes
|
|
362
|
+
|
|
363
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`, `authorization_admission_closed`, `route_not_payable`, `consent_scope_not_payable`, `spending_limit_exceeded`, `onchain_insufficient_balance`, `yield_source_underfunded`, `sync_approval_admission_closed`, `decision_deadline_exceeded`, `internal_error`
|
|
364
|
+
|
|
365
|
+
Unknown codes may also occur.
|
|
366
|
+
|
|
367
|
+
## POST /api/card/authorizations/{external_id}/facts
|
|
368
|
+
|
|
369
|
+
Record a subsequent clearing, reversal, refund, chargeback, or settlement lifecycle fact.
|
|
370
|
+
|
|
371
|
+
### Request headers and path parameters
|
|
372
|
+
|
|
373
|
+
| Name | Location | Required | Constraints |
|
|
374
|
+
| --- | --- | --- | --- |
|
|
375
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
376
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
377
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
378
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
379
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
380
|
+
| `external_id` | path | Yes | min length 1; max length 256 |
|
|
381
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
382
|
+
|
|
383
|
+
### Request body
|
|
384
|
+
|
|
385
|
+
Body required.
|
|
386
|
+
|
|
387
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
388
|
+
| --- | --- | --- | --- | --- |
|
|
389
|
+
| `amount` | string | Yes | min length 1; max length 64 | Decimal amount for the operation. |
|
|
390
|
+
| `client_transaction_id` | string | No | min length 1; max length 256 | Caller-provided transaction correlation identifier. |
|
|
391
|
+
| `currency` | string | Yes | one of `USD`, `USDC` | ISO or token currency code. |
|
|
392
|
+
| `fact_type` | string | Yes | one of `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
|
|
393
|
+
| `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
|
|
394
|
+
| `merchant_country` | string | No | min length 1; max length 8 | ISO country code reported for this transaction. |
|
|
395
|
+
| `merchant_mcc` | string | No | min length 0; max length 16 | Merchant category code reported for this transaction. |
|
|
396
|
+
| `merchant_name` | string | No | min length 0; max length 256 | Merchant name reported for this transaction. |
|
|
397
|
+
| `parent_supplier_transaction_id` | string | No | min length 1; max length 256 | Partner identifier for the preceding transaction. |
|
|
398
|
+
| `predecessor_version` | string | Yes | min length 1; max length 255 | Previous distinct version for a subsequent fact. |
|
|
399
|
+
| `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
|
|
400
|
+
| `recorded_at` | string | Yes | format date-time | Time the fact was recorded. |
|
|
401
|
+
| `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
|
|
402
|
+
| `supplier_transaction_id` | string | No | min length 1; max length 256 | Partner transaction identifier for this operation. |
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
Conditional rules:
|
|
406
|
+
|
|
407
|
+
- A subsequent fact requires a distinct `predecessor_version` that already exists on the same authorization lineage.
|
|
408
|
+
- Every subsequent fact needs its own stable idempotency key and resource version.
|
|
409
|
+
|
|
410
|
+
### Responses
|
|
411
|
+
|
|
412
|
+
#### HTTP 200
|
|
413
|
+
|
|
414
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
415
|
+
| --- | --- | --- | --- | --- |
|
|
416
|
+
| `operation_id` | string | Yes | format uuid | Recorded operation identifier. |
|
|
417
|
+
| `status` | string | Yes | equals `recorded` | Reported status; interpret in the context of this response. |
|
|
418
|
+
|
|
419
|
+
#### HTTP 400
|
|
420
|
+
|
|
421
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
422
|
+
| --- | --- | --- | --- | --- |
|
|
423
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
424
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
425
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
426
|
+
|
|
427
|
+
#### HTTP 401
|
|
428
|
+
|
|
429
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
430
|
+
| --- | --- | --- | --- | --- |
|
|
431
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
432
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
433
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
434
|
+
|
|
435
|
+
#### HTTP 403
|
|
436
|
+
|
|
437
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
438
|
+
| --- | --- | --- | --- | --- |
|
|
439
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
440
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
441
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
442
|
+
|
|
443
|
+
#### HTTP 404
|
|
444
|
+
|
|
445
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
446
|
+
| --- | --- | --- | --- | --- |
|
|
447
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
448
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
449
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
450
|
+
|
|
451
|
+
#### HTTP 409
|
|
452
|
+
|
|
453
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
454
|
+
| --- | --- | --- | --- | --- |
|
|
455
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
456
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
457
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
458
|
+
|
|
459
|
+
#### HTTP 429
|
|
460
|
+
|
|
461
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
462
|
+
| --- | --- | --- | --- | --- |
|
|
463
|
+
| `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
|
|
464
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
465
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
466
|
+
|
|
467
|
+
#### HTTP 500
|
|
468
|
+
|
|
469
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
470
|
+
| --- | --- | --- | --- | --- |
|
|
471
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
472
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
473
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
474
|
+
|
|
475
|
+
#### HTTP 503
|
|
476
|
+
|
|
477
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
478
|
+
| --- | --- | --- | --- | --- |
|
|
479
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
480
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
481
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
482
|
+
|
|
483
|
+
### Known error codes
|
|
484
|
+
|
|
485
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`, `authorization_admission_closed`, `route_not_payable`, `consent_scope_not_payable`, `spending_limit_exceeded`, `onchain_insufficient_balance`, `yield_source_underfunded`, `sync_approval_admission_closed`, `decision_deadline_exceeded`, `internal_error`
|
|
486
|
+
|
|
487
|
+
Unknown codes may also occur.
|
|
488
|
+
|
|
489
|
+
## POST /api/card/bindings/lookup
|
|
490
|
+
|
|
491
|
+
Look up the current Facto card binding projection by opaque external_card_id.
|
|
492
|
+
|
|
493
|
+
### Request headers and path parameters
|
|
494
|
+
|
|
495
|
+
| Name | Location | Required | Constraints |
|
|
496
|
+
| --- | --- | --- | --- |
|
|
497
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
498
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
499
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
500
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
501
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
502
|
+
|
|
503
|
+
### Request body
|
|
504
|
+
|
|
505
|
+
Body required.
|
|
506
|
+
|
|
507
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
508
|
+
| --- | --- | --- | --- | --- |
|
|
509
|
+
| `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
|
|
510
|
+
|
|
511
|
+
### Responses
|
|
512
|
+
|
|
513
|
+
#### HTTP 200
|
|
514
|
+
|
|
515
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
516
|
+
| --- | --- | --- | --- | --- |
|
|
517
|
+
| `binding` | one of the variants below | Yes | — | Current binding projection, or null when unbound. |
|
|
518
|
+
| `found` | boolean | Yes | — | Whether an active or revoked binding matched. |
|
|
519
|
+
|
|
520
|
+
|
|
521
|
+
**binding variants**
|
|
522
|
+
|
|
523
|
+
#### Variant 1: BindingSummary
|
|
524
|
+
|
|
525
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
526
|
+
| --- | --- | --- | --- | --- |
|
|
527
|
+
| `card` | [`CardDisplayFacts`](schemas.md#carddisplayfacts) | Yes | — | Card display metadata. |
|
|
528
|
+
| `funding` | [`BindingFundingProjection`](schemas.md#bindingfundingprojection) | No | — | Funding readiness summary, when included. |
|
|
529
|
+
| `id` | [`CardBindingId`](schemas.md#cardbindingid) | Yes | pattern `^cb_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
|
|
530
|
+
| `revision` | integer | Yes | min 1; format int32 | Optimistic concurrency revision. |
|
|
531
|
+
| `status` | string | Yes | one of `active`, `revoked` | Reported status; interpret in the context of this response. |
|
|
532
|
+
|
|
533
|
+
|
|
534
|
+
#### Variant 2
|
|
535
|
+
|
|
536
|
+
Type: null. Constraints: —.
|
|
537
|
+
|
|
538
|
+
#### HTTP 400
|
|
539
|
+
|
|
540
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
541
|
+
| --- | --- | --- | --- | --- |
|
|
542
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
543
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
544
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
545
|
+
|
|
546
|
+
#### HTTP 401
|
|
547
|
+
|
|
548
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
549
|
+
| --- | --- | --- | --- | --- |
|
|
550
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
551
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
552
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
553
|
+
|
|
554
|
+
#### HTTP 403
|
|
555
|
+
|
|
556
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
557
|
+
| --- | --- | --- | --- | --- |
|
|
558
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
559
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
560
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
561
|
+
|
|
562
|
+
#### HTTP 404
|
|
563
|
+
|
|
564
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
565
|
+
| --- | --- | --- | --- | --- |
|
|
566
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
567
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
568
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
569
|
+
|
|
570
|
+
#### HTTP 409
|
|
571
|
+
|
|
572
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
573
|
+
| --- | --- | --- | --- | --- |
|
|
574
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
575
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
576
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
577
|
+
|
|
578
|
+
#### HTTP 410
|
|
579
|
+
|
|
580
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
581
|
+
| --- | --- | --- | --- | --- |
|
|
582
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
583
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
584
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
585
|
+
|
|
586
|
+
#### HTTP 412
|
|
587
|
+
|
|
588
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
589
|
+
| --- | --- | --- | --- | --- |
|
|
590
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
591
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
592
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
593
|
+
|
|
594
|
+
#### HTTP 422
|
|
595
|
+
|
|
596
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
597
|
+
| --- | --- | --- | --- | --- |
|
|
598
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
599
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
600
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
601
|
+
|
|
602
|
+
#### HTTP 423
|
|
603
|
+
|
|
604
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
605
|
+
| --- | --- | --- | --- | --- |
|
|
606
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
607
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
608
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
609
|
+
|
|
610
|
+
#### HTTP 428
|
|
611
|
+
|
|
612
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
613
|
+
| --- | --- | --- | --- | --- |
|
|
614
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
615
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
616
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
617
|
+
|
|
618
|
+
#### HTTP 429
|
|
619
|
+
|
|
620
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
621
|
+
| --- | --- | --- | --- | --- |
|
|
622
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
623
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
624
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
625
|
+
|
|
626
|
+
#### HTTP 500
|
|
627
|
+
|
|
628
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
629
|
+
| --- | --- | --- | --- | --- |
|
|
630
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
631
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
632
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
633
|
+
|
|
634
|
+
### Known error codes
|
|
635
|
+
|
|
636
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
637
|
+
|
|
638
|
+
Unknown codes may also occur.
|
|
639
|
+
|
|
640
|
+
## POST /api/card/connect/intents/{id}/cancel
|
|
641
|
+
|
|
642
|
+
Cancel an active connect intent when the cardholder aborts selection.
|
|
643
|
+
|
|
644
|
+
### Request headers and path parameters
|
|
645
|
+
|
|
646
|
+
| Name | Location | Required | Constraints |
|
|
647
|
+
| --- | --- | --- | --- |
|
|
648
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
649
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
650
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
651
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
652
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
653
|
+
| `id` | path | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` |
|
|
654
|
+
|
|
655
|
+
### Request body
|
|
656
|
+
|
|
657
|
+
Body required.
|
|
658
|
+
|
|
659
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
660
|
+
| --- | --- | --- | --- | --- |
|
|
661
|
+
| `intent_token` | string | Yes | — | Signed intent token issued by Facto for this connect intent. |
|
|
662
|
+
|
|
663
|
+
### Responses
|
|
664
|
+
|
|
665
|
+
#### HTTP 200
|
|
666
|
+
|
|
667
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
668
|
+
| --- | --- | --- | --- | --- |
|
|
669
|
+
| `id` | [`ConnectIntentId`](schemas.md#connectintentid) | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
|
|
670
|
+
| `status` | string | Yes | equals `cancelled` | Reported status; interpret in the context of this response. |
|
|
671
|
+
|
|
672
|
+
#### HTTP 400
|
|
673
|
+
|
|
674
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
675
|
+
| --- | --- | --- | --- | --- |
|
|
676
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
677
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
678
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
679
|
+
|
|
680
|
+
#### HTTP 401
|
|
681
|
+
|
|
682
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
683
|
+
| --- | --- | --- | --- | --- |
|
|
684
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
685
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
686
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
687
|
+
|
|
688
|
+
#### HTTP 403
|
|
689
|
+
|
|
690
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
691
|
+
| --- | --- | --- | --- | --- |
|
|
692
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
693
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
694
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
695
|
+
|
|
696
|
+
#### HTTP 404
|
|
697
|
+
|
|
698
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
699
|
+
| --- | --- | --- | --- | --- |
|
|
700
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
701
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
702
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
703
|
+
|
|
704
|
+
#### HTTP 409
|
|
705
|
+
|
|
706
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
707
|
+
| --- | --- | --- | --- | --- |
|
|
708
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
709
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
710
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
711
|
+
|
|
712
|
+
#### HTTP 410
|
|
713
|
+
|
|
714
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
715
|
+
| --- | --- | --- | --- | --- |
|
|
716
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
717
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
718
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
719
|
+
|
|
720
|
+
#### HTTP 412
|
|
721
|
+
|
|
722
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
723
|
+
| --- | --- | --- | --- | --- |
|
|
724
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
725
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
726
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
727
|
+
|
|
728
|
+
#### HTTP 422
|
|
729
|
+
|
|
730
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
731
|
+
| --- | --- | --- | --- | --- |
|
|
732
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
733
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
734
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
735
|
+
|
|
736
|
+
#### HTTP 423
|
|
737
|
+
|
|
738
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
739
|
+
| --- | --- | --- | --- | --- |
|
|
740
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
741
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
742
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
743
|
+
|
|
744
|
+
#### HTTP 428
|
|
745
|
+
|
|
746
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
747
|
+
| --- | --- | --- | --- | --- |
|
|
748
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
749
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
750
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
751
|
+
|
|
752
|
+
#### HTTP 429
|
|
753
|
+
|
|
754
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
755
|
+
| --- | --- | --- | --- | --- |
|
|
756
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
757
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
758
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
759
|
+
|
|
760
|
+
#### HTTP 500
|
|
761
|
+
|
|
762
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
763
|
+
| --- | --- | --- | --- | --- |
|
|
764
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
765
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
766
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
767
|
+
|
|
768
|
+
### Known error codes
|
|
769
|
+
|
|
770
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
771
|
+
|
|
772
|
+
Unknown codes may also occur.
|
|
773
|
+
|
|
774
|
+
## GET /api/card/connect/intents/{id}/cards
|
|
775
|
+
|
|
776
|
+
List currently bound cards and the optimistic concurrency revision for an active connect intent.
|
|
777
|
+
|
|
778
|
+
### Request headers and path parameters
|
|
779
|
+
|
|
780
|
+
| Name | Location | Required | Constraints |
|
|
781
|
+
| --- | --- | --- | --- |
|
|
782
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
783
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
784
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
785
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
786
|
+
| `id` | path | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` |
|
|
787
|
+
| `x-facto-intent-token` | header | Yes | min length 32; max length 8192 |
|
|
788
|
+
|
|
789
|
+
`x-facto-intent-token` is the signed intent token Facto issues when the user opens this connect intent. Obtain the original token through the user handoff and present it only for that live intent; the partner does not create it.
|
|
790
|
+
|
|
791
|
+
### Request body
|
|
792
|
+
|
|
793
|
+
No structured JSON body is specified.
|
|
794
|
+
|
|
795
|
+
### Responses
|
|
796
|
+
|
|
797
|
+
#### HTTP 200
|
|
798
|
+
|
|
799
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
800
|
+
| --- | --- | --- | --- | --- |
|
|
801
|
+
| `cards` | array | Yes | items: [`IntentCardItem`](schemas.md#intentcarditem) | Card set for this intent. |
|
|
802
|
+
| `id` | [`ConnectIntentId`](schemas.md#connectintentid) | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
|
|
803
|
+
| `revision` | [`ConnectIntentDigest`](schemas.md#connectintentdigest) | Yes | pattern `^sha256:[a-fA-F0-9]{64}$` | Optimistic concurrency revision. |
|
|
804
|
+
|
|
805
|
+
#### HTTP 400
|
|
806
|
+
|
|
807
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
808
|
+
| --- | --- | --- | --- | --- |
|
|
809
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
810
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
811
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
812
|
+
|
|
813
|
+
#### HTTP 401
|
|
814
|
+
|
|
815
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
816
|
+
| --- | --- | --- | --- | --- |
|
|
817
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
818
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
819
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
820
|
+
|
|
821
|
+
#### HTTP 403
|
|
822
|
+
|
|
823
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
824
|
+
| --- | --- | --- | --- | --- |
|
|
825
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
826
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
827
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
828
|
+
|
|
829
|
+
#### HTTP 404
|
|
830
|
+
|
|
831
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
832
|
+
| --- | --- | --- | --- | --- |
|
|
833
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
834
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
835
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
836
|
+
|
|
837
|
+
#### HTTP 409
|
|
838
|
+
|
|
839
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
840
|
+
| --- | --- | --- | --- | --- |
|
|
841
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
842
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
843
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
844
|
+
|
|
845
|
+
#### HTTP 410
|
|
846
|
+
|
|
847
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
848
|
+
| --- | --- | --- | --- | --- |
|
|
849
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
850
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
851
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
852
|
+
|
|
853
|
+
#### HTTP 412
|
|
854
|
+
|
|
855
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
856
|
+
| --- | --- | --- | --- | --- |
|
|
857
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
858
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
859
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
860
|
+
|
|
861
|
+
#### HTTP 422
|
|
862
|
+
|
|
863
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
864
|
+
| --- | --- | --- | --- | --- |
|
|
865
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
866
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
867
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
868
|
+
|
|
869
|
+
#### HTTP 423
|
|
870
|
+
|
|
871
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
872
|
+
| --- | --- | --- | --- | --- |
|
|
873
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
874
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
875
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
876
|
+
|
|
877
|
+
#### HTTP 428
|
|
878
|
+
|
|
879
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
880
|
+
| --- | --- | --- | --- | --- |
|
|
881
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
882
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
883
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
884
|
+
|
|
885
|
+
#### HTTP 429
|
|
886
|
+
|
|
887
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
888
|
+
| --- | --- | --- | --- | --- |
|
|
889
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
890
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
891
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
892
|
+
|
|
893
|
+
#### HTTP 500
|
|
894
|
+
|
|
895
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
896
|
+
| --- | --- | --- | --- | --- |
|
|
897
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
898
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
899
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
900
|
+
|
|
901
|
+
### Known error codes
|
|
902
|
+
|
|
903
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
904
|
+
|
|
905
|
+
Unknown codes may also occur.
|
|
906
|
+
|
|
907
|
+
## PUT /api/card/connect/intents/{id}/cards
|
|
908
|
+
|
|
909
|
+
Atomically replace the cardholder-approved target card set for an active connect intent.
|
|
910
|
+
|
|
911
|
+
### Request headers and path parameters
|
|
912
|
+
|
|
913
|
+
| Name | Location | Required | Constraints |
|
|
914
|
+
| --- | --- | --- | --- |
|
|
915
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
916
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
917
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
918
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
919
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
920
|
+
| `id` | path | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` |
|
|
921
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
922
|
+
|
|
923
|
+
### Request body
|
|
924
|
+
|
|
925
|
+
Body required.
|
|
926
|
+
|
|
927
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
928
|
+
| --- | --- | --- | --- | --- |
|
|
929
|
+
| `approval_id` | string | Yes | min length 1; max length 255 | Partner approval identifier for the card replacement. |
|
|
930
|
+
| `approval_sha256` | string | Yes | pattern `^[a-f0-9]{64}$` | Lowercase SHA-256 digest of the approved payload. |
|
|
931
|
+
| `cards` | array | Yes | max items 50; items: [`TargetCardInput`](schemas.md#targetcardinput) | Card set for this intent. |
|
|
932
|
+
| `external_account_id` | one of the variants below | No | — | Opaque partner account identifier. |
|
|
933
|
+
| `intent_token` | string | Yes | — | Signed intent token issued by Facto for this connect intent. |
|
|
934
|
+
| `revision` | [`ConnectIntentDigest`](schemas.md#connectintentdigest) | Yes | pattern `^sha256:[a-fA-F0-9]{64}$` | Optimistic concurrency revision. |
|
|
935
|
+
|
|
936
|
+
|
|
937
|
+
**external_account_id variants**
|
|
938
|
+
|
|
939
|
+
#### Variant 1
|
|
940
|
+
|
|
941
|
+
Type: string. Constraints: min length 1; max length 512.
|
|
942
|
+
|
|
943
|
+
|
|
944
|
+
#### Variant 2
|
|
945
|
+
|
|
946
|
+
Type: null. Constraints: —.
|
|
947
|
+
|
|
948
|
+
### Responses
|
|
949
|
+
|
|
950
|
+
#### HTTP 200
|
|
951
|
+
|
|
952
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
953
|
+
| --- | --- | --- | --- | --- |
|
|
954
|
+
| `added_binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Binding IDs created by this replacement. |
|
|
955
|
+
| `id` | [`ConnectIntentId`](schemas.md#connectintentid) | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
|
|
956
|
+
| `kept_binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Binding IDs preserved unchanged. |
|
|
957
|
+
| `removed_binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Binding IDs revoked by this replacement. |
|
|
958
|
+
| `revision` | [`ConnectIntentDigest`](schemas.md#connectintentdigest) | Yes | pattern `^sha256:[a-fA-F0-9]{64}$` | Optimistic concurrency revision. |
|
|
959
|
+
| `status` | string | Yes | one of `applied`, `no_change` | Reported status; interpret in the context of this response. |
|
|
960
|
+
|
|
961
|
+
#### HTTP 400
|
|
962
|
+
|
|
963
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
964
|
+
| --- | --- | --- | --- | --- |
|
|
965
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
966
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
967
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
968
|
+
|
|
969
|
+
#### HTTP 401
|
|
970
|
+
|
|
971
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
972
|
+
| --- | --- | --- | --- | --- |
|
|
973
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
974
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
975
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
976
|
+
|
|
977
|
+
#### HTTP 403
|
|
978
|
+
|
|
979
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
980
|
+
| --- | --- | --- | --- | --- |
|
|
981
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
982
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
983
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
984
|
+
|
|
985
|
+
#### HTTP 404
|
|
986
|
+
|
|
987
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
988
|
+
| --- | --- | --- | --- | --- |
|
|
989
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
990
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
991
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
992
|
+
|
|
993
|
+
#### HTTP 409
|
|
994
|
+
|
|
995
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
996
|
+
| --- | --- | --- | --- | --- |
|
|
997
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
998
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
999
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1000
|
+
|
|
1001
|
+
#### HTTP 410
|
|
1002
|
+
|
|
1003
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1004
|
+
| --- | --- | --- | --- | --- |
|
|
1005
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1006
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1007
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1008
|
+
|
|
1009
|
+
#### HTTP 412
|
|
1010
|
+
|
|
1011
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1012
|
+
| --- | --- | --- | --- | --- |
|
|
1013
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1014
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1015
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1016
|
+
|
|
1017
|
+
#### HTTP 422
|
|
1018
|
+
|
|
1019
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1020
|
+
| --- | --- | --- | --- | --- |
|
|
1021
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1022
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1023
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1024
|
+
|
|
1025
|
+
#### HTTP 423
|
|
1026
|
+
|
|
1027
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1028
|
+
| --- | --- | --- | --- | --- |
|
|
1029
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1030
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1031
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1032
|
+
|
|
1033
|
+
#### HTTP 428
|
|
1034
|
+
|
|
1035
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1036
|
+
| --- | --- | --- | --- | --- |
|
|
1037
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1038
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1039
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1040
|
+
|
|
1041
|
+
#### HTTP 429
|
|
1042
|
+
|
|
1043
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1044
|
+
| --- | --- | --- | --- | --- |
|
|
1045
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1046
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1047
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1048
|
+
|
|
1049
|
+
#### HTTP 500
|
|
1050
|
+
|
|
1051
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1052
|
+
| --- | --- | --- | --- | --- |
|
|
1053
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1054
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1055
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1056
|
+
|
|
1057
|
+
### Known error codes
|
|
1058
|
+
|
|
1059
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1060
|
+
|
|
1061
|
+
Unknown codes may also occur.
|
|
1062
|
+
|
|
1063
|
+
## POST /api/card/connect/sessions
|
|
1064
|
+
|
|
1065
|
+
Create a partner-initiated hosted binding session for one granted card program and return its one-time binding URL and proof policy.
|
|
1066
|
+
|
|
1067
|
+
### Request headers and path parameters
|
|
1068
|
+
|
|
1069
|
+
| Name | Location | Required | Constraints |
|
|
1070
|
+
| --- | --- | --- | --- |
|
|
1071
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1072
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
1073
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
1074
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
1075
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
1076
|
+
| `x-facto-card-selection` | header | No | one of `1` |
|
|
1077
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
1078
|
+
|
|
1079
|
+
### Request body
|
|
1080
|
+
|
|
1081
|
+
Body required.
|
|
1082
|
+
|
|
1083
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1084
|
+
| --- | --- | --- | --- | --- |
|
|
1085
|
+
| `program_ref` | string | Yes | min length 1; max length 255 | Program reference assigned for this environment. |
|
|
1086
|
+
| `requested_user_consents` | array | Yes | min items 1; items: string | Non-empty unique set of user consent purposes requested for the binding session. |
|
|
1087
|
+
| `return_uri` | string | Yes | max length 2048; pattern `^https://[^/@?#\r\n]+(?:[/?][^#\r\n]*)?$` | Exact pre-registered HTTPS return URI used after the hosted authorization flow ends. |
|
|
1088
|
+
|
|
1089
|
+
### Responses
|
|
1090
|
+
|
|
1091
|
+
#### HTTP 201
|
|
1092
|
+
|
|
1093
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1094
|
+
| --- | --- | --- | --- | --- |
|
|
1095
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1096
|
+
| `binding_url` | string | Yes | — | Sensitive one-time Facto hosted authorization URL returned only to the authenticated partner backend. |
|
|
1097
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1098
|
+
| `proof_policy` | [`BindingProofPolicy`](schemas.md#bindingproofpolicy) | Yes | — | Server-determined proof policy governing proof modes, challenge delivery, and optional card selection. |
|
|
1099
|
+
| `status` | string | Yes | equals `pending` | Reported status; interpret in the context of this response. |
|
|
1100
|
+
|
|
1101
|
+
#### HTTP 400
|
|
1102
|
+
|
|
1103
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1104
|
+
| --- | --- | --- | --- | --- |
|
|
1105
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1106
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1107
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1108
|
+
|
|
1109
|
+
#### HTTP 401
|
|
1110
|
+
|
|
1111
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1112
|
+
| --- | --- | --- | --- | --- |
|
|
1113
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1114
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1115
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1116
|
+
|
|
1117
|
+
#### HTTP 403
|
|
1118
|
+
|
|
1119
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1120
|
+
| --- | --- | --- | --- | --- |
|
|
1121
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1122
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1123
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1124
|
+
|
|
1125
|
+
#### HTTP 404
|
|
1126
|
+
|
|
1127
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1128
|
+
| --- | --- | --- | --- | --- |
|
|
1129
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1130
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1131
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1132
|
+
|
|
1133
|
+
#### HTTP 409
|
|
1134
|
+
|
|
1135
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1136
|
+
| --- | --- | --- | --- | --- |
|
|
1137
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1138
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1139
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1140
|
+
|
|
1141
|
+
#### HTTP 410
|
|
1142
|
+
|
|
1143
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1144
|
+
| --- | --- | --- | --- | --- |
|
|
1145
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1146
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1147
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1148
|
+
|
|
1149
|
+
#### HTTP 412
|
|
1150
|
+
|
|
1151
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1152
|
+
| --- | --- | --- | --- | --- |
|
|
1153
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1154
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1155
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1156
|
+
|
|
1157
|
+
#### HTTP 422
|
|
1158
|
+
|
|
1159
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1160
|
+
| --- | --- | --- | --- | --- |
|
|
1161
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1162
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1163
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1164
|
+
|
|
1165
|
+
#### HTTP 423
|
|
1166
|
+
|
|
1167
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1168
|
+
| --- | --- | --- | --- | --- |
|
|
1169
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1170
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1171
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1172
|
+
|
|
1173
|
+
#### HTTP 428
|
|
1174
|
+
|
|
1175
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1176
|
+
| --- | --- | --- | --- | --- |
|
|
1177
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1178
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1179
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1180
|
+
|
|
1181
|
+
#### HTTP 429
|
|
1182
|
+
|
|
1183
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1184
|
+
| --- | --- | --- | --- | --- |
|
|
1185
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1186
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1187
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1188
|
+
|
|
1189
|
+
#### HTTP 500
|
|
1190
|
+
|
|
1191
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1192
|
+
| --- | --- | --- | --- | --- |
|
|
1193
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1194
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1195
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1196
|
+
|
|
1197
|
+
### Known error codes
|
|
1198
|
+
|
|
1199
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1200
|
+
|
|
1201
|
+
Unknown codes may also occur.
|
|
1202
|
+
|
|
1203
|
+
## GET /api/card/connect/sessions/{id}
|
|
1204
|
+
|
|
1205
|
+
Read the current state-safe status projection of a hosted binding session.
|
|
1206
|
+
|
|
1207
|
+
### Request headers and path parameters
|
|
1208
|
+
|
|
1209
|
+
| Name | Location | Required | Constraints |
|
|
1210
|
+
| --- | --- | --- | --- |
|
|
1211
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1212
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
1213
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
1214
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
1215
|
+
| `id` | path | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` |
|
|
1216
|
+
|
|
1217
|
+
### Request body
|
|
1218
|
+
|
|
1219
|
+
No structured JSON body is specified.
|
|
1220
|
+
|
|
1221
|
+
### Responses
|
|
1222
|
+
|
|
1223
|
+
#### HTTP 200
|
|
1224
|
+
|
|
1225
|
+
#### Variant 1
|
|
1226
|
+
|
|
1227
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1228
|
+
| --- | --- | --- | --- | --- |
|
|
1229
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1230
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1231
|
+
| `status` | string | Yes | equals `pending` | Reported status; interpret in the context of this response. |
|
|
1232
|
+
|
|
1233
|
+
|
|
1234
|
+
#### Variant 2
|
|
1235
|
+
|
|
1236
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1237
|
+
| --- | --- | --- | --- | --- |
|
|
1238
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1239
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1240
|
+
| `status` | string | Yes | equals `proof_pending` | Reported status; interpret in the context of this response. |
|
|
1241
|
+
|
|
1242
|
+
|
|
1243
|
+
#### Variant 3
|
|
1244
|
+
|
|
1245
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1246
|
+
| --- | --- | --- | --- | --- |
|
|
1247
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1248
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1249
|
+
| `status` | string | Yes | equals `consent_pending` | Reported status; interpret in the context of this response. |
|
|
1250
|
+
|
|
1251
|
+
|
|
1252
|
+
#### Variant 4
|
|
1253
|
+
|
|
1254
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1255
|
+
| --- | --- | --- | --- | --- |
|
|
1256
|
+
| `binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Stable sorted list of binding IDs created when the session completes as bound. |
|
|
1257
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1258
|
+
| `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
|
|
1259
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1260
|
+
| `outcome` | string | Yes | equals `bound` | Terminal decision outcome of a completed binding session. |
|
|
1261
|
+
| `status` | string | Yes | equals `completed` | Reported status; interpret in the context of this response. |
|
|
1262
|
+
|
|
1263
|
+
|
|
1264
|
+
#### Variant 5
|
|
1265
|
+
|
|
1266
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1267
|
+
| --- | --- | --- | --- | --- |
|
|
1268
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1269
|
+
| `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
|
|
1270
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1271
|
+
| `failure_reason` | string | Yes | equals `declined_by_user` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
|
|
1272
|
+
| `outcome` | string | Yes | equals `declined` | Terminal decision outcome of a completed binding session. |
|
|
1273
|
+
| `status` | string | Yes | equals `completed` | Reported status; interpret in the context of this response. |
|
|
1274
|
+
|
|
1275
|
+
|
|
1276
|
+
#### Variant 6
|
|
1277
|
+
|
|
1278
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1279
|
+
| --- | --- | --- | --- | --- |
|
|
1280
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1281
|
+
| `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
|
|
1282
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1283
|
+
| `failure_reason` | string | No | one of `cancelled_by_user`, `cancelled_by_partner`, `proof_rejected`, `admission_closed`, `no_eligible_cards`, `integrity_conflict` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
|
|
1284
|
+
| `status` | string | Yes | equals `cancelled` | Reported status; interpret in the context of this response. |
|
|
1285
|
+
|
|
1286
|
+
|
|
1287
|
+
#### Variant 7
|
|
1288
|
+
|
|
1289
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1290
|
+
| --- | --- | --- | --- | --- |
|
|
1291
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1292
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1293
|
+
| `failure_reason` | string | No | one of `expired`, `proof_timeout` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
|
|
1294
|
+
| `status` | string | Yes | equals `expired` | Reported status; interpret in the context of this response. |
|
|
1295
|
+
|
|
1296
|
+
#### HTTP 400
|
|
1297
|
+
|
|
1298
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1299
|
+
| --- | --- | --- | --- | --- |
|
|
1300
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1301
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1302
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1303
|
+
|
|
1304
|
+
#### HTTP 401
|
|
1305
|
+
|
|
1306
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1307
|
+
| --- | --- | --- | --- | --- |
|
|
1308
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1309
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1310
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1311
|
+
|
|
1312
|
+
#### HTTP 403
|
|
1313
|
+
|
|
1314
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1315
|
+
| --- | --- | --- | --- | --- |
|
|
1316
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1317
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1318
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1319
|
+
|
|
1320
|
+
#### HTTP 404
|
|
1321
|
+
|
|
1322
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1323
|
+
| --- | --- | --- | --- | --- |
|
|
1324
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1325
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1326
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1327
|
+
|
|
1328
|
+
#### HTTP 409
|
|
1329
|
+
|
|
1330
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1331
|
+
| --- | --- | --- | --- | --- |
|
|
1332
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1333
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1334
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1335
|
+
|
|
1336
|
+
#### HTTP 410
|
|
1337
|
+
|
|
1338
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1339
|
+
| --- | --- | --- | --- | --- |
|
|
1340
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1341
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1342
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1343
|
+
|
|
1344
|
+
#### HTTP 412
|
|
1345
|
+
|
|
1346
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1347
|
+
| --- | --- | --- | --- | --- |
|
|
1348
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1349
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1350
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1351
|
+
|
|
1352
|
+
#### HTTP 422
|
|
1353
|
+
|
|
1354
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1355
|
+
| --- | --- | --- | --- | --- |
|
|
1356
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1357
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1358
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1359
|
+
|
|
1360
|
+
#### HTTP 423
|
|
1361
|
+
|
|
1362
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1363
|
+
| --- | --- | --- | --- | --- |
|
|
1364
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1365
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1366
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1367
|
+
|
|
1368
|
+
#### HTTP 428
|
|
1369
|
+
|
|
1370
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1371
|
+
| --- | --- | --- | --- | --- |
|
|
1372
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1373
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1374
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1375
|
+
|
|
1376
|
+
#### HTTP 429
|
|
1377
|
+
|
|
1378
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1379
|
+
| --- | --- | --- | --- | --- |
|
|
1380
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1381
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1382
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1383
|
+
|
|
1384
|
+
#### HTTP 500
|
|
1385
|
+
|
|
1386
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1387
|
+
| --- | --- | --- | --- | --- |
|
|
1388
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1389
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1390
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1391
|
+
|
|
1392
|
+
### Known error codes
|
|
1393
|
+
|
|
1394
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1395
|
+
|
|
1396
|
+
Unknown codes may also occur.
|
|
1397
|
+
|
|
1398
|
+
## POST /api/card/connect/sessions/{id}/cancel
|
|
1399
|
+
|
|
1400
|
+
Cancel a nonterminal hosted binding session as the partner; already-terminal sessions return unchanged.
|
|
1401
|
+
|
|
1402
|
+
### Request headers and path parameters
|
|
1403
|
+
|
|
1404
|
+
| Name | Location | Required | Constraints |
|
|
1405
|
+
| --- | --- | --- | --- |
|
|
1406
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1407
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
1408
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
1409
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
1410
|
+
| `id` | path | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` |
|
|
1411
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
1412
|
+
|
|
1413
|
+
### Request body
|
|
1414
|
+
|
|
1415
|
+
No structured JSON body is specified.
|
|
1416
|
+
|
|
1417
|
+
### Responses
|
|
1418
|
+
|
|
1419
|
+
#### HTTP 200
|
|
1420
|
+
|
|
1421
|
+
#### Variant 1
|
|
1422
|
+
|
|
1423
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1424
|
+
| --- | --- | --- | --- | --- |
|
|
1425
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1426
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1427
|
+
| `status` | string | Yes | equals `pending` | Reported status; interpret in the context of this response. |
|
|
1428
|
+
|
|
1429
|
+
|
|
1430
|
+
#### Variant 2
|
|
1431
|
+
|
|
1432
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1433
|
+
| --- | --- | --- | --- | --- |
|
|
1434
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1435
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1436
|
+
| `status` | string | Yes | equals `proof_pending` | Reported status; interpret in the context of this response. |
|
|
1437
|
+
|
|
1438
|
+
|
|
1439
|
+
#### Variant 3
|
|
1440
|
+
|
|
1441
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1442
|
+
| --- | --- | --- | --- | --- |
|
|
1443
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1444
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1445
|
+
| `status` | string | Yes | equals `consent_pending` | Reported status; interpret in the context of this response. |
|
|
1446
|
+
|
|
1447
|
+
|
|
1448
|
+
#### Variant 4
|
|
1449
|
+
|
|
1450
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1451
|
+
| --- | --- | --- | --- | --- |
|
|
1452
|
+
| `binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Stable sorted list of binding IDs created when the session completes as bound. |
|
|
1453
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1454
|
+
| `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
|
|
1455
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1456
|
+
| `outcome` | string | Yes | equals `bound` | Terminal decision outcome of a completed binding session. |
|
|
1457
|
+
| `status` | string | Yes | equals `completed` | Reported status; interpret in the context of this response. |
|
|
1458
|
+
|
|
1459
|
+
|
|
1460
|
+
#### Variant 5
|
|
1461
|
+
|
|
1462
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1463
|
+
| --- | --- | --- | --- | --- |
|
|
1464
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1465
|
+
| `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
|
|
1466
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1467
|
+
| `failure_reason` | string | Yes | equals `declined_by_user` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
|
|
1468
|
+
| `outcome` | string | Yes | equals `declined` | Terminal decision outcome of a completed binding session. |
|
|
1469
|
+
| `status` | string | Yes | equals `completed` | Reported status; interpret in the context of this response. |
|
|
1470
|
+
|
|
1471
|
+
|
|
1472
|
+
#### Variant 6
|
|
1473
|
+
|
|
1474
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1475
|
+
| --- | --- | --- | --- | --- |
|
|
1476
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1477
|
+
| `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
|
|
1478
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1479
|
+
| `failure_reason` | string | No | one of `cancelled_by_user`, `cancelled_by_partner`, `proof_rejected`, `admission_closed`, `no_eligible_cards`, `integrity_conflict` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
|
|
1480
|
+
| `status` | string | Yes | equals `cancelled` | Reported status; interpret in the context of this response. |
|
|
1481
|
+
|
|
1482
|
+
|
|
1483
|
+
#### Variant 7
|
|
1484
|
+
|
|
1485
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1486
|
+
| --- | --- | --- | --- | --- |
|
|
1487
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1488
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1489
|
+
| `failure_reason` | string | No | one of `expired`, `proof_timeout` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
|
|
1490
|
+
| `status` | string | Yes | equals `expired` | Reported status; interpret in the context of this response. |
|
|
1491
|
+
|
|
1492
|
+
#### HTTP 400
|
|
1493
|
+
|
|
1494
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1495
|
+
| --- | --- | --- | --- | --- |
|
|
1496
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1497
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1498
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1499
|
+
|
|
1500
|
+
#### HTTP 401
|
|
1501
|
+
|
|
1502
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1503
|
+
| --- | --- | --- | --- | --- |
|
|
1504
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1505
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1506
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1507
|
+
|
|
1508
|
+
#### HTTP 403
|
|
1509
|
+
|
|
1510
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1511
|
+
| --- | --- | --- | --- | --- |
|
|
1512
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1513
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1514
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1515
|
+
|
|
1516
|
+
#### HTTP 404
|
|
1517
|
+
|
|
1518
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1519
|
+
| --- | --- | --- | --- | --- |
|
|
1520
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1521
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1522
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1523
|
+
|
|
1524
|
+
#### HTTP 409
|
|
1525
|
+
|
|
1526
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1527
|
+
| --- | --- | --- | --- | --- |
|
|
1528
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1529
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1530
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1531
|
+
|
|
1532
|
+
#### HTTP 410
|
|
1533
|
+
|
|
1534
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1535
|
+
| --- | --- | --- | --- | --- |
|
|
1536
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1537
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1538
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1539
|
+
|
|
1540
|
+
#### HTTP 412
|
|
1541
|
+
|
|
1542
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1543
|
+
| --- | --- | --- | --- | --- |
|
|
1544
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1545
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1546
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1547
|
+
|
|
1548
|
+
#### HTTP 422
|
|
1549
|
+
|
|
1550
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1551
|
+
| --- | --- | --- | --- | --- |
|
|
1552
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1553
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1554
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1555
|
+
|
|
1556
|
+
#### HTTP 423
|
|
1557
|
+
|
|
1558
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1559
|
+
| --- | --- | --- | --- | --- |
|
|
1560
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1561
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1562
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1563
|
+
|
|
1564
|
+
#### HTTP 428
|
|
1565
|
+
|
|
1566
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1567
|
+
| --- | --- | --- | --- | --- |
|
|
1568
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1569
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1570
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1571
|
+
|
|
1572
|
+
#### HTTP 429
|
|
1573
|
+
|
|
1574
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1575
|
+
| --- | --- | --- | --- | --- |
|
|
1576
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1577
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1578
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1579
|
+
|
|
1580
|
+
#### HTTP 500
|
|
1581
|
+
|
|
1582
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1583
|
+
| --- | --- | --- | --- | --- |
|
|
1584
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1585
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1586
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1587
|
+
|
|
1588
|
+
### Known error codes
|
|
1589
|
+
|
|
1590
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1591
|
+
|
|
1592
|
+
Unknown codes may also occur.
|
|
1593
|
+
|
|
1594
|
+
## GET /api/card/connect/sessions/{id}/proof-challenge
|
|
1595
|
+
|
|
1596
|
+
Read the active proof challenge of a hosted binding session for a provider_backend connection while proof_pending.
|
|
1597
|
+
|
|
1598
|
+
### Request headers and path parameters
|
|
1599
|
+
|
|
1600
|
+
| Name | Location | Required | Constraints |
|
|
1601
|
+
| --- | --- | --- | --- |
|
|
1602
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1603
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
1604
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
1605
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
1606
|
+
| `id` | path | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` |
|
|
1607
|
+
|
|
1608
|
+
### Request body
|
|
1609
|
+
|
|
1610
|
+
No structured JSON body is specified.
|
|
1611
|
+
|
|
1612
|
+
### Responses
|
|
1613
|
+
|
|
1614
|
+
#### HTTP 200
|
|
1615
|
+
|
|
1616
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1617
|
+
| --- | --- | --- | --- | --- |
|
|
1618
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1619
|
+
| `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
|
|
1620
|
+
| `facto_challenge` | string | Yes | — | High-entropy Facto challenge echoed in the provider proof assertion. |
|
|
1621
|
+
| `session_request_digest` | string | Yes | — | Canonical SHA-256 digest of the immutable session request bound into the proof assertion. |
|
|
1622
|
+
|
|
1623
|
+
#### HTTP 400
|
|
1624
|
+
|
|
1625
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1626
|
+
| --- | --- | --- | --- | --- |
|
|
1627
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1628
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1629
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1630
|
+
|
|
1631
|
+
#### HTTP 401
|
|
1632
|
+
|
|
1633
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1634
|
+
| --- | --- | --- | --- | --- |
|
|
1635
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1636
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1637
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1638
|
+
|
|
1639
|
+
#### HTTP 403
|
|
1640
|
+
|
|
1641
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1642
|
+
| --- | --- | --- | --- | --- |
|
|
1643
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1644
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1645
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1646
|
+
|
|
1647
|
+
#### HTTP 404
|
|
1648
|
+
|
|
1649
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1650
|
+
| --- | --- | --- | --- | --- |
|
|
1651
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1652
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1653
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1654
|
+
|
|
1655
|
+
#### HTTP 409
|
|
1656
|
+
|
|
1657
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1658
|
+
| --- | --- | --- | --- | --- |
|
|
1659
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1660
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1661
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1662
|
+
|
|
1663
|
+
#### HTTP 410
|
|
1664
|
+
|
|
1665
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1666
|
+
| --- | --- | --- | --- | --- |
|
|
1667
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1668
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1669
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1670
|
+
|
|
1671
|
+
#### HTTP 412
|
|
1672
|
+
|
|
1673
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1674
|
+
| --- | --- | --- | --- | --- |
|
|
1675
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1676
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1677
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1678
|
+
|
|
1679
|
+
#### HTTP 422
|
|
1680
|
+
|
|
1681
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1682
|
+
| --- | --- | --- | --- | --- |
|
|
1683
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1684
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1685
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1686
|
+
|
|
1687
|
+
#### HTTP 423
|
|
1688
|
+
|
|
1689
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1690
|
+
| --- | --- | --- | --- | --- |
|
|
1691
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1692
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1693
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1694
|
+
|
|
1695
|
+
#### HTTP 428
|
|
1696
|
+
|
|
1697
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1698
|
+
| --- | --- | --- | --- | --- |
|
|
1699
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1700
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1701
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1702
|
+
|
|
1703
|
+
#### HTTP 429
|
|
1704
|
+
|
|
1705
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1706
|
+
| --- | --- | --- | --- | --- |
|
|
1707
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1708
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1709
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1710
|
+
|
|
1711
|
+
#### HTTP 500
|
|
1712
|
+
|
|
1713
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1714
|
+
| --- | --- | --- | --- | --- |
|
|
1715
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1716
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1717
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1718
|
+
|
|
1719
|
+
### Known error codes
|
|
1720
|
+
|
|
1721
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1722
|
+
|
|
1723
|
+
Unknown codes may also occur.
|
|
1724
|
+
|
|
1725
|
+
## POST /api/card/connect/sessions/{id}/provider-proof
|
|
1726
|
+
|
|
1727
|
+
Submit a challenge-bound compact-JWS provider proof for a hosted binding session.
|
|
1728
|
+
|
|
1729
|
+
### Request headers and path parameters
|
|
1730
|
+
|
|
1731
|
+
| Name | Location | Required | Constraints |
|
|
1732
|
+
| --- | --- | --- | --- |
|
|
1733
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1734
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
1735
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
1736
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
1737
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
1738
|
+
| `id` | path | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` |
|
|
1739
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
1740
|
+
|
|
1741
|
+
### Request body
|
|
1742
|
+
|
|
1743
|
+
Body required.
|
|
1744
|
+
|
|
1745
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1746
|
+
| --- | --- | --- | --- | --- |
|
|
1747
|
+
| `binding_assertion` | string | Yes | min length 128; max length 16384; pattern `^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$` | Write-only compact EdDSA JWS signed by the partner carrying asserted cards and proof evidence. |
|
|
1748
|
+
| `proof_format` | string | Yes | equals `compact-jws` | Format of the submitted provider proof (compact-jws). |
|
|
1749
|
+
|
|
1750
|
+
### Responses
|
|
1751
|
+
|
|
1752
|
+
#### HTTP 202
|
|
1753
|
+
|
|
1754
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1755
|
+
| --- | --- | --- | --- | --- |
|
|
1756
|
+
| `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
|
|
1757
|
+
| `proof_received_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Timestamp when Facto durably accepted the provider proof. |
|
|
1758
|
+
| `status` | string | Yes | equals `consent_pending` | Reported status; interpret in the context of this response. |
|
|
1759
|
+
|
|
1760
|
+
#### HTTP 400
|
|
1761
|
+
|
|
1762
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1763
|
+
| --- | --- | --- | --- | --- |
|
|
1764
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1765
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1766
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1767
|
+
|
|
1768
|
+
#### HTTP 401
|
|
1769
|
+
|
|
1770
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1771
|
+
| --- | --- | --- | --- | --- |
|
|
1772
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1773
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1774
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1775
|
+
|
|
1776
|
+
#### HTTP 403
|
|
1777
|
+
|
|
1778
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1779
|
+
| --- | --- | --- | --- | --- |
|
|
1780
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1781
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1782
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1783
|
+
|
|
1784
|
+
#### HTTP 404
|
|
1785
|
+
|
|
1786
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1787
|
+
| --- | --- | --- | --- | --- |
|
|
1788
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1789
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1790
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1791
|
+
|
|
1792
|
+
#### HTTP 409
|
|
1793
|
+
|
|
1794
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1795
|
+
| --- | --- | --- | --- | --- |
|
|
1796
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1797
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1798
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1799
|
+
|
|
1800
|
+
#### HTTP 410
|
|
1801
|
+
|
|
1802
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1803
|
+
| --- | --- | --- | --- | --- |
|
|
1804
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1805
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1806
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1807
|
+
|
|
1808
|
+
#### HTTP 412
|
|
1809
|
+
|
|
1810
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1811
|
+
| --- | --- | --- | --- | --- |
|
|
1812
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1813
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1814
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1815
|
+
|
|
1816
|
+
#### HTTP 422
|
|
1817
|
+
|
|
1818
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1819
|
+
| --- | --- | --- | --- | --- |
|
|
1820
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1821
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1822
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1823
|
+
|
|
1824
|
+
#### HTTP 423
|
|
1825
|
+
|
|
1826
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1827
|
+
| --- | --- | --- | --- | --- |
|
|
1828
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1829
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1830
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1831
|
+
|
|
1832
|
+
#### HTTP 428
|
|
1833
|
+
|
|
1834
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1835
|
+
| --- | --- | --- | --- | --- |
|
|
1836
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1837
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1838
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1839
|
+
|
|
1840
|
+
#### HTTP 429
|
|
1841
|
+
|
|
1842
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1843
|
+
| --- | --- | --- | --- | --- |
|
|
1844
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1845
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1846
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1847
|
+
|
|
1848
|
+
#### HTTP 500
|
|
1849
|
+
|
|
1850
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1851
|
+
| --- | --- | --- | --- | --- |
|
|
1852
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1853
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1854
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1855
|
+
|
|
1856
|
+
### Known error codes
|
|
1857
|
+
|
|
1858
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1859
|
+
|
|
1860
|
+
Unknown codes may also occur.
|
|
1861
|
+
|
|
1862
|
+
## GET /api/card/deliveries/dead-letters
|
|
1863
|
+
|
|
1864
|
+
List webhook delivery dead-letter records for the authenticated connection.
|
|
1865
|
+
|
|
1866
|
+
### Request headers and path parameters
|
|
1867
|
+
|
|
1868
|
+
| Name | Location | Required | Constraints |
|
|
1869
|
+
| --- | --- | --- | --- |
|
|
1870
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1871
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
1872
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
1873
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
1874
|
+
| `limit` | query | No | min 1; max 100 |
|
|
1875
|
+
|
|
1876
|
+
### Request body
|
|
1877
|
+
|
|
1878
|
+
No structured JSON body is specified.
|
|
1879
|
+
|
|
1880
|
+
### Responses
|
|
1881
|
+
|
|
1882
|
+
#### HTTP 200
|
|
1883
|
+
|
|
1884
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1885
|
+
| --- | --- | --- | --- | --- |
|
|
1886
|
+
| `items` | array | Yes | items: [`DeadLetterItem`](schemas.md#deadletteritem) | Items returned on this page. |
|
|
1887
|
+
|
|
1888
|
+
#### HTTP 400
|
|
1889
|
+
|
|
1890
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1891
|
+
| --- | --- | --- | --- | --- |
|
|
1892
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1893
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1894
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1895
|
+
|
|
1896
|
+
#### HTTP 401
|
|
1897
|
+
|
|
1898
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1899
|
+
| --- | --- | --- | --- | --- |
|
|
1900
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1901
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1902
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1903
|
+
|
|
1904
|
+
#### HTTP 403
|
|
1905
|
+
|
|
1906
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1907
|
+
| --- | --- | --- | --- | --- |
|
|
1908
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1909
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1910
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1911
|
+
|
|
1912
|
+
#### HTTP 404
|
|
1913
|
+
|
|
1914
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1915
|
+
| --- | --- | --- | --- | --- |
|
|
1916
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1917
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1918
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1919
|
+
|
|
1920
|
+
#### HTTP 409
|
|
1921
|
+
|
|
1922
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1923
|
+
| --- | --- | --- | --- | --- |
|
|
1924
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1925
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1926
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1927
|
+
|
|
1928
|
+
#### HTTP 410
|
|
1929
|
+
|
|
1930
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1931
|
+
| --- | --- | --- | --- | --- |
|
|
1932
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1933
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1934
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1935
|
+
|
|
1936
|
+
#### HTTP 412
|
|
1937
|
+
|
|
1938
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1939
|
+
| --- | --- | --- | --- | --- |
|
|
1940
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1941
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1942
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1943
|
+
|
|
1944
|
+
#### HTTP 422
|
|
1945
|
+
|
|
1946
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1947
|
+
| --- | --- | --- | --- | --- |
|
|
1948
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1949
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1950
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1951
|
+
|
|
1952
|
+
#### HTTP 423
|
|
1953
|
+
|
|
1954
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1955
|
+
| --- | --- | --- | --- | --- |
|
|
1956
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1957
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1958
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1959
|
+
|
|
1960
|
+
#### HTTP 428
|
|
1961
|
+
|
|
1962
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1963
|
+
| --- | --- | --- | --- | --- |
|
|
1964
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1965
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1966
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1967
|
+
|
|
1968
|
+
#### HTTP 429
|
|
1969
|
+
|
|
1970
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1971
|
+
| --- | --- | --- | --- | --- |
|
|
1972
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1973
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1974
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1975
|
+
|
|
1976
|
+
#### HTTP 500
|
|
1977
|
+
|
|
1978
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
1979
|
+
| --- | --- | --- | --- | --- |
|
|
1980
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
1981
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
1982
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
1983
|
+
|
|
1984
|
+
### Known error codes
|
|
1985
|
+
|
|
1986
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
1987
|
+
|
|
1988
|
+
Unknown codes may also occur.
|
|
1989
|
+
|
|
1990
|
+
## POST /api/card/deliveries/dead-letters/{id}/replay
|
|
1991
|
+
|
|
1992
|
+
Accept a single dead-lettered webhook delivery for asynchronous redelivery.
|
|
1993
|
+
|
|
1994
|
+
### Request headers and path parameters
|
|
1995
|
+
|
|
1996
|
+
| Name | Location | Required | Constraints |
|
|
1997
|
+
| --- | --- | --- | --- |
|
|
1998
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
1999
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
2000
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
2001
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
2002
|
+
| `id` | path | Yes | format uuid |
|
|
2003
|
+
|
|
2004
|
+
### Request body
|
|
2005
|
+
|
|
2006
|
+
No structured JSON body is specified.
|
|
2007
|
+
|
|
2008
|
+
### Responses
|
|
2009
|
+
|
|
2010
|
+
#### HTTP 202
|
|
2011
|
+
|
|
2012
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2013
|
+
| --- | --- | --- | --- | --- |
|
|
2014
|
+
| `id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Resource identifier. |
|
|
2015
|
+
| `status` | string | Yes | equals `accepted` | Reported status; interpret in the context of this response. |
|
|
2016
|
+
|
|
2017
|
+
#### HTTP 400
|
|
2018
|
+
|
|
2019
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2020
|
+
| --- | --- | --- | --- | --- |
|
|
2021
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2022
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2023
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2024
|
+
|
|
2025
|
+
#### HTTP 401
|
|
2026
|
+
|
|
2027
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2028
|
+
| --- | --- | --- | --- | --- |
|
|
2029
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2030
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2031
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2032
|
+
|
|
2033
|
+
#### HTTP 403
|
|
2034
|
+
|
|
2035
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2036
|
+
| --- | --- | --- | --- | --- |
|
|
2037
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2038
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2039
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2040
|
+
|
|
2041
|
+
#### HTTP 404
|
|
2042
|
+
|
|
2043
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2044
|
+
| --- | --- | --- | --- | --- |
|
|
2045
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2046
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2047
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2048
|
+
|
|
2049
|
+
#### HTTP 409
|
|
2050
|
+
|
|
2051
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2052
|
+
| --- | --- | --- | --- | --- |
|
|
2053
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2054
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2055
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2056
|
+
|
|
2057
|
+
#### HTTP 410
|
|
2058
|
+
|
|
2059
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2060
|
+
| --- | --- | --- | --- | --- |
|
|
2061
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2062
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2063
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2064
|
+
|
|
2065
|
+
#### HTTP 412
|
|
2066
|
+
|
|
2067
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2068
|
+
| --- | --- | --- | --- | --- |
|
|
2069
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2070
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2071
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2072
|
+
|
|
2073
|
+
#### HTTP 422
|
|
2074
|
+
|
|
2075
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2076
|
+
| --- | --- | --- | --- | --- |
|
|
2077
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2078
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2079
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2080
|
+
|
|
2081
|
+
#### HTTP 423
|
|
2082
|
+
|
|
2083
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2084
|
+
| --- | --- | --- | --- | --- |
|
|
2085
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2086
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2087
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2088
|
+
|
|
2089
|
+
#### HTTP 428
|
|
2090
|
+
|
|
2091
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2092
|
+
| --- | --- | --- | --- | --- |
|
|
2093
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2094
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2095
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2096
|
+
|
|
2097
|
+
#### HTTP 429
|
|
2098
|
+
|
|
2099
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2100
|
+
| --- | --- | --- | --- | --- |
|
|
2101
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2102
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2103
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2104
|
+
|
|
2105
|
+
#### HTTP 500
|
|
2106
|
+
|
|
2107
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2108
|
+
| --- | --- | --- | --- | --- |
|
|
2109
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2110
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2111
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2112
|
+
|
|
2113
|
+
### Known error codes
|
|
2114
|
+
|
|
2115
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
2116
|
+
|
|
2117
|
+
Unknown codes may also occur.
|
|
2118
|
+
|
|
2119
|
+
## POST /api/card/deliveries/reconciliations/list
|
|
2120
|
+
|
|
2121
|
+
List paginated webhook delivery reconciliation items within a bounded snapshot.
|
|
2122
|
+
|
|
2123
|
+
### Request headers and path parameters
|
|
2124
|
+
|
|
2125
|
+
| Name | Location | Required | Constraints |
|
|
2126
|
+
| --- | --- | --- | --- |
|
|
2127
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
2128
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
2129
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
2130
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
2131
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
2132
|
+
|
|
2133
|
+
### Request body
|
|
2134
|
+
|
|
2135
|
+
Body required.
|
|
2136
|
+
|
|
2137
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2138
|
+
| --- | --- | --- | --- | --- |
|
|
2139
|
+
| `cursor` | string | No | min length 16; max length 4096 | Cursor returned by the preceding page. |
|
|
2140
|
+
| `from_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Lower boundary of the approved reconciliation time window. |
|
|
2141
|
+
| `page_size` | integer | Yes | min 1; max 100 | Maximum number of items in a page. |
|
|
2142
|
+
| `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
|
|
2143
|
+
| `selection_id` | [`CardUuid`](schemas.md#carduuid) | No | format uuid | Previously approved historical selection. |
|
|
2144
|
+
| `snapshot_token` | string | No | min length 16; max length 4096 | Snapshot token returned by the first page. |
|
|
2145
|
+
| `target_revision` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Delivery target revision. |
|
|
2146
|
+
| `to_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Upper boundary of the approved reconciliation time window. |
|
|
2147
|
+
|
|
2148
|
+
|
|
2149
|
+
Conditional rules:
|
|
2150
|
+
|
|
2151
|
+
- Choose exactly one: `selection_id` without time fields, or both `from_at` and `to_at` without `selection_id`.
|
|
2152
|
+
|
|
2153
|
+
### Responses
|
|
2154
|
+
|
|
2155
|
+
#### HTTP 200
|
|
2156
|
+
|
|
2157
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2158
|
+
| --- | --- | --- | --- | --- |
|
|
2159
|
+
| `complete` | boolean | Yes | — | Whether this snapshot page is the last page. |
|
|
2160
|
+
| `items` | array | Yes | min items 0; max items 100; items: [`DeliveryItem`](schemas.md#deliveryitem) | Items returned on this page. |
|
|
2161
|
+
| `next_cursor` | string or null | Yes | max length 4096 | Cursor for the next page, or null at the end. |
|
|
2162
|
+
| `snapshot_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Timestamp at which the snapshot was captured. |
|
|
2163
|
+
| `snapshot_token` | string | Yes | min length 16; max length 4096 | Snapshot token returned by the first page. |
|
|
2164
|
+
| `to_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Upper boundary of the approved reconciliation time window. |
|
|
2165
|
+
|
|
2166
|
+
#### HTTP 400
|
|
2167
|
+
|
|
2168
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2169
|
+
| --- | --- | --- | --- | --- |
|
|
2170
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2171
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2172
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2173
|
+
|
|
2174
|
+
#### HTTP 401
|
|
2175
|
+
|
|
2176
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2177
|
+
| --- | --- | --- | --- | --- |
|
|
2178
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2179
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2180
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2181
|
+
|
|
2182
|
+
#### HTTP 403
|
|
2183
|
+
|
|
2184
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2185
|
+
| --- | --- | --- | --- | --- |
|
|
2186
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2187
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2188
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2189
|
+
|
|
2190
|
+
#### HTTP 404
|
|
2191
|
+
|
|
2192
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2193
|
+
| --- | --- | --- | --- | --- |
|
|
2194
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2195
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2196
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2197
|
+
|
|
2198
|
+
#### HTTP 409
|
|
2199
|
+
|
|
2200
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2201
|
+
| --- | --- | --- | --- | --- |
|
|
2202
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2203
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2204
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2205
|
+
|
|
2206
|
+
#### HTTP 500
|
|
2207
|
+
|
|
2208
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2209
|
+
| --- | --- | --- | --- | --- |
|
|
2210
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2211
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2212
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2213
|
+
|
|
2214
|
+
#### HTTP 503
|
|
2215
|
+
|
|
2216
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2217
|
+
| --- | --- | --- | --- | --- |
|
|
2218
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2219
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2220
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2221
|
+
|
|
2222
|
+
### Known error codes
|
|
2223
|
+
|
|
2224
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
2225
|
+
|
|
2226
|
+
Unknown codes may also occur.
|
|
2227
|
+
|
|
2228
|
+
## POST /api/card/deliveries/replays
|
|
2229
|
+
|
|
2230
|
+
Create an asynchronous replay job for an approved historical event selection.
|
|
2231
|
+
|
|
2232
|
+
### Request headers and path parameters
|
|
2233
|
+
|
|
2234
|
+
| Name | Location | Required | Constraints |
|
|
2235
|
+
| --- | --- | --- | --- |
|
|
2236
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
2237
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
2238
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
2239
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
2240
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
2241
|
+
| `Idempotency-Key` | header | Yes | min length 16; max length 255 |
|
|
2242
|
+
|
|
2243
|
+
### Request body
|
|
2244
|
+
|
|
2245
|
+
Body required.
|
|
2246
|
+
|
|
2247
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2248
|
+
| --- | --- | --- | --- | --- |
|
|
2249
|
+
| `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
|
|
2250
|
+
| `selection_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Previously approved historical selection. |
|
|
2251
|
+
|
|
2252
|
+
### Responses
|
|
2253
|
+
|
|
2254
|
+
#### HTTP 202
|
|
2255
|
+
|
|
2256
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2257
|
+
| --- | --- | --- | --- | --- |
|
|
2258
|
+
| `replay_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Historical replay job identifier. |
|
|
2259
|
+
| `selection_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Previously approved historical selection. |
|
|
2260
|
+
| `status` | string | Yes | equals `accepted` | Reported status; interpret in the context of this response. |
|
|
2261
|
+
| `target_revision` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Delivery target revision. |
|
|
2262
|
+
|
|
2263
|
+
#### HTTP 400
|
|
2264
|
+
|
|
2265
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2266
|
+
| --- | --- | --- | --- | --- |
|
|
2267
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2268
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2269
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2270
|
+
|
|
2271
|
+
#### HTTP 401
|
|
2272
|
+
|
|
2273
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2274
|
+
| --- | --- | --- | --- | --- |
|
|
2275
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2276
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2277
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2278
|
+
|
|
2279
|
+
#### HTTP 403
|
|
2280
|
+
|
|
2281
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2282
|
+
| --- | --- | --- | --- | --- |
|
|
2283
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2284
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2285
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2286
|
+
|
|
2287
|
+
#### HTTP 404
|
|
2288
|
+
|
|
2289
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2290
|
+
| --- | --- | --- | --- | --- |
|
|
2291
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2292
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2293
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2294
|
+
|
|
2295
|
+
#### HTTP 409
|
|
2296
|
+
|
|
2297
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2298
|
+
| --- | --- | --- | --- | --- |
|
|
2299
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2300
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2301
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2302
|
+
|
|
2303
|
+
#### HTTP 500
|
|
2304
|
+
|
|
2305
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2306
|
+
| --- | --- | --- | --- | --- |
|
|
2307
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2308
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2309
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2310
|
+
|
|
2311
|
+
#### HTTP 503
|
|
2312
|
+
|
|
2313
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2314
|
+
| --- | --- | --- | --- | --- |
|
|
2315
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `not_found`, `integrity_conflict`, `query_unavailable`, `history_selection_mismatch`, `read_snapshot_stale`, `read_snapshot_expired`, `internal_error` | Machine-readable error code. |
|
|
2316
|
+
| `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
|
|
2317
|
+
| `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
|
|
2318
|
+
|
|
2319
|
+
### Known error codes
|
|
2320
|
+
|
|
2321
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
2322
|
+
|
|
2323
|
+
Unknown codes may also occur.
|
|
2324
|
+
|
|
2325
|
+
## POST /api/card/events
|
|
2326
|
+
|
|
2327
|
+
Record a signed inbound card lifecycle or account release event.
|
|
2328
|
+
|
|
2329
|
+
### Request headers and path parameters
|
|
2330
|
+
|
|
2331
|
+
| Name | Location | Required | Constraints |
|
|
2332
|
+
| --- | --- | --- | --- |
|
|
2333
|
+
| `x-api-key` | header | Yes | See authentication |
|
|
2334
|
+
| `x-api-timestamp` | header | Yes | See authentication |
|
|
2335
|
+
| `x-api-nonce` | header | Yes | See authentication |
|
|
2336
|
+
| `x-api-signature` | header | Yes | See authentication |
|
|
2337
|
+
| `Content-Type` | header | When sending JSON | `application/json` |
|
|
2338
|
+
|
|
2339
|
+
### Request body
|
|
2340
|
+
|
|
2341
|
+
Body required.
|
|
2342
|
+
|
|
2343
|
+
#### Variant 1
|
|
2344
|
+
|
|
2345
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2346
|
+
| --- | --- | --- | --- | --- |
|
|
2347
|
+
| `assertion_jws` | string | Yes | min length 1; pattern `\S` | Certified compact JWS assertion signed by the partner. |
|
|
2348
|
+
| `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
|
|
2349
|
+
| `external_account_id` | null | No | — | Opaque partner account identifier. |
|
|
2350
|
+
| `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
|
|
2351
|
+
| `kind` | string | Yes | equals `card.unbound` | Kind of event or fact. |
|
|
2352
|
+
| `lifecycle_status` | null | No | — | Updated card lifecycle status. |
|
|
2353
|
+
|
|
2354
|
+
|
|
2355
|
+
#### Variant 2
|
|
2356
|
+
|
|
2357
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2358
|
+
| --- | --- | --- | --- | --- |
|
|
2359
|
+
| `assertion_jws` | string | Yes | min length 1; pattern `\S` | Certified compact JWS assertion signed by the partner. |
|
|
2360
|
+
| `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
|
|
2361
|
+
| `external_account_id` | null | No | — | Opaque partner account identifier. |
|
|
2362
|
+
| `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
|
|
2363
|
+
| `kind` | string | Yes | equals `card.lifecycle_changed` | Kind of event or fact. |
|
|
2364
|
+
| `lifecycle_status` | string | Yes | one of `pending`, `active`, `frozen`, `closed`, `replaced`, `unknown` | Updated card lifecycle status. |
|
|
2365
|
+
|
|
2366
|
+
|
|
2367
|
+
#### Variant 3
|
|
2368
|
+
|
|
2369
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2370
|
+
| --- | --- | --- | --- | --- |
|
|
2371
|
+
| `assertion_jws` | string | Yes | min length 1; pattern `\S` | Certified compact JWS assertion signed by the partner. |
|
|
2372
|
+
| `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
|
|
2373
|
+
| `external_account_id` | string | Yes | min length 1; max length 512 | Opaque partner account identifier. |
|
|
2374
|
+
| `external_card_id` | null | No | — | Opaque card identifier assigned by the partner. |
|
|
2375
|
+
| `kind` | string | Yes | equals `account.released` | Kind of event or fact. |
|
|
2376
|
+
| `lifecycle_status` | null | No | — | Updated card lifecycle status. |
|
|
2377
|
+
|
|
2378
|
+
### Responses
|
|
2379
|
+
|
|
2380
|
+
#### HTTP 200
|
|
2381
|
+
|
|
2382
|
+
#### Variant 1
|
|
2383
|
+
|
|
2384
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2385
|
+
| --- | --- | --- | --- | --- |
|
|
2386
|
+
| `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
|
|
2387
|
+
| `disposition` | string | Yes | equals `applied` | Whether the inbound event was applied or deduplicated. |
|
|
2388
|
+
| `effect` | string | Yes | one of `revoked`, `status_updated`, `released`, `none` | Reported lifecycle effect. |
|
|
2389
|
+
|
|
2390
|
+
|
|
2391
|
+
#### Variant 2
|
|
2392
|
+
|
|
2393
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2394
|
+
| --- | --- | --- | --- | --- |
|
|
2395
|
+
| `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
|
|
2396
|
+
| `disposition` | string | Yes | equals `duplicate` | Whether the inbound event was applied or deduplicated. |
|
|
2397
|
+
| `effect` | null | Yes | — | Reported lifecycle effect. |
|
|
2398
|
+
|
|
2399
|
+
#### HTTP 400
|
|
2400
|
+
|
|
2401
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2402
|
+
| --- | --- | --- | --- | --- |
|
|
2403
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2404
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2405
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2406
|
+
|
|
2407
|
+
#### HTTP 401
|
|
2408
|
+
|
|
2409
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2410
|
+
| --- | --- | --- | --- | --- |
|
|
2411
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2412
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2413
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2414
|
+
|
|
2415
|
+
#### HTTP 403
|
|
2416
|
+
|
|
2417
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2418
|
+
| --- | --- | --- | --- | --- |
|
|
2419
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2420
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2421
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2422
|
+
|
|
2423
|
+
#### HTTP 404
|
|
2424
|
+
|
|
2425
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2426
|
+
| --- | --- | --- | --- | --- |
|
|
2427
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2428
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2429
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2430
|
+
|
|
2431
|
+
#### HTTP 409
|
|
2432
|
+
|
|
2433
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2434
|
+
| --- | --- | --- | --- | --- |
|
|
2435
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2436
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2437
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2438
|
+
|
|
2439
|
+
#### HTTP 410
|
|
2440
|
+
|
|
2441
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2442
|
+
| --- | --- | --- | --- | --- |
|
|
2443
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2444
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2445
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2446
|
+
|
|
2447
|
+
#### HTTP 412
|
|
2448
|
+
|
|
2449
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2450
|
+
| --- | --- | --- | --- | --- |
|
|
2451
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2452
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2453
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2454
|
+
|
|
2455
|
+
#### HTTP 422
|
|
2456
|
+
|
|
2457
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2458
|
+
| --- | --- | --- | --- | --- |
|
|
2459
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2460
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2461
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2462
|
+
|
|
2463
|
+
#### HTTP 423
|
|
2464
|
+
|
|
2465
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2466
|
+
| --- | --- | --- | --- | --- |
|
|
2467
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2468
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2469
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2470
|
+
|
|
2471
|
+
#### HTTP 428
|
|
2472
|
+
|
|
2473
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2474
|
+
| --- | --- | --- | --- | --- |
|
|
2475
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2476
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2477
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2478
|
+
|
|
2479
|
+
#### HTTP 429
|
|
2480
|
+
|
|
2481
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2482
|
+
| --- | --- | --- | --- | --- |
|
|
2483
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2484
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2485
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2486
|
+
|
|
2487
|
+
#### HTTP 500
|
|
2488
|
+
|
|
2489
|
+
| Field | Type | Required | Constraints | Meaning |
|
|
2490
|
+
| --- | --- | --- | --- | --- |
|
|
2491
|
+
| `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
|
|
2492
|
+
| `message` | string | Yes | — | Human-readable explanation. |
|
|
2493
|
+
| `request_id` | string | Yes | — | Request correlation identifier. |
|
|
2494
|
+
|
|
2495
|
+
### Known error codes
|
|
2496
|
+
|
|
2497
|
+
`authentication_failed`, `program_grant_denied`, `invalid_request`, `not_found`, `integrity_conflict`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `idempotency_payload_mismatch`, `version_already_recorded`, `mapping_revision_not_approved`, `fact_type_not_allowed`, `managed_route_refused`, `ambiguous_lookup_selector`, `precondition_failed`, `stale_revision`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `too_many_requests`, `rate_limited`
|
|
2498
|
+
|
|
2499
|
+
Unknown codes may also occur.
|
|
2500
|
+
|
|
2501
|
+
## Known machine error codes
|
|
2502
|
+
|
|
2503
|
+
The table is not exhaustive. Groups identify source envelopes.
|
|
2504
|
+
|
|
2505
|
+
| Code | Contract group |
|
|
2506
|
+
| --- | --- |
|
|
2507
|
+
| `ambiguous_lookup_selector` | Card machine |
|
|
2508
|
+
| `assertion_rejected` | Card machine |
|
|
2509
|
+
| `assertion_replayed` | Card machine |
|
|
2510
|
+
| `authentication_failed` | Card machine |
|
|
2511
|
+
| `authorization_admission_closed` | Authorization |
|
|
2512
|
+
| `binding_admission_closed` | Card machine |
|
|
2513
|
+
| `consent_scope_not_payable` | Authorization |
|
|
2514
|
+
| `decision_deadline_exceeded` | Authorization |
|
|
2515
|
+
| `fact_type_not_allowed` | Card machine |
|
|
2516
|
+
| `idempotency_payload_mismatch` | Card machine |
|
|
2517
|
+
| `integrity_conflict` | Card machine |
|
|
2518
|
+
| `intent_expired` | Card machine |
|
|
2519
|
+
| `intent_sealed` | Card machine |
|
|
2520
|
+
| `intent_token_rejected` | Card machine |
|
|
2521
|
+
| `internal_error` | Authorization |
|
|
2522
|
+
| `invalid_request` | Card machine |
|
|
2523
|
+
| `managed_route_refused` | Card machine |
|
|
2524
|
+
| `mapping_revision_not_approved` | Card machine |
|
|
2525
|
+
| `not_found` | Card machine |
|
|
2526
|
+
| `onchain_insufficient_balance` | Authorization |
|
|
2527
|
+
| `precondition_failed` | Card machine |
|
|
2528
|
+
| `program_grant_denied` | Card machine |
|
|
2529
|
+
| `prohibited_data` | Card machine |
|
|
2530
|
+
| `proof_mode_denied` | Card machine |
|
|
2531
|
+
| `provider_proof_required` | Card machine |
|
|
2532
|
+
| `rate_limited` | Card machine |
|
|
2533
|
+
| `return_uri_not_registered` | Card machine |
|
|
2534
|
+
| `route_not_payable` | Authorization |
|
|
2535
|
+
| `spending_limit_exceeded` | Authorization |
|
|
2536
|
+
| `stale_revision` | Card machine |
|
|
2537
|
+
| `sync_approval_admission_closed` | Authorization |
|
|
2538
|
+
| `tenant_scope_mismatch` | Card machine |
|
|
2539
|
+
| `too_many_requests` | Card machine |
|
|
2540
|
+
| `version_already_recorded` | Card machine |
|
|
2541
|
+
| `yield_source_underfunded` | Authorization |
|