@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,1001 @@
1
+ # Schema appendix
2
+
3
+ Nested types and constraints from the pinned contract. The [machine-readable schemas](schemas.json) contain the full structural constraints.
4
+
5
+ ## AuthorizationAccepted
6
+
7
+ | Field | Type | Required | Constraints | Meaning |
8
+ | --- | --- | --- | --- | --- |
9
+ | `charge_id` | string | Yes | min length 1; max length 255 | Public charge identifier. |
10
+ | `status` | string | Yes | equals `processing` | Reported status; interpret in the context of this response. |
11
+
12
+
13
+ ## AuthorizationChargeIdLookup
14
+
15
+ | Field | Type | Required | Constraints | Meaning |
16
+ | --- | --- | --- | --- | --- |
17
+ | `by` | string | Yes | equals `charge_id` | Selects the lookup identity. |
18
+ | `charge_id` | string | Yes | min length 1; max length 255 | Public charge identifier. |
19
+
20
+
21
+ ## AuthorizationCreateInput
22
+
23
+ | Field | Type | Required | Constraints | Meaning |
24
+ | --- | --- | --- | --- | --- |
25
+ | `amount` | string | Yes | min length 1; max length 64 | Decimal amount for the operation. |
26
+ | `cardholder_verification` | [`CardholderVerification`](schemas.md#cardholderverification) | Yes | — | Cardholder verification evidence. |
27
+ | `client_transaction_id` | string | No | min length 1; max length 256 | Caller-provided transaction correlation identifier. |
28
+ | `currency` | string | Yes | one of `USD`, `USDC` | ISO or token currency code. |
29
+ | `deadline_at` | string | No | format date-time | Effective decision deadline. |
30
+ | `decision_mode` | string | No | one of `asynchronous`, `synchronous` | Requested asynchronous or synchronous decision mode. |
31
+ | `decision_timeout_ms` | integer | No | min 50; max 5000 | Requested synchronous decision time limit in milliseconds. |
32
+ | `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
33
+ | `external_card_id` | string | Yes | min length 1; max length 512 | Opaque card identifier assigned by the partner. |
34
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
35
+ | `merchant_country` | string | No | min length 1; max length 8 | ISO country code reported for this transaction. |
36
+ | `merchant_mcc` | string | No | min length 0; max length 16 | Merchant category code reported for this transaction. |
37
+ | `merchant_name` | string | No | min length 0; max length 256 | Merchant name reported for this transaction. |
38
+ | `occurred_at` | string | No | format date-time | Time when the event or authorization occurred. |
39
+ | `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
40
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
41
+ | `supplier_transaction_id` | string | No | min length 1; max length 256 | Partner transaction identifier for this operation. |
42
+
43
+
44
+ Conditional rules:
45
+
46
+ - `decision_timeout_ms` and `deadline_at` are allowed only for synchronous original authorizations; synchronous approval is currently closed.
47
+
48
+
49
+ ## AuthorizationDeadlineExceeded
50
+
51
+ | Field | Type | Required | Constraints | Meaning |
52
+ | --- | --- | --- | --- | --- |
53
+ | `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
54
+ | `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
55
+ | `error` | string | Yes | equals `decision_deadline_exceeded` | Machine-readable error code. |
56
+ | `message` | string | Yes | — | Human-readable explanation. |
57
+ | `request_id` | string | Yes | — | Request correlation identifier. |
58
+
59
+
60
+ ## AuthorizationError
61
+
62
+ | Field | Type | Required | Constraints | Meaning |
63
+ | --- | --- | --- | --- | --- |
64
+ | `error` | string | Yes | min length 1; max length 128; pattern `^[a-z][a-z0-9_]*$` | Machine-readable error code. |
65
+ | `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
66
+ | `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
67
+
68
+
69
+ ## AuthorizationFact
70
+
71
+ | Field | Type | Required | Constraints | Meaning |
72
+ | --- | --- | --- | --- | --- |
73
+ | `kind` | [`AuthorizationFactKind`](schemas.md#authorizationfactkind) | Yes | one of `facto_admission`, `durable_commit`, `provider_authorization`, `chain_finality`, `provider_settlement` | Kind of event or fact. |
74
+ | `observed_at` | [`AuthorizationTimestamp`](schemas.md#authorizationtimestamp) | No | format date-time | Time of the returned observation. |
75
+ | `recorded_at` | [`AuthorizationTimestamp`](schemas.md#authorizationtimestamp) | Yes | format date-time | Time the fact was recorded. |
76
+ | `safe_code` | string | No | min length 1; max length 64 | Bounded machine-readable fact code, when available. |
77
+ | `source_system` | string | Yes | one of `facto`, `provider`, `chain` | System that reported the fact. |
78
+ | `state` | string | Yes | one of `unobserved`, `pending`, `confirmed`, `rejected`, `indeterminate` | Observed state. |
79
+
80
+
81
+ Conditional rules:
82
+
83
+ - If state is `confirmed`, `observed_at` is present.
84
+ - If state is `unobserved`, not (`observed_at` is present).
85
+
86
+
87
+ ## AuthorizationFactInput
88
+
89
+ | Field | Type | Required | Constraints | Meaning |
90
+ | --- | --- | --- | --- | --- |
91
+ | `amount` | string | Yes | min length 1; max length 64 | Decimal amount for the operation. |
92
+ | `client_transaction_id` | string | No | min length 1; max length 256 | Caller-provided transaction correlation identifier. |
93
+ | `currency` | string | Yes | one of `USD`, `USDC` | ISO or token currency code. |
94
+ | `fact_type` | string | Yes | one of `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
95
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
96
+ | `merchant_country` | string | No | min length 1; max length 8 | ISO country code reported for this transaction. |
97
+ | `merchant_mcc` | string | No | min length 0; max length 16 | Merchant category code reported for this transaction. |
98
+ | `merchant_name` | string | No | min length 0; max length 256 | Merchant name reported for this transaction. |
99
+ | `parent_supplier_transaction_id` | string | No | min length 1; max length 256 | Partner identifier for the preceding transaction. |
100
+ | `predecessor_version` | string | Yes | min length 1; max length 255 | Previous distinct version for a subsequent fact. |
101
+ | `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
102
+ | `recorded_at` | string | Yes | format date-time | Time the fact was recorded. |
103
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
104
+ | `supplier_transaction_id` | string | No | min length 1; max length 256 | Partner transaction identifier for this operation. |
105
+
106
+
107
+ Conditional rules:
108
+
109
+ - A subsequent fact requires a distinct `predecessor_version` that already exists on the same authorization lineage.
110
+ - Every subsequent fact needs its own stable idempotency key and resource version.
111
+
112
+
113
+ ## AuthorizationFactKind
114
+
115
+ Type: string. Constraints: one of `facto_admission`, `durable_commit`, `provider_authorization`, `chain_finality`, `provider_settlement`.
116
+
117
+
118
+ ## AuthorizationFactReceipt
119
+
120
+ | Field | Type | Required | Constraints | Meaning |
121
+ | --- | --- | --- | --- | --- |
122
+ | `operation_id` | string | Yes | format uuid | Recorded operation identifier. |
123
+ | `status` | string | Yes | equals `recorded` | Reported status; interpret in the context of this response. |
124
+
125
+
126
+ ## AuthorizationFacts
127
+
128
+ Type: array. Constraints: min items 5; max items 5.
129
+
130
+ Fixed element order:
131
+
132
+ - Position 1: [`AuthorizationFact`](schemas.md#authorizationfact); kind is `facto_admission`.
133
+ - Position 2: [`AuthorizationFact`](schemas.md#authorizationfact); kind is `durable_commit`.
134
+ - Position 3: [`AuthorizationFact`](schemas.md#authorizationfact); kind is `provider_authorization`.
135
+ - Position 4: [`AuthorizationFact`](schemas.md#authorizationfact); kind is `chain_finality`.
136
+ - Position 5: [`AuthorizationFact`](schemas.md#authorizationfact); kind is `provider_settlement`.
137
+
138
+
139
+ ## AuthorizationIdempotencyLookup
140
+
141
+ | Field | Type | Required | Constraints | Meaning |
142
+ | --- | --- | --- | --- | --- |
143
+ | `by` | string | Yes | equals `idempotency_key` | Selects the lookup identity. |
144
+ | `idempotency_key` | string | Yes | min length 16; max length 255 | Original idempotency key used for the authorization. |
145
+ | `operation` | string | No | equals `create_authorization` | Idempotent operation category. |
146
+ | `original_credential_key_id` | string | Yes | min length 1; max length 255 | Key ID that signed the original authorization. |
147
+
148
+
149
+ ## AuthorizationLifecycle
150
+
151
+ | Field | Type | Required | Constraints | Meaning |
152
+ | --- | --- | --- | --- | --- |
153
+ | `issuer` | [`AuthorizationSupplierSummary`](schemas.md#authorizationsuppliersummary) | Yes | — | Value shape: [`AuthorizationSupplierSummary`](schemas.md#authorizationsuppliersummary). |
154
+ | `refund_cases` | array | Yes | items: [`AuthorizationRefundCase`](schemas.md#authorizationrefundcase) | Value shape: array. |
155
+
156
+
157
+ ## AuthorizationLifecycleEntry
158
+
159
+ | Field | Type | Required | Constraints | Meaning |
160
+ | --- | --- | --- | --- | --- |
161
+ | `amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Decimal amount for the operation. |
162
+ | `currency` | string | Yes | one of `USDC` | ISO or token currency code. |
163
+ | `link_status` | string | Yes | one of `linked`, `unlinked` | Value shape: string. |
164
+ | `operation_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | Yes | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Authorization or lifecycle operation kind. |
165
+ | `recorded_at` | string | Yes | format date-time | Time the fact was recorded. |
166
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
167
+ | `unlinked_reason` | string | No | — | Value shape: string. |
168
+
169
+
170
+ ## AuthorizationLookupInput
171
+
172
+ | Field | Type | Required | Constraints | Meaning |
173
+ | --- | --- | --- | --- | --- |
174
+ | `criteria` | one of the variants below | Yes | — | Exactly one authorization lookup selector. |
175
+ | `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
176
+
177
+
178
+ **criteria variants**
179
+
180
+ #### Variant 1: AuthorizationRefLookup
181
+
182
+ | Field | Type | Required | Constraints | Meaning |
183
+ | --- | --- | --- | --- | --- |
184
+ | `by` | string | Yes | equals `external_authorization_id` | Selects the lookup identity. |
185
+ | `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
186
+ | `fact_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | No | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
187
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
188
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
189
+
190
+
191
+ #### Variant 2: SupplierTransactionRefLookup
192
+
193
+ | Field | Type | Required | Constraints | Meaning |
194
+ | --- | --- | --- | --- | --- |
195
+ | `by` | string | Yes | equals `supplier_transaction_id` | Selects the lookup identity. |
196
+ | `fact_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | No | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
197
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
198
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
199
+ | `supplier_transaction_id` | string | Yes | min length 1; max length 256 | Partner transaction identifier for this operation. |
200
+
201
+
202
+ #### Variant 3: AuthorizationIdempotencyLookup
203
+
204
+ | Field | Type | Required | Constraints | Meaning |
205
+ | --- | --- | --- | --- | --- |
206
+ | `by` | string | Yes | equals `idempotency_key` | Selects the lookup identity. |
207
+ | `idempotency_key` | string | Yes | min length 16; max length 255 | Original idempotency key used for the authorization. |
208
+ | `operation` | string | No | equals `create_authorization` | Idempotent operation category. |
209
+ | `original_credential_key_id` | string | Yes | min length 1; max length 255 | Key ID that signed the original authorization. |
210
+
211
+
212
+ #### Variant 4: AuthorizationChargeIdLookup
213
+
214
+ | Field | Type | Required | Constraints | Meaning |
215
+ | --- | --- | --- | --- | --- |
216
+ | `by` | string | Yes | equals `charge_id` | Selects the lookup identity. |
217
+ | `charge_id` | string | Yes | min length 1; max length 255 | Public charge identifier. |
218
+
219
+
220
+ ## AuthorizationLookupResult
221
+
222
+ | Field | Type | Required | Constraints | Meaning |
223
+ | --- | --- | --- | --- | --- |
224
+ | `authorization` | [`AuthorizationProjection`](schemas.md#authorizationprojection) | No | — | Authorization projection, when observed. |
225
+ | `observed_at` | [`AuthorizationTimestamp`](schemas.md#authorizationtimestamp) | Yes | format date-time | Time of the returned observation. |
226
+ | `resolution` | string | Yes | one of `resolved`, `pending`, `unknown`, `not_observed` | Lookup resolution. |
227
+
228
+
229
+ Conditional rules:
230
+
231
+ - If resolution is `not_observed`, not (`authorization` is present).
232
+ - If resolution is `resolved`, `authorization` is present and authorization.processing_status is one of `succeeded`, `failed`.
233
+ - If resolution is `pending`, `authorization` is present and authorization.processing_status is one of `processing`.
234
+ - If resolution is `unknown`, `authorization` is present and authorization.processing_status is one of `indeterminate`.
235
+
236
+
237
+ ## AuthorizationOperationType
238
+
239
+ Type: string. Constraints: one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement`.
240
+
241
+
242
+ ## AuthorizationPaymentDetails
243
+
244
+ | Field | Type | Required | Constraints | Meaning |
245
+ | --- | --- | --- | --- | --- |
246
+ | `fee_breakdown` | object | Yes | — | Value shape: object. |
247
+ | `fee_total` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Value shape: [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount). |
248
+ | `refund_payments` | array | No | items: object | Value shape: array. |
249
+ | `user_payment` | object | No | — | Value shape: object. |
250
+
251
+
252
+ ## AuthorizationProgramConnectionId
253
+
254
+ Type: string. Constraints: pattern `^pconn_[A-Za-z0-9_-]{16,}$`.
255
+
256
+
257
+ ## AuthorizationProjection
258
+
259
+ | Field | Type | Required | Constraints | Meaning |
260
+ | --- | --- | --- | --- | --- |
261
+ | `charge_id` | string | No | min length 1; max length 255 | Public charge identifier. |
262
+ | `decision` | string | No | one of `approved`, `declined`, `self_reversed_timeout` | Synchronous decision. |
263
+ | `decline_reason_code` | string | No | min length 1; max length 64; pattern `^[A-Za-z0-9_.:-]+$` | Value shape: string. |
264
+ | `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
265
+ | `facts` | [`AuthorizationFacts`](schemas.md#authorizationfacts) | Yes | min items 5; max items 5 | Current observed facts. |
266
+ | `final_receipt` | [`ChargeFinalReceipt`](schemas.md#chargefinalreceipt) | No | — | Terminal execution receipt. |
267
+ | `lifecycle` | [`AuthorizationLifecycle`](schemas.md#authorizationlifecycle) | No | — | Value shape: [`AuthorizationLifecycle`](schemas.md#authorizationlifecycle). |
268
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
269
+ | `operation_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | Yes | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Authorization or lifecycle operation kind. |
270
+ | `origin_connection_id` | [`AuthorizationProgramConnectionId`](schemas.md#authorizationprogramconnectionid) | Yes | pattern `^pconn_[A-Za-z0-9_-]{16,}$` | Connection that originated the event or authorization. |
271
+ | `payment_details` | [`AuthorizationPaymentDetails`](schemas.md#authorizationpaymentdetails) | No | — | Value shape: [`AuthorizationPaymentDetails`](schemas.md#authorizationpaymentdetails). |
272
+ | `processing_status` | string | Yes | one of `processing`, `succeeded`, `failed`, `indeterminate` | Processing state for the original operation. |
273
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
274
+ | `revision` | [`AuthorizationRevision`](schemas.md#authorizationrevision) | Yes | min 1; max 2147483647 | Optimistic concurrency revision. |
275
+ | `supplier_transaction_id` | string | No | min length 1; max length 256 | Partner transaction identifier for this operation. |
276
+
277
+
278
+ Conditional rules:
279
+
280
+ - If processing_status is `succeeded`, `charge_id` is present.
281
+ - Otherwise, when processing_status is `succeeded` is false, not (`final_receipt` is present).
282
+ - If processing_status is `succeeded`, `final_receipt` is present.
283
+ - If `final_receipt` is present, not (`decline_reason_code` is present).
284
+ - If `decline_reason_code` is present, processing_status is `failed`.
285
+ - If `charge_id` is present, processing_status is one of `processing`, `succeeded`, `failed`.
286
+ - If processing_status is `succeeded`, final_receipt.execution_outcome is `succeeded`.
287
+ - If processing_status is `failed`, final_receipt.execution_outcome is `failed`.
288
+
289
+
290
+ ## AuthorizationRefLookup
291
+
292
+ | Field | Type | Required | Constraints | Meaning |
293
+ | --- | --- | --- | --- | --- |
294
+ | `by` | string | Yes | equals `external_authorization_id` | Selects the lookup identity. |
295
+ | `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
296
+ | `fact_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | No | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
297
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
298
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
299
+
300
+
301
+ ## AuthorizationRefundCase
302
+
303
+ | Field | Type | Required | Constraints | Meaning |
304
+ | --- | --- | --- | --- | --- |
305
+ | `amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Decimal amount for the operation. |
306
+ | `case_id` | string | Yes | pattern `^rfc_[0-9a-f]{32}$` | Value shape: string. |
307
+ | `excess_amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Value shape: [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount). |
308
+ | `not_payable_reason` | string | No | — | Value shape: string. |
309
+ | `paid_amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | No | pattern `^-?[0-9]+\.[0-9]{6}$` | Value shape: [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount). |
310
+ | `source_operation_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | Yes | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle operation kind that opened the refund case. |
311
+ | `source_resource_version` | string | Yes | min length 1; max length 255 | Resource version of the lifecycle operation that opened the refund case. |
312
+ | `status` | string | Yes | — | Reported status; interpret in the context of this response. |
313
+ | `updated_at` | string | Yes | format date-time | Value shape: string. |
314
+
315
+
316
+ ## AuthorizationRevision
317
+
318
+ Type: integer. Constraints: min 1; max 2147483647.
319
+
320
+
321
+ ## AuthorizationSupplierSummary
322
+
323
+ | Field | Type | Required | Constraints | Meaning |
324
+ | --- | --- | --- | --- | --- |
325
+ | `cleared_amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Value shape: [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount). |
326
+ | `entries` | array | Yes | items: [`AuthorizationLifecycleEntry`](schemas.md#authorizationlifecycleentry) | Value shape: array. |
327
+ | `refunded_amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Value shape: [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount). |
328
+ | `reversed_amount` | [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount) | Yes | pattern `^-?[0-9]+\.[0-9]{6}$` | Value shape: [`AuthorizationUsdcAmount`](schemas.md#authorizationusdcamount). |
329
+ | `state` | string | Yes | — | Observed state. |
330
+
331
+
332
+ ## AuthorizationTimestamp
333
+
334
+ Type: string. Constraints: format date-time.
335
+
336
+
337
+ ## AuthorizationUsdcAmount
338
+
339
+ Type: string. Constraints: pattern `^-?[0-9]+\.[0-9]{6}$`.
340
+
341
+
342
+ ## AuthorizationUuid
343
+
344
+ Type: string. Constraints: format uuid.
345
+
346
+
347
+ ## BindingFundingProjection
348
+
349
+ | Field | Type | Required | Constraints | Meaning |
350
+ | --- | --- | --- | --- | --- |
351
+ | `configured` | boolean | Yes | — | Value shape: boolean. |
352
+ | `reason` | string | No | — | Value shape: string. |
353
+ | `state` | string | Yes | one of `ready`, `not_configured`, `unavailable` | Observed state. |
354
+
355
+
356
+ ## BindingLookupInput
357
+
358
+ | Field | Type | Required | Constraints | Meaning |
359
+ | --- | --- | --- | --- | --- |
360
+ | `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
361
+
362
+
363
+ ## BindingLookupResult
364
+
365
+ | Field | Type | Required | Constraints | Meaning |
366
+ | --- | --- | --- | --- | --- |
367
+ | `binding` | one of the variants below | Yes | — | Current binding projection, or null when unbound. |
368
+ | `found` | boolean | Yes | — | Whether an active or revoked binding matched. |
369
+
370
+
371
+ **binding variants**
372
+
373
+ #### Variant 1: BindingSummary
374
+
375
+ | Field | Type | Required | Constraints | Meaning |
376
+ | --- | --- | --- | --- | --- |
377
+ | `card` | [`CardDisplayFacts`](schemas.md#carddisplayfacts) | Yes | — | Card display metadata. |
378
+ | `funding` | [`BindingFundingProjection`](schemas.md#bindingfundingprojection) | No | — | Funding readiness summary, when included. |
379
+ | `id` | [`CardBindingId`](schemas.md#cardbindingid) | Yes | pattern `^cb_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
380
+ | `revision` | integer | Yes | min 1; format int32 | Optimistic concurrency revision. |
381
+ | `status` | string | Yes | one of `active`, `revoked` | Reported status; interpret in the context of this response. |
382
+
383
+
384
+ #### Variant 2
385
+
386
+ Type: null. Constraints: —.
387
+
388
+
389
+ ## BindingProofChallenge
390
+
391
+ | Field | Type | Required | Constraints | Meaning |
392
+ | --- | --- | --- | --- | --- |
393
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
394
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
395
+ | `facto_challenge` | string | Yes | — | High-entropy Facto challenge echoed in the provider proof assertion. |
396
+ | `session_request_digest` | string | Yes | — | Canonical SHA-256 digest of the immutable session request bound into the proof assertion. |
397
+
398
+
399
+ ## BindingProofPolicy
400
+
401
+ | Field | Type | Required | Constraints | Meaning |
402
+ | --- | --- | --- | --- | --- |
403
+ | `allowed_modes` | array | Yes | min items 1; items: string | Proof modes accepted for this binding session. |
404
+ | `card_selection_supported` | boolean | No | equals `true` | Present as true only when the create request opted in with x-facto-card-selection: 1. |
405
+ | `challenge_after_facto_auth` | boolean | Yes | equals `true` | Always true: a proof challenge is issued only after the cardholder authenticates in Facto. |
406
+ | `challenge_delivery` | string | Yes | one of `browser_handoff`, `provider_backend` | Configured challenge delivery channel for this connection. |
407
+
408
+
409
+ ## BindingSessionCreate
410
+
411
+ | Field | Type | Required | Constraints | Meaning |
412
+ | --- | --- | --- | --- | --- |
413
+ | `program_ref` | string | Yes | min length 1; max length 255 | Program reference assigned for this environment. |
414
+ | `requested_user_consents` | array | Yes | min items 1; items: string | Non-empty unique set of user consent purposes requested for the binding session. |
415
+ | `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. |
416
+
417
+
418
+ ## BindingSessionCreated
419
+
420
+ | Field | Type | Required | Constraints | Meaning |
421
+ | --- | --- | --- | --- | --- |
422
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
423
+ | `binding_url` | string | Yes | — | Sensitive one-time Facto hosted authorization URL returned only to the authenticated partner backend. |
424
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
425
+ | `proof_policy` | [`BindingProofPolicy`](schemas.md#bindingproofpolicy) | Yes | — | Server-determined proof policy governing proof modes, challenge delivery, and optional card selection. |
426
+ | `status` | string | Yes | equals `pending` | Reported status; interpret in the context of this response. |
427
+
428
+
429
+ ## BindingSessionId
430
+
431
+ Type: string. Constraints: pattern `^cbs_[A-Za-z0-9_-]{16,}$`.
432
+
433
+
434
+ ## BindingSessionStatus
435
+
436
+ #### Variant 1
437
+
438
+ | Field | Type | Required | Constraints | Meaning |
439
+ | --- | --- | --- | --- | --- |
440
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
441
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
442
+ | `status` | string | Yes | equals `pending` | Reported status; interpret in the context of this response. |
443
+
444
+
445
+ #### Variant 2
446
+
447
+ | Field | Type | Required | Constraints | Meaning |
448
+ | --- | --- | --- | --- | --- |
449
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
450
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
451
+ | `status` | string | Yes | equals `proof_pending` | Reported status; interpret in the context of this response. |
452
+
453
+
454
+ #### Variant 3
455
+
456
+ | Field | Type | Required | Constraints | Meaning |
457
+ | --- | --- | --- | --- | --- |
458
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
459
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
460
+ | `status` | string | Yes | equals `consent_pending` | Reported status; interpret in the context of this response. |
461
+
462
+
463
+ #### Variant 4
464
+
465
+ | Field | Type | Required | Constraints | Meaning |
466
+ | --- | --- | --- | --- | --- |
467
+ | `binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Stable sorted list of binding IDs created when the session completes as bound. |
468
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
469
+ | `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
470
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
471
+ | `outcome` | string | Yes | equals `bound` | Terminal decision outcome of a completed binding session. |
472
+ | `status` | string | Yes | equals `completed` | Reported status; interpret in the context of this response. |
473
+
474
+
475
+ #### Variant 5
476
+
477
+ | Field | Type | Required | Constraints | Meaning |
478
+ | --- | --- | --- | --- | --- |
479
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
480
+ | `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
481
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
482
+ | `failure_reason` | string | Yes | equals `declined_by_user` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
483
+ | `outcome` | string | Yes | equals `declined` | Terminal decision outcome of a completed binding session. |
484
+ | `status` | string | Yes | equals `completed` | Reported status; interpret in the context of this response. |
485
+
486
+
487
+ #### Variant 6
488
+
489
+ | Field | Type | Required | Constraints | Meaning |
490
+ | --- | --- | --- | --- | --- |
491
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
492
+ | `completed_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Timestamp when the session reached a completed or cancelled terminal state. |
493
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
494
+ | `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. |
495
+ | `status` | string | Yes | equals `cancelled` | Reported status; interpret in the context of this response. |
496
+
497
+
498
+ #### Variant 7
499
+
500
+ | Field | Type | Required | Constraints | Meaning |
501
+ | --- | --- | --- | --- | --- |
502
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
503
+ | `expires_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Expiration timestamp. |
504
+ | `failure_reason` | string | No | one of `expired`, `proof_timeout` | Terminal reason explaining why a session ended declined, cancelled, or expired. |
505
+ | `status` | string | Yes | equals `expired` | Reported status; interpret in the context of this response. |
506
+
507
+
508
+ ## BindingSummary
509
+
510
+ | Field | Type | Required | Constraints | Meaning |
511
+ | --- | --- | --- | --- | --- |
512
+ | `card` | [`CardDisplayFacts`](schemas.md#carddisplayfacts) | Yes | — | Card display metadata. |
513
+ | `funding` | [`BindingFundingProjection`](schemas.md#bindingfundingprojection) | No | — | Funding readiness summary, when included. |
514
+ | `id` | [`CardBindingId`](schemas.md#cardbindingid) | Yes | pattern `^cb_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
515
+ | `revision` | integer | Yes | min 1; format int32 | Optimistic concurrency revision. |
516
+ | `status` | string | Yes | one of `active`, `revoked` | Reported status; interpret in the context of this response. |
517
+
518
+
519
+ ## CardBindingId
520
+
521
+ Type: string. Constraints: pattern `^cb_[A-Za-z0-9_-]{16,}$`.
522
+
523
+
524
+ ## CardDisplayFacts
525
+
526
+ | Field | Type | Required | Constraints | Meaning |
527
+ | --- | --- | --- | --- | --- |
528
+ | `last4` | one of the variants below | Yes | — | Last four card digits, when available. |
529
+ | `network` | one of the variants below | Yes | — | Card network, when available. |
530
+ | `type` | one of the variants below | Yes | — | Card or change type. |
531
+
532
+
533
+ **last4 variants**
534
+
535
+ #### Variant 1
536
+
537
+ Type: string. Constraints: pattern `^[0-9]{4}$`.
538
+
539
+
540
+ #### Variant 2
541
+
542
+ Type: null. Constraints: —.
543
+
544
+
545
+ **network variants**
546
+
547
+ #### Variant 1
548
+
549
+ Type: string. Constraints: max length 40.
550
+
551
+
552
+ #### Variant 2
553
+
554
+ Type: null. Constraints: —.
555
+
556
+
557
+ **type variants**
558
+
559
+ #### Variant 1
560
+
561
+ Type: string. Constraints: one of `virtual`, `physical`, `unknown`.
562
+
563
+
564
+ #### Variant 2
565
+
566
+ Type: null. Constraints: —.
567
+
568
+
569
+ ## CardError
570
+
571
+ | Field | Type | Required | Constraints | Meaning |
572
+ | --- | --- | --- | --- | --- |
573
+ | `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. |
574
+ | `message` | string | Yes | min length 1; max length 512 | Human-readable explanation. |
575
+ | `request_id` | string | Yes | min length 1; max length 128 | Request correlation identifier. |
576
+
577
+
578
+ ## CardholderVerification
579
+
580
+ | Field | Type | Required | Constraints | Meaning |
581
+ | --- | --- | --- | --- | --- |
582
+ | `evidence_id` | string | Yes | min length 1; max length 256 | Partner identifier for the verification evidence. |
583
+ | `method` | string | Yes | one of `pin`, `biometric`, `cdcvm`, `signature`, `no_cvm`, `provider_attested` | Cardholder verification method. |
584
+ | `verified_at` | [`AuthorizationTimestamp`](schemas.md#authorizationtimestamp) | Yes | format date-time | Time of cardholder verification. |
585
+
586
+
587
+ ## CardInboundEventInput
588
+
589
+ #### Variant 1
590
+
591
+ | Field | Type | Required | Constraints | Meaning |
592
+ | --- | --- | --- | --- | --- |
593
+ | `assertion_jws` | string | Yes | min length 1; pattern `\S` | Certified compact JWS assertion signed by the partner. |
594
+ | `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
595
+ | `external_account_id` | null | No | — | Opaque partner account identifier. |
596
+ | `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
597
+ | `kind` | string | Yes | equals `card.unbound` | Kind of event or fact. |
598
+ | `lifecycle_status` | null | No | — | Updated card lifecycle status. |
599
+
600
+
601
+ #### Variant 2
602
+
603
+ | Field | Type | Required | Constraints | Meaning |
604
+ | --- | --- | --- | --- | --- |
605
+ | `assertion_jws` | string | Yes | min length 1; pattern `\S` | Certified compact JWS assertion signed by the partner. |
606
+ | `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
607
+ | `external_account_id` | null | No | — | Opaque partner account identifier. |
608
+ | `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
609
+ | `kind` | string | Yes | equals `card.lifecycle_changed` | Kind of event or fact. |
610
+ | `lifecycle_status` | string | Yes | one of `pending`, `active`, `frozen`, `closed`, `replaced`, `unknown` | Updated card lifecycle status. |
611
+
612
+
613
+ #### Variant 3
614
+
615
+ | Field | Type | Required | Constraints | Meaning |
616
+ | --- | --- | --- | --- | --- |
617
+ | `assertion_jws` | string | Yes | min length 1; pattern `\S` | Certified compact JWS assertion signed by the partner. |
618
+ | `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
619
+ | `external_account_id` | string | Yes | min length 1; max length 512 | Opaque partner account identifier. |
620
+ | `external_card_id` | null | No | — | Opaque card identifier assigned by the partner. |
621
+ | `kind` | string | Yes | equals `account.released` | Kind of event or fact. |
622
+ | `lifecycle_status` | null | No | — | Updated card lifecycle status. |
623
+
624
+
625
+ ## CardInboundEventReceipt
626
+
627
+ #### Variant 1
628
+
629
+ | Field | Type | Required | Constraints | Meaning |
630
+ | --- | --- | --- | --- | --- |
631
+ | `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
632
+ | `disposition` | string | Yes | equals `applied` | Whether the inbound event was applied or deduplicated. |
633
+ | `effect` | string | Yes | one of `revoked`, `status_updated`, `released`, `none` | Reported lifecycle effect. |
634
+
635
+
636
+ #### Variant 2
637
+
638
+ | Field | Type | Required | Constraints | Meaning |
639
+ | --- | --- | --- | --- | --- |
640
+ | `delivery_id` | string | Yes | min length 1; max length 255 | Partner delivery UUID. |
641
+ | `disposition` | string | Yes | equals `duplicate` | Whether the inbound event was applied or deduplicated. |
642
+ | `effect` | null | Yes | — | Reported lifecycle effect. |
643
+
644
+
645
+ ## CardMachineError
646
+
647
+ | Field | Type | Required | Constraints | Meaning |
648
+ | --- | --- | --- | --- | --- |
649
+ | `error` | string | Yes | one of `invalid_request`, `authentication_failed`, `program_grant_denied`, `assertion_rejected`, `assertion_replayed`, `tenant_scope_mismatch`, `integrity_conflict`, `provider_proof_required`, `proof_mode_denied`, `binding_admission_closed`, `prohibited_data`, `return_uri_not_registered`, `not_found`, `rate_limited`, `intent_token_rejected`, `intent_sealed`, `intent_expired`, `stale_revision`, `internal_error` | Machine-readable error code. |
650
+ | `message` | string | Yes | — | Human-readable explanation. |
651
+ | `request_id` | string | Yes | — | Request correlation identifier. |
652
+
653
+
654
+ ## CardNoStoreHeader
655
+
656
+ Type: string. Constraints: equals `no-store`.
657
+
658
+
659
+ ## CardTimestamp
660
+
661
+ Type: string. Constraints: format date-time.
662
+
663
+
664
+ ## CardUuid
665
+
666
+ Type: string. Constraints: format uuid.
667
+
668
+
669
+ ## ChargeFinalReceipt
670
+
671
+ | Field | Type | Required | Constraints | Meaning |
672
+ | --- | --- | --- | --- | --- |
673
+ | `charge_id` | string | Yes | min length 1; max length 255 | Public charge identifier. |
674
+ | `execution_outcome` | string | Yes | one of `succeeded`, `failed` | Terminal execution outcome. |
675
+ | `external_authorization_id` | string | Yes | min length 1; max length 256 | Stable identifier for the authorization lineage. |
676
+ | `facts_at_finality` | [`AuthorizationFacts`](schemas.md#authorizationfacts) | Yes | min items 5; max items 5 | Facts observed at execution finality. |
677
+ | `finalized_at` | [`AuthorizationTimestamp`](schemas.md#authorizationtimestamp) | Yes | format date-time | Time execution reached finality. |
678
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
679
+ | `operation_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | Yes | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Authorization or lifecycle operation kind. |
680
+ | `receipt_event_id` | [`AuthorizationUuid`](schemas.md#authorizationuuid) | Yes | format uuid | Final receipt event identifier. |
681
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
682
+ | `terminal_action` | string | Yes | one of `releaseFor`, `cancelReservation` | Terminal execution action. |
683
+
684
+
685
+ Conditional rules:
686
+
687
+ - facts_at_finality[3].state is `confirmed`.
688
+ - If terminal_action is `releaseFor`, execution_outcome is `succeeded` and facts_at_finality[0].state is `confirmed` and facts_at_finality[1].state is `confirmed`.
689
+ - Otherwise, when terminal_action is `releaseFor` is false, execution_outcome is `failed`.
690
+
691
+
692
+ ## ConnectIntentDigest
693
+
694
+ Type: string. Constraints: pattern `^sha256:[a-fA-F0-9]{64}$`.
695
+
696
+
697
+ ## ConnectIntentId
698
+
699
+ Type: string. Constraints: pattern `^cint_[A-Za-z0-9_-]{16,}$`.
700
+
701
+
702
+ ## DeadLetterItem
703
+
704
+ | Field | Type | Required | Constraints | Meaning |
705
+ | --- | --- | --- | --- | --- |
706
+ | `binding_id` | [`CardBindingId`](schemas.md#cardbindingid) | Yes | pattern `^cb_[A-Za-z0-9_-]{16,}$` | Card binding identifier. |
707
+ | `binding_revision` | integer | Yes | format int32 | Card binding revision. |
708
+ | `connection_sequence` | one of the variants below | Yes | — | Per-connection sequence, when available. |
709
+ | `dead_lettered_at` | one of the variants below | Yes | — | Value shape: one of the variants below. |
710
+ | `delivery_attempts` | integer | Yes | format int32 | Value shape: integer. |
711
+ | `event_kind` | string | Yes | — | Event kind. |
712
+ | `id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Resource identifier. |
713
+ | `last_delivery_error` | one of the variants below | Yes | — | Value shape: one of the variants below. |
714
+ | `replay_count` | integer | Yes | format int32 | Value shape: integer. |
715
+
716
+
717
+ **connection_sequence variants**
718
+
719
+ #### Variant 1
720
+
721
+ Type: integer. Constraints: format int64.
722
+
723
+
724
+ #### Variant 2
725
+
726
+ Type: null. Constraints: —.
727
+
728
+
729
+ **dead_lettered_at variants**
730
+
731
+ #### Variant 1: CardTimestamp
732
+
733
+ Type: [`CardTimestamp`](schemas.md#cardtimestamp). Constraints: format date-time.
734
+
735
+
736
+ #### Variant 2
737
+
738
+ Type: null. Constraints: —.
739
+
740
+
741
+ **last_delivery_error variants**
742
+
743
+ #### Variant 1
744
+
745
+ Type: string. Constraints: —.
746
+
747
+
748
+ #### Variant 2
749
+
750
+ Type: null. Constraints: —.
751
+
752
+
753
+ ## DeadLetterPage
754
+
755
+ | Field | Type | Required | Constraints | Meaning |
756
+ | --- | --- | --- | --- | --- |
757
+ | `items` | array | Yes | items: [`DeadLetterItem`](schemas.md#deadletteritem) | Items returned on this page. |
758
+
759
+
760
+ ## DeadLetterReplayAccepted
761
+
762
+ | Field | Type | Required | Constraints | Meaning |
763
+ | --- | --- | --- | --- | --- |
764
+ | `id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Resource identifier. |
765
+ | `status` | string | Yes | equals `accepted` | Reported status; interpret in the context of this response. |
766
+
767
+
768
+ ## DeliveryItem
769
+
770
+ | Field | Type | Required | Constraints | Meaning |
771
+ | --- | --- | --- | --- | --- |
772
+ | `accepted_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Value shape: [`CardTimestamp`](schemas.md#cardtimestamp). |
773
+ | `connection_sequence` | integer or null | Yes | min 1 | Per-connection sequence, when available. |
774
+ | `delivery_state` | string | Yes | one of `pending`, `held`, `accepted`, `failed`, `dead_lettered`, `indeterminate` | Current delivery state. |
775
+ | `event_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Delivery event identifier. |
776
+ | `event_sha256` | string | Yes | pattern `^[a-f0-9]{64}$` | Lowercase SHA-256 hex digest of the event body. |
777
+ | `origin_connection_id` | [`ProgramConnectionId`](schemas.md#programconnectionid) | Yes | pattern `^pconn_[A-Za-z0-9_-]{16,}$` | Connection that originated the event or authorization. |
778
+ | `target_revision` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Delivery target revision. |
779
+
780
+
781
+ ## DeliveryPage
782
+
783
+ | Field | Type | Required | Constraints | Meaning |
784
+ | --- | --- | --- | --- | --- |
785
+ | `complete` | boolean | Yes | — | Whether this snapshot page is the last page. |
786
+ | `items` | array | Yes | min items 0; max items 100; items: [`DeliveryItem`](schemas.md#deliveryitem) | Items returned on this page. |
787
+ | `next_cursor` | string or null | Yes | max length 4096 | Cursor for the next page, or null at the end. |
788
+ | `snapshot_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Timestamp at which the snapshot was captured. |
789
+ | `snapshot_token` | string | Yes | min length 16; max length 4096 | Snapshot token returned by the first page. |
790
+ | `to_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Upper boundary of the approved reconciliation time window. |
791
+
792
+
793
+ ## DeliveryReconciliationListInput
794
+
795
+ | Field | Type | Required | Constraints | Meaning |
796
+ | --- | --- | --- | --- | --- |
797
+ | `cursor` | string | No | min length 16; max length 4096 | Cursor returned by the preceding page. |
798
+ | `from_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Lower boundary of the approved reconciliation time window. |
799
+ | `page_size` | integer | Yes | min 1; max 100 | Maximum number of items in a page. |
800
+ | `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
801
+ | `selection_id` | [`CardUuid`](schemas.md#carduuid) | No | format uuid | Previously approved historical selection. |
802
+ | `snapshot_token` | string | No | min length 16; max length 4096 | Snapshot token returned by the first page. |
803
+ | `target_revision` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Delivery target revision. |
804
+ | `to_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | No | format date-time | Upper boundary of the approved reconciliation time window. |
805
+
806
+
807
+ Conditional rules:
808
+
809
+ - Choose exactly one: `selection_id` without time fields, or both `from_at` and `to_at` without `selection_id`.
810
+
811
+
812
+ ## DeliveryReplayAccepted
813
+
814
+ | Field | Type | Required | Constraints | Meaning |
815
+ | --- | --- | --- | --- | --- |
816
+ | `replay_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Historical replay job identifier. |
817
+ | `selection_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Previously approved historical selection. |
818
+ | `status` | string | Yes | equals `accepted` | Reported status; interpret in the context of this response. |
819
+ | `target_revision` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Delivery target revision. |
820
+
821
+
822
+ ## DeliveryReplayCreateInput
823
+
824
+ | Field | Type | Required | Constraints | Meaning |
825
+ | --- | --- | --- | --- | --- |
826
+ | `program_id` | string | Yes | min length 1; max length 512 | Program identifier assigned for this environment. |
827
+ | `selection_id` | [`CardUuid`](schemas.md#carduuid) | Yes | format uuid | Previously approved historical selection. |
828
+
829
+
830
+ ## IntentCancelInput
831
+
832
+ | Field | Type | Required | Constraints | Meaning |
833
+ | --- | --- | --- | --- | --- |
834
+ | `intent_token` | string | Yes | — | Signed intent token issued by Facto for this connect intent. |
835
+
836
+
837
+ ## IntentCancelled
838
+
839
+ | Field | Type | Required | Constraints | Meaning |
840
+ | --- | --- | --- | --- | --- |
841
+ | `id` | [`ConnectIntentId`](schemas.md#connectintentid) | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
842
+ | `status` | string | Yes | equals `cancelled` | Reported status; interpret in the context of this response. |
843
+
844
+
845
+ ## IntentCardItem
846
+
847
+ | Field | Type | Required | Constraints | Meaning |
848
+ | --- | --- | --- | --- | --- |
849
+ | `binding_id` | [`CardBindingId`](schemas.md#cardbindingid) | Yes | pattern `^cb_[A-Za-z0-9_-]{16,}$` | Card binding identifier. |
850
+ | `card` | [`CardDisplayFacts`](schemas.md#carddisplayfacts) | Yes | — | Card display metadata. |
851
+ | `status` | string | Yes | one of `active`, `revoked` | Reported status; interpret in the context of this response. |
852
+
853
+
854
+ ## IntentCardList
855
+
856
+ | Field | Type | Required | Constraints | Meaning |
857
+ | --- | --- | --- | --- | --- |
858
+ | `cards` | array | Yes | items: [`IntentCardItem`](schemas.md#intentcarditem) | Card set for this intent. |
859
+ | `id` | [`ConnectIntentId`](schemas.md#connectintentid) | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
860
+ | `revision` | [`ConnectIntentDigest`](schemas.md#connectintentdigest) | Yes | pattern `^sha256:[a-fA-F0-9]{64}$` | Optimistic concurrency revision. |
861
+
862
+
863
+ ## IntentCardsReplaced
864
+
865
+ | Field | Type | Required | Constraints | Meaning |
866
+ | --- | --- | --- | --- | --- |
867
+ | `added_binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Binding IDs created by this replacement. |
868
+ | `id` | [`ConnectIntentId`](schemas.md#connectintentid) | Yes | pattern `^cint_[A-Za-z0-9_-]{16,}$` | Resource identifier. |
869
+ | `kept_binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Binding IDs preserved unchanged. |
870
+ | `removed_binding_ids` | array | Yes | items: [`CardBindingId`](schemas.md#cardbindingid) | Binding IDs revoked by this replacement. |
871
+ | `revision` | [`ConnectIntentDigest`](schemas.md#connectintentdigest) | Yes | pattern `^sha256:[a-fA-F0-9]{64}$` | Optimistic concurrency revision. |
872
+ | `status` | string | Yes | one of `applied`, `no_change` | Reported status; interpret in the context of this response. |
873
+
874
+
875
+ ## IntentCardsReplaceInput
876
+
877
+ | Field | Type | Required | Constraints | Meaning |
878
+ | --- | --- | --- | --- | --- |
879
+ | `approval_id` | string | Yes | min length 1; max length 255 | Partner approval identifier for the card replacement. |
880
+ | `approval_sha256` | string | Yes | pattern `^[a-f0-9]{64}$` | Lowercase SHA-256 digest of the approved payload. |
881
+ | `cards` | array | Yes | max items 50; items: [`TargetCardInput`](schemas.md#targetcardinput) | Card set for this intent. |
882
+ | `external_account_id` | one of the variants below | No | — | Opaque partner account identifier. |
883
+ | `intent_token` | string | Yes | — | Signed intent token issued by Facto for this connect intent. |
884
+ | `revision` | [`ConnectIntentDigest`](schemas.md#connectintentdigest) | Yes | pattern `^sha256:[a-fA-F0-9]{64}$` | Optimistic concurrency revision. |
885
+
886
+
887
+ **external_account_id variants**
888
+
889
+ #### Variant 1
890
+
891
+ Type: string. Constraints: min length 1; max length 512.
892
+
893
+
894
+ #### Variant 2
895
+
896
+ Type: null. Constraints: —.
897
+
898
+
899
+ ## ProgramConnectionId
900
+
901
+ Type: string. Constraints: pattern `^pconn_[A-Za-z0-9_-]{16,}$`.
902
+
903
+
904
+ ## ProviderProofAccepted
905
+
906
+ | Field | Type | Required | Constraints | Meaning |
907
+ | --- | --- | --- | --- | --- |
908
+ | `binding_session_id` | [`BindingSessionId`](schemas.md#bindingsessionid) | Yes | pattern `^cbs_[A-Za-z0-9_-]{16,}$` | Binding session identifier. |
909
+ | `proof_received_at` | [`CardTimestamp`](schemas.md#cardtimestamp) | Yes | format date-time | Timestamp when Facto durably accepted the provider proof. |
910
+ | `status` | string | Yes | equals `consent_pending` | Reported status; interpret in the context of this response. |
911
+
912
+
913
+ ## ProviderProofSubmitPayload
914
+
915
+ | Field | Type | Required | Constraints | Meaning |
916
+ | --- | --- | --- | --- | --- |
917
+ | `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. |
918
+ | `proof_format` | string | Yes | equals `compact-jws` | Format of the submitted provider proof (compact-jws). |
919
+
920
+
921
+ ## SupplierTransactionRefLookup
922
+
923
+ | Field | Type | Required | Constraints | Meaning |
924
+ | --- | --- | --- | --- | --- |
925
+ | `by` | string | Yes | equals `supplier_transaction_id` | Selects the lookup identity. |
926
+ | `fact_type` | [`AuthorizationOperationType`](schemas.md#authorizationoperationtype) | No | one of `authorization_requested`, `authorization_updated`, `clearing`, `reversal`, `refund`, `chargeback`, `settlement` | Lifecycle fact kind. |
927
+ | `mapping_revision` | string | Yes | min length 1; max length 255 | Original mapping revision. |
928
+ | `resource_version` | string | Yes | min length 1; max length 255 | Version identifying this operation within its lineage. |
929
+ | `supplier_transaction_id` | string | Yes | min length 1; max length 256 | Partner transaction identifier for this operation. |
930
+
931
+
932
+ ## SynchronousAuthorizationApproved
933
+
934
+ | Field | Type | Required | Constraints | Meaning |
935
+ | --- | --- | --- | --- | --- |
936
+ | `charge_id` | string | Yes | — | Public charge identifier. |
937
+ | `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
938
+ | `decided_at` | string | Yes | format date-time | Time at which a decision was recorded. |
939
+ | `decision` | string | Yes | equals `approved` | Synchronous decision. |
940
+ | `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
941
+ | `status` | string | Yes | equals `approved` | Reported status; interpret in the context of this response. |
942
+
943
+
944
+ ## SynchronousAuthorizationDeclined
945
+
946
+ | Field | Type | Required | Constraints | Meaning |
947
+ | --- | --- | --- | --- | --- |
948
+ | `deadline_at` | string | Yes | format date-time | Effective decision deadline. |
949
+ | `decided_at` | string | Yes | format date-time | Time at which a decision was recorded. |
950
+ | `decision` | string | Yes | one of `declined`, `self_reversed_timeout` | Synchronous decision. |
951
+ | `decision_id` | string | Yes | format uuid | Synchronous decision identifier. |
952
+ | `error` | string | Yes | — | Machine-readable error code. |
953
+ | `message` | string | Yes | — | Human-readable explanation. |
954
+ | `request_id` | string | Yes | — | Request correlation identifier. |
955
+
956
+
957
+ ## TargetCardInput
958
+
959
+ | Field | Type | Required | Constraints | Meaning |
960
+ | --- | --- | --- | --- | --- |
961
+ | `external_card_id` | string | Yes | min length 1; max length 255 | Opaque card identifier assigned by the partner. |
962
+ | `last4` | one of the variants below | No | — | Last four card digits, when available. |
963
+ | `network` | one of the variants below | No | — | Card network, when available. |
964
+ | `type` | one of the variants below | No | — | Card or change type. |
965
+
966
+
967
+ **last4 variants**
968
+
969
+ #### Variant 1
970
+
971
+ Type: string. Constraints: pattern `^[0-9]{4}$`.
972
+
973
+
974
+ #### Variant 2
975
+
976
+ Type: null. Constraints: —.
977
+
978
+
979
+ **network variants**
980
+
981
+ #### Variant 1
982
+
983
+ Type: string. Constraints: min length 1; max length 40.
984
+
985
+
986
+ #### Variant 2
987
+
988
+ Type: null. Constraints: —.
989
+
990
+
991
+ **type variants**
992
+
993
+ #### Variant 1
994
+
995
+ Type: string. Constraints: one of `virtual`, `physical`, `unknown`.
996
+
997
+
998
+ #### Variant 2
999
+
1000
+ Type: null. Constraints: —.
1001
+