@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.
Files changed (69) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +5 -0
  4. package/README.md +63 -2
  5. package/dist/card-inbox-DzsHFRPT.d.cts +312 -0
  6. package/dist/card-inbox-DzsHFRPT.d.ts +312 -0
  7. package/dist/chunk-KBS2PWM4.js +2 -0
  8. package/dist/cli/index.js +6 -0
  9. package/dist/docs/README.md +9 -0
  10. package/dist/docs/authentication.md +96 -0
  11. package/dist/docs/authorization-binding.md +182 -0
  12. package/dist/docs/authorizations.md +182 -0
  13. package/dist/docs/concepts.md +36 -0
  14. package/dist/docs/deliveries.md +170 -0
  15. package/dist/docs/errors.md +100 -0
  16. package/dist/docs/getting-access.md +56 -0
  17. package/dist/docs/idempotency.md +78 -0
  18. package/dist/docs/integration-checklist.md +15 -0
  19. package/dist/docs/integration.zh.md +59 -0
  20. package/dist/docs/interlace-adapter-v1.md +87 -0
  21. package/dist/docs/interlace-adapter-v1.zh.md +87 -0
  22. package/dist/docs/not-yet-available.md +13 -0
  23. package/dist/docs/quickstart.md +126 -0
  24. package/dist/docs/reconciliation.md +86 -0
  25. package/dist/docs/reference/api.md +2541 -0
  26. package/dist/docs/reference/events.md +639 -0
  27. package/dist/docs/reference/schemas.json +6603 -0
  28. package/dist/docs/reference/schemas.md +1001 -0
  29. package/dist/docs/simulator.md +235 -0
  30. package/dist/docs/versioning.md +9 -0
  31. package/dist/index.cjs +3 -0
  32. package/dist/index.d.cts +987 -0
  33. package/dist/index.d.ts +987 -0
  34. package/dist/index.js +2 -0
  35. package/dist/source/build.mjs +5 -0
  36. package/dist/source/package.json +16 -0
  37. package/dist/source/src/connect/cli/deliveries.ts +48 -0
  38. package/dist/source/src/connect/cli/index.ts +57 -0
  39. package/dist/source/src/connect/server/card-binding-assertion.ts +312 -0
  40. package/dist/source/src/connect/server/card-client.ts +1018 -0
  41. package/dist/source/src/connect/server/card-delivery.ts +301 -0
  42. package/dist/source/src/connect/server/card-events.ts +473 -0
  43. package/dist/source/src/connect/server/card-idempotency.ts +27 -0
  44. package/dist/source/src/connect/server/card-inbox.ts +82 -0
  45. package/dist/source/src/connect/server/card-intent-token.ts +588 -0
  46. package/dist/source/src/connect/server/card-polling.ts +69 -0
  47. package/dist/source/src/connect/server/card-signing.ts +115 -0
  48. package/dist/source/src/connect/server/card-transport.ts +282 -0
  49. package/dist/source/src/connect/server/errors.ts +280 -0
  50. package/dist/source/src/connect/server/fixtures/engine/card-events.synthetic.ts +84 -0
  51. package/dist/source/src/connect/server/retry-after.ts +12 -0
  52. package/dist/source/src/connect/testing/card-inbox.ts +124 -0
  53. package/dist/source/src/connect/testing/card-scenarios.ts +243 -0
  54. package/dist/source/src/connect/testing/card-simulator-vectors.ts +262 -0
  55. package/dist/source/src/connect/testing/card-simulator.ts +531 -0
  56. package/dist/source/src/connect/testing/interlace-card-transactions.ts +704 -0
  57. package/dist/source/src/connect/testing/pure-sha256.ts +123 -0
  58. package/dist/source/src/connect/wire.d.ts +544 -0
  59. package/dist/source/src/index.ts +163 -0
  60. package/dist/source/src/testing-browser.ts +24 -0
  61. package/dist/source/src/testing.ts +26 -0
  62. package/dist/source/tsconfig.json +20 -0
  63. package/dist/testing-browser.d.ts +220 -0
  64. package/dist/testing-browser.js +5 -0
  65. package/dist/testing.cjs +6 -0
  66. package/dist/testing.d.cts +199 -0
  67. package/dist/testing.d.ts +199 -0
  68. package/dist/testing.js +5 -0
  69. 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 |