@facto-to/card 0.0.0-stage → 0.0.1-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +63 -2
- package/dist/card-inbox-DzsHFRPT.d.cts +312 -0
- package/dist/card-inbox-DzsHFRPT.d.ts +312 -0
- package/dist/chunk-KBS2PWM4.js +2 -0
- package/dist/cli/index.js +6 -0
- package/dist/docs/README.md +9 -0
- package/dist/docs/authentication.md +96 -0
- package/dist/docs/authorization-binding.md +182 -0
- package/dist/docs/authorizations.md +182 -0
- package/dist/docs/concepts.md +36 -0
- package/dist/docs/deliveries.md +170 -0
- package/dist/docs/errors.md +100 -0
- package/dist/docs/getting-access.md +56 -0
- package/dist/docs/idempotency.md +78 -0
- package/dist/docs/integration-checklist.md +15 -0
- package/dist/docs/integration.zh.md +59 -0
- package/dist/docs/interlace-adapter-v1.md +87 -0
- package/dist/docs/interlace-adapter-v1.zh.md +87 -0
- package/dist/docs/not-yet-available.md +13 -0
- package/dist/docs/quickstart.md +126 -0
- package/dist/docs/reconciliation.md +86 -0
- package/dist/docs/reference/api.md +2541 -0
- package/dist/docs/reference/events.md +639 -0
- package/dist/docs/reference/schemas.json +6603 -0
- package/dist/docs/reference/schemas.md +1001 -0
- package/dist/docs/simulator.md +235 -0
- package/dist/docs/versioning.md +9 -0
- package/dist/index.cjs +3 -0
- package/dist/index.d.cts +987 -0
- package/dist/index.d.ts +987 -0
- package/dist/index.js +2 -0
- package/dist/source/build.mjs +5 -0
- package/dist/source/package.json +16 -0
- package/dist/source/src/connect/cli/deliveries.ts +48 -0
- package/dist/source/src/connect/cli/index.ts +57 -0
- package/dist/source/src/connect/server/card-binding-assertion.ts +312 -0
- package/dist/source/src/connect/server/card-client.ts +1018 -0
- package/dist/source/src/connect/server/card-delivery.ts +301 -0
- package/dist/source/src/connect/server/card-events.ts +473 -0
- package/dist/source/src/connect/server/card-idempotency.ts +27 -0
- package/dist/source/src/connect/server/card-inbox.ts +82 -0
- package/dist/source/src/connect/server/card-intent-token.ts +588 -0
- package/dist/source/src/connect/server/card-polling.ts +69 -0
- package/dist/source/src/connect/server/card-signing.ts +115 -0
- package/dist/source/src/connect/server/card-transport.ts +282 -0
- package/dist/source/src/connect/server/errors.ts +280 -0
- package/dist/source/src/connect/server/fixtures/engine/card-events.synthetic.ts +84 -0
- package/dist/source/src/connect/server/retry-after.ts +12 -0
- package/dist/source/src/connect/testing/card-inbox.ts +124 -0
- package/dist/source/src/connect/testing/card-scenarios.ts +243 -0
- package/dist/source/src/connect/testing/card-simulator-vectors.ts +262 -0
- package/dist/source/src/connect/testing/card-simulator.ts +531 -0
- package/dist/source/src/connect/testing/interlace-card-transactions.ts +704 -0
- package/dist/source/src/connect/testing/pure-sha256.ts +123 -0
- package/dist/source/src/connect/wire.d.ts +544 -0
- package/dist/source/src/index.ts +163 -0
- package/dist/source/src/testing-browser.ts +24 -0
- package/dist/source/src/testing.ts +26 -0
- package/dist/source/tsconfig.json +20 -0
- package/dist/testing-browser.d.ts +220 -0
- package/dist/testing-browser.js +5 -0
- package/dist/testing.cjs +6 -0
- package/dist/testing.d.cts +199 -0
- package/dist/testing.d.ts +199 -0
- package/dist/testing.js +5 -0
- package/package.json +60 -4
|
@@ -0,0 +1,639 @@
|
|
|
1
|
+
# Card delivery event catalog
|
|
2
|
+
|
|
3
|
+
Find each current Envelope v2 event kind, its envelope and payload fields, and a synthetic example below. Authenticate the original bytes before decoding.
|
|
4
|
+
|
|
5
|
+
## card.binding.linked
|
|
6
|
+
|
|
7
|
+
A card binding is linked.
|
|
8
|
+
|
|
9
|
+
| Field | Type | Presence | Meaning |
|
|
10
|
+
| --- | --- | --- | --- |
|
|
11
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
12
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
13
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
14
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
15
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
16
|
+
| `connection_sequence` | number or null | Required | Per-connection sequence, when available. |
|
|
17
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
18
|
+
| `binding_id` | string | Required | Card binding identifier. |
|
|
19
|
+
| `binding_revision` | number | Required | Card binding revision. |
|
|
20
|
+
| `event_kind` | string | Required | Event kind. |
|
|
21
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
22
|
+
| `data.binding_id` | string | Required | Card binding identifier. |
|
|
23
|
+
| `data.intent_id` | string or null | Required | Connect intent identifier, when available. |
|
|
24
|
+
| `data.external_card_id` | string | Required | Opaque card identifier assigned by the partner. |
|
|
25
|
+
| `data.subject_link_id` | string | Required | Subject link identifier. |
|
|
26
|
+
| `data.card` | object | Required | Card display metadata. |
|
|
27
|
+
| `data.approved_scopes` | array | Required | Scopes approved for this binding. |
|
|
28
|
+
| `data.consent_revision` | string | Required | Consent revision carried by the binding. |
|
|
29
|
+
| `data.ownership_transfer` | boolean | May be omitted | Whether this link accompanies an ownership transfer. |
|
|
30
|
+
| `data.previous_binding_id` | string | May be omitted | Previous binding identifier. |
|
|
31
|
+
|
|
32
|
+
### Example
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"envelope_version": 2,
|
|
37
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
38
|
+
"environment": "dev",
|
|
39
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
40
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
41
|
+
"connection_sequence": 1,
|
|
42
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
43
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
44
|
+
"binding_revision": 1,
|
|
45
|
+
"event_kind": "card.binding.linked",
|
|
46
|
+
"data": {
|
|
47
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
48
|
+
"intent_id": null,
|
|
49
|
+
"external_card_id": "scp_card_0001",
|
|
50
|
+
"subject_link_id": "csl_synthetic",
|
|
51
|
+
"card": {
|
|
52
|
+
"network": "Visa",
|
|
53
|
+
"type": "virtual",
|
|
54
|
+
"last4": "4242"
|
|
55
|
+
},
|
|
56
|
+
"approved_scopes": [
|
|
57
|
+
"card.metadata.view"
|
|
58
|
+
],
|
|
59
|
+
"consent_revision": "synthetic"
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Nullable-card example
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"envelope_version": 2,
|
|
69
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
70
|
+
"environment": "dev",
|
|
71
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
72
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
73
|
+
"connection_sequence": null,
|
|
74
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
75
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
76
|
+
"binding_revision": 1,
|
|
77
|
+
"event_kind": "card.binding.linked",
|
|
78
|
+
"data": {
|
|
79
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
80
|
+
"intent_id": "cint_01JZ9X8K4M2V7R5T3N6P8Q0W2Y",
|
|
81
|
+
"external_card_id": "scp_card_0001",
|
|
82
|
+
"subject_link_id": "csl_synthetic",
|
|
83
|
+
"card": {
|
|
84
|
+
"network": null,
|
|
85
|
+
"type": null,
|
|
86
|
+
"last4": null
|
|
87
|
+
},
|
|
88
|
+
"approved_scopes": [
|
|
89
|
+
"card.metadata.view"
|
|
90
|
+
],
|
|
91
|
+
"consent_revision": "synthetic"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## card.binding.relinked
|
|
97
|
+
|
|
98
|
+
A card binding is linked again.
|
|
99
|
+
|
|
100
|
+
| Field | Type | Presence | Meaning |
|
|
101
|
+
| --- | --- | --- | --- |
|
|
102
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
103
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
104
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
105
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
106
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
107
|
+
| `connection_sequence` | number or null | Required | Per-connection sequence, when available. |
|
|
108
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
109
|
+
| `binding_id` | string | Required | Card binding identifier. |
|
|
110
|
+
| `binding_revision` | number | Required | Card binding revision. |
|
|
111
|
+
| `event_kind` | string | Required | Event kind. |
|
|
112
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
113
|
+
| `data.binding_id` | string | Required | Card binding identifier. |
|
|
114
|
+
| `data.intent_id` | string or null | Required | Connect intent identifier, when available. |
|
|
115
|
+
| `data.external_card_id` | string | Required | Opaque card identifier assigned by the partner. |
|
|
116
|
+
| `data.subject_link_id` | string | Required | Subject link identifier. |
|
|
117
|
+
| `data.card` | object | Required | Card display metadata. |
|
|
118
|
+
| `data.approved_scopes` | array | Required | Scopes approved for this binding. |
|
|
119
|
+
| `data.consent_revision` | string | Required | Consent revision carried by the binding. |
|
|
120
|
+
| `data.ownership_transfer` | boolean | May be omitted | Whether this link accompanies an ownership transfer. |
|
|
121
|
+
| `data.previous_binding_id` | string | May be omitted | Previous binding identifier. |
|
|
122
|
+
|
|
123
|
+
### Example
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"envelope_version": 2,
|
|
128
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
129
|
+
"environment": "dev",
|
|
130
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
131
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
132
|
+
"connection_sequence": 1,
|
|
133
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
134
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
135
|
+
"binding_revision": 1,
|
|
136
|
+
"event_kind": "card.binding.relinked",
|
|
137
|
+
"data": {
|
|
138
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
139
|
+
"intent_id": null,
|
|
140
|
+
"external_card_id": "scp_card_0001",
|
|
141
|
+
"subject_link_id": "csl_synthetic",
|
|
142
|
+
"card": {
|
|
143
|
+
"network": "Visa",
|
|
144
|
+
"type": "virtual",
|
|
145
|
+
"last4": "4242"
|
|
146
|
+
},
|
|
147
|
+
"approved_scopes": [
|
|
148
|
+
"card.metadata.view"
|
|
149
|
+
],
|
|
150
|
+
"consent_revision": "synthetic"
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## card.binding.revoked
|
|
156
|
+
|
|
157
|
+
A card binding is revoked.
|
|
158
|
+
|
|
159
|
+
| Field | Type | Presence | Meaning |
|
|
160
|
+
| --- | --- | --- | --- |
|
|
161
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
162
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
163
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
164
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
165
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
166
|
+
| `connection_sequence` | number or null | Required | Per-connection sequence, when available. |
|
|
167
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
168
|
+
| `binding_id` | string | Required | Card binding identifier. |
|
|
169
|
+
| `binding_revision` | number | Required | Card binding revision. |
|
|
170
|
+
| `event_kind` | string | Required | Event kind. |
|
|
171
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
172
|
+
| `data.binding_id` | string | Required | Card binding identifier. |
|
|
173
|
+
| `data.binding_revision` | number | Required | Card binding revision. |
|
|
174
|
+
| `data.external_card_id` | string | Required | Opaque card identifier assigned by the partner. |
|
|
175
|
+
| `data.card` | object | Required | Card display metadata. |
|
|
176
|
+
| `data.revocation_source` | string | May be omitted | Source of the revocation. |
|
|
177
|
+
| `data.reason_code` | string | May be omitted | Reason reported for the event. |
|
|
178
|
+
| `data.payable_projections_closed` | number | Required | Number of payable projections closed. |
|
|
179
|
+
| `data.routes_detached` | number | Required | Number of payment routes detached. |
|
|
180
|
+
| `data.intent_id` | string | May be omitted | Connect intent identifier, when available. |
|
|
181
|
+
|
|
182
|
+
At least one of `data.reason_code` and `data.revocation_source` is required.
|
|
183
|
+
|
|
184
|
+
### Example
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"envelope_version": 2,
|
|
189
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
190
|
+
"environment": "dev",
|
|
191
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
192
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
193
|
+
"connection_sequence": 1,
|
|
194
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
195
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
196
|
+
"binding_revision": 1,
|
|
197
|
+
"event_kind": "card.binding.revoked",
|
|
198
|
+
"data": {
|
|
199
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
200
|
+
"binding_revision": 1,
|
|
201
|
+
"external_card_id": "scp_card_0001",
|
|
202
|
+
"card": {
|
|
203
|
+
"network": "Visa",
|
|
204
|
+
"type": "virtual",
|
|
205
|
+
"last4": "4242"
|
|
206
|
+
},
|
|
207
|
+
"revocation_source": "user_portfolio",
|
|
208
|
+
"reason_code": "user_requested",
|
|
209
|
+
"payable_projections_closed": 0,
|
|
210
|
+
"routes_detached": 0
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## card.binding.route_changed
|
|
216
|
+
|
|
217
|
+
A payment route association changes.
|
|
218
|
+
|
|
219
|
+
| Field | Type | Presence | Meaning |
|
|
220
|
+
| --- | --- | --- | --- |
|
|
221
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
222
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
223
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
224
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
225
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
226
|
+
| `connection_sequence` | number or null | Required | Per-connection sequence, when available. |
|
|
227
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
228
|
+
| `binding_id` | string | Required | Card binding identifier. |
|
|
229
|
+
| `binding_revision` | number | Required | Card binding revision. |
|
|
230
|
+
| `event_kind` | string | Required | Event kind. |
|
|
231
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
232
|
+
| `data.binding_id` | string | Required | Card binding identifier. |
|
|
233
|
+
| `data.binding_revision` | number | Required | Card binding revision. |
|
|
234
|
+
| `data.association_status` | string | Required | Current payment route association status. |
|
|
235
|
+
|
|
236
|
+
### Example
|
|
237
|
+
|
|
238
|
+
```json
|
|
239
|
+
{
|
|
240
|
+
"envelope_version": 2,
|
|
241
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
242
|
+
"environment": "dev",
|
|
243
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
244
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
245
|
+
"connection_sequence": 1,
|
|
246
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
247
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
248
|
+
"binding_revision": 1,
|
|
249
|
+
"event_kind": "card.binding.route_changed",
|
|
250
|
+
"data": {
|
|
251
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
252
|
+
"binding_revision": 1,
|
|
253
|
+
"association_status": "associated"
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## card.binding.limits_changed
|
|
259
|
+
|
|
260
|
+
Card spending limits change.
|
|
261
|
+
|
|
262
|
+
| Field | Type | Presence | Meaning |
|
|
263
|
+
| --- | --- | --- | --- |
|
|
264
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
265
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
266
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
267
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
268
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
269
|
+
| `connection_sequence` | number or null | Required | Per-connection sequence, when available. |
|
|
270
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
271
|
+
| `binding_id` | string | Required | Card binding identifier. |
|
|
272
|
+
| `binding_revision` | number | Required | Card binding revision. |
|
|
273
|
+
| `event_kind` | string | Required | Event kind. |
|
|
274
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
275
|
+
| `data.binding_id` | string | Required | Card binding identifier. |
|
|
276
|
+
| `data.binding_revision` | number | Required | Card binding revision. |
|
|
277
|
+
| `data.per_tx_limit` | string | Required | Per-transaction spend limit in six-decimal USDC. |
|
|
278
|
+
| `data.period_limit` | string | Required | Spend limit for the period. |
|
|
279
|
+
| `data.period` | string | Required | Spend limit period. |
|
|
280
|
+
| `data.expires_at` | string or null | Required | Expiration timestamp. |
|
|
281
|
+
|
|
282
|
+
### Example
|
|
283
|
+
|
|
284
|
+
```json
|
|
285
|
+
{
|
|
286
|
+
"envelope_version": 2,
|
|
287
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
288
|
+
"environment": "dev",
|
|
289
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
290
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
291
|
+
"connection_sequence": 1,
|
|
292
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
293
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
294
|
+
"binding_revision": 1,
|
|
295
|
+
"event_kind": "card.binding.limits_changed",
|
|
296
|
+
"data": {
|
|
297
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
298
|
+
"binding_revision": 1,
|
|
299
|
+
"per_tx_limit": "1.000000",
|
|
300
|
+
"period_limit": "2.000000",
|
|
301
|
+
"period": "monthly",
|
|
302
|
+
"expires_at": "2027-01-01T00:00:00Z"
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## card.binding.ownership_transferred
|
|
308
|
+
|
|
309
|
+
A card binding ownership transfer is recorded.
|
|
310
|
+
|
|
311
|
+
| Field | Type | Presence | Meaning |
|
|
312
|
+
| --- | --- | --- | --- |
|
|
313
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
314
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
315
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
316
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
317
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
318
|
+
| `connection_sequence` | number or null | Required | Per-connection sequence, when available. |
|
|
319
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
320
|
+
| `binding_id` | string | Required | Card binding identifier. |
|
|
321
|
+
| `binding_revision` | number | Required | Card binding revision. |
|
|
322
|
+
| `event_kind` | string | Required | Event kind. |
|
|
323
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
324
|
+
| `data.previous_binding_id` | string | Required | Previous binding identifier. |
|
|
325
|
+
| `data.new_binding_id` | string | Required | New binding identifier. |
|
|
326
|
+
| `data.external_card_id` | string | Required | Opaque card identifier assigned by the partner. |
|
|
327
|
+
| `data.card` | object | Required | Card display metadata. |
|
|
328
|
+
| `data.transferred_at` | string | Required | Time of the reported ownership transfer. |
|
|
329
|
+
|
|
330
|
+
### Example
|
|
331
|
+
|
|
332
|
+
```json
|
|
333
|
+
{
|
|
334
|
+
"envelope_version": 2,
|
|
335
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
336
|
+
"environment": "dev",
|
|
337
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
338
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
339
|
+
"connection_sequence": 1,
|
|
340
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
341
|
+
"binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
342
|
+
"binding_revision": 1,
|
|
343
|
+
"event_kind": "card.binding.ownership_transferred",
|
|
344
|
+
"data": {
|
|
345
|
+
"previous_binding_id": "cb_01JZ9X8K4M2V7R5T3N6P8Q0W2Z",
|
|
346
|
+
"new_binding_id": "cb_new0000000000001",
|
|
347
|
+
"external_card_id": "scp_card_0001",
|
|
348
|
+
"card": {
|
|
349
|
+
"network": "Visa",
|
|
350
|
+
"type": "virtual",
|
|
351
|
+
"last4": "4242"
|
|
352
|
+
},
|
|
353
|
+
"transferred_at": "2026-11-18T00:00:00Z"
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
## card.charge.finalized
|
|
359
|
+
|
|
360
|
+
A charge reaches a final execution outcome.
|
|
361
|
+
|
|
362
|
+
| Field | Type | Presence | Meaning |
|
|
363
|
+
| --- | --- | --- | --- |
|
|
364
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
365
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
366
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
367
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
368
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
369
|
+
| `connection_sequence` | number | Required | Per-connection sequence, when available. |
|
|
370
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
371
|
+
| `event_kind` | string | Required | Event kind. |
|
|
372
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
373
|
+
| `data.authorization_revision` | number | Required | Authorization projection revision. |
|
|
374
|
+
| `data.operation_type` | string | Required | Authorization or lifecycle operation kind. |
|
|
375
|
+
| `data.resource_version` | string | Required | Version identifying this operation within its lineage. |
|
|
376
|
+
| `data.external_authorization_id` | string | Required | Stable identifier for the authorization lineage. |
|
|
377
|
+
| `data.mapping_revision` | string | Required | Original mapping revision. |
|
|
378
|
+
| `data.final_receipt` | object | Required | Terminal execution receipt. |
|
|
379
|
+
| `data.final_receipt.receipt_event_id` | string | Required | Final receipt event identifier. |
|
|
380
|
+
| `data.final_receipt.charge_id` | string | Required | Public charge identifier. |
|
|
381
|
+
| `data.final_receipt.external_authorization_id` | string | Required | Stable identifier for the authorization lineage. |
|
|
382
|
+
| `data.final_receipt.mapping_revision` | string | Required | Original mapping revision. |
|
|
383
|
+
| `data.final_receipt.operation_type` | string | Required | Authorization or lifecycle operation kind. |
|
|
384
|
+
| `data.final_receipt.resource_version` | string | Required | Version identifying this operation within its lineage. |
|
|
385
|
+
| `data.final_receipt.execution_outcome` | string | Required | Terminal execution outcome. |
|
|
386
|
+
| `data.final_receipt.terminal_action` | string | Required | Terminal execution action. |
|
|
387
|
+
| `data.final_receipt.finalized_at` | string | Required | Time execution reached finality. |
|
|
388
|
+
| `data.final_receipt.facts_at_finality` | array | Required | Facts observed at execution finality. |
|
|
389
|
+
| `data.final_receipt.facts_at_finality[].kind` | string | Required | Kind of event or fact. |
|
|
390
|
+
| `data.final_receipt.facts_at_finality[].state` | string | Required | Observed state. |
|
|
391
|
+
| `data.final_receipt.facts_at_finality[].recorded_at` | string | Required | Time the fact was recorded. |
|
|
392
|
+
| `data.final_receipt.facts_at_finality[].source_system` | string | Required | System that reported the fact. |
|
|
393
|
+
| `data.final_receipt.facts_at_finality[].observed_at` | string | May be omitted | Time of the returned observation. |
|
|
394
|
+
| `data.final_receipt.facts_at_finality[].safe_code` | string | May be omitted | Bounded machine-readable fact code, when available. |
|
|
395
|
+
|
|
396
|
+
### Example
|
|
397
|
+
|
|
398
|
+
```json
|
|
399
|
+
{
|
|
400
|
+
"envelope_version": 2,
|
|
401
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
402
|
+
"environment": "dev",
|
|
403
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
404
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
405
|
+
"connection_sequence": 1,
|
|
406
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
407
|
+
"event_kind": "card.charge.finalized",
|
|
408
|
+
"data": {
|
|
409
|
+
"authorization_revision": 1,
|
|
410
|
+
"operation_type": "authorization_requested",
|
|
411
|
+
"resource_version": "v1",
|
|
412
|
+
"external_authorization_id": "synthetic-auth",
|
|
413
|
+
"mapping_revision": "synthetic-mapping",
|
|
414
|
+
"final_receipt": {
|
|
415
|
+
"receipt_event_id": "00000000-0000-4000-8000-000000000001",
|
|
416
|
+
"charge_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
|
|
417
|
+
"external_authorization_id": "synthetic-auth",
|
|
418
|
+
"mapping_revision": "synthetic-mapping",
|
|
419
|
+
"operation_type": "authorization_requested",
|
|
420
|
+
"resource_version": "v1",
|
|
421
|
+
"execution_outcome": "succeeded",
|
|
422
|
+
"terminal_action": "releaseFor",
|
|
423
|
+
"finalized_at": "2026-11-18T00:00:00Z",
|
|
424
|
+
"facts_at_finality": [
|
|
425
|
+
{
|
|
426
|
+
"kind": "facto_admission",
|
|
427
|
+
"state": "confirmed",
|
|
428
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
429
|
+
"source_system": "facto",
|
|
430
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
431
|
+
},
|
|
432
|
+
{
|
|
433
|
+
"kind": "durable_commit",
|
|
434
|
+
"state": "confirmed",
|
|
435
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
436
|
+
"source_system": "facto",
|
|
437
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
438
|
+
},
|
|
439
|
+
{
|
|
440
|
+
"kind": "provider_authorization",
|
|
441
|
+
"state": "unobserved",
|
|
442
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
443
|
+
"source_system": "provider"
|
|
444
|
+
},
|
|
445
|
+
{
|
|
446
|
+
"kind": "chain_finality",
|
|
447
|
+
"state": "confirmed",
|
|
448
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
449
|
+
"source_system": "chain",
|
|
450
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
451
|
+
},
|
|
452
|
+
{
|
|
453
|
+
"kind": "provider_settlement",
|
|
454
|
+
"state": "unobserved",
|
|
455
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
456
|
+
"source_system": "provider"
|
|
457
|
+
}
|
|
458
|
+
]
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
}
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
## card.charge.facts_updated
|
|
465
|
+
|
|
466
|
+
Later facts for a finalized charge are recorded.
|
|
467
|
+
|
|
468
|
+
| Field | Type | Presence | Meaning |
|
|
469
|
+
| --- | --- | --- | --- |
|
|
470
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
471
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
472
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
473
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
474
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
475
|
+
| `connection_sequence` | number | Required | Per-connection sequence, when available. |
|
|
476
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
477
|
+
| `event_kind` | string | Required | Event kind. |
|
|
478
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
479
|
+
| `data.authorization_revision` | number | Required | Authorization projection revision. |
|
|
480
|
+
| `data.operation_type` | string | Required | Authorization or lifecycle operation kind. |
|
|
481
|
+
| `data.resource_version` | string | Required | Version identifying this operation within its lineage. |
|
|
482
|
+
| `data.external_authorization_id` | string | Required | Stable identifier for the authorization lineage. |
|
|
483
|
+
| `data.mapping_revision` | string | Required | Original mapping revision. |
|
|
484
|
+
| `data.charge_id` | string | Required | Public charge identifier. |
|
|
485
|
+
| `data.final_receipt_event_id` | string | Required | Event identifier of the final receipt. |
|
|
486
|
+
| `data.previous_authorization_revision` | number | Required | Prior authorization projection revision. |
|
|
487
|
+
| `data.facts` | array | Required | Current observed facts. |
|
|
488
|
+
| `data.facts[].kind` | string | Required | Kind of event or fact. |
|
|
489
|
+
| `data.facts[].state` | string | Required | Observed state. |
|
|
490
|
+
| `data.facts[].recorded_at` | string | Required | Time the fact was recorded. |
|
|
491
|
+
| `data.facts[].source_system` | string | Required | System that reported the fact. |
|
|
492
|
+
| `data.facts[].observed_at` | string | May be omitted | Time of the returned observation. |
|
|
493
|
+
| `data.facts[].safe_code` | string | May be omitted | Bounded machine-readable fact code, when available. |
|
|
494
|
+
|
|
495
|
+
### Example
|
|
496
|
+
|
|
497
|
+
```json
|
|
498
|
+
{
|
|
499
|
+
"envelope_version": 2,
|
|
500
|
+
"event_id": "00000000-0000-4000-8000-000000000002",
|
|
501
|
+
"environment": "dev",
|
|
502
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
503
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
504
|
+
"connection_sequence": 2,
|
|
505
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
506
|
+
"event_kind": "card.charge.facts_updated",
|
|
507
|
+
"data": {
|
|
508
|
+
"authorization_revision": 2,
|
|
509
|
+
"operation_type": "authorization_requested",
|
|
510
|
+
"resource_version": "v1",
|
|
511
|
+
"external_authorization_id": "synthetic-auth",
|
|
512
|
+
"mapping_revision": "synthetic-mapping",
|
|
513
|
+
"charge_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
|
|
514
|
+
"final_receipt_event_id": "00000000-0000-4000-8000-000000000001",
|
|
515
|
+
"previous_authorization_revision": 1,
|
|
516
|
+
"facts": [
|
|
517
|
+
{
|
|
518
|
+
"kind": "facto_admission",
|
|
519
|
+
"state": "confirmed",
|
|
520
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
521
|
+
"source_system": "facto",
|
|
522
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
523
|
+
},
|
|
524
|
+
{
|
|
525
|
+
"kind": "durable_commit",
|
|
526
|
+
"state": "confirmed",
|
|
527
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
528
|
+
"source_system": "facto",
|
|
529
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
530
|
+
},
|
|
531
|
+
{
|
|
532
|
+
"kind": "provider_authorization",
|
|
533
|
+
"state": "confirmed",
|
|
534
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
535
|
+
"source_system": "provider",
|
|
536
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
537
|
+
},
|
|
538
|
+
{
|
|
539
|
+
"kind": "chain_finality",
|
|
540
|
+
"state": "confirmed",
|
|
541
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
542
|
+
"source_system": "chain",
|
|
543
|
+
"observed_at": "2026-11-18T00:00:00Z"
|
|
544
|
+
},
|
|
545
|
+
{
|
|
546
|
+
"kind": "provider_settlement",
|
|
547
|
+
"state": "unobserved",
|
|
548
|
+
"recorded_at": "2026-11-18T00:00:00Z",
|
|
549
|
+
"source_system": "provider"
|
|
550
|
+
}
|
|
551
|
+
]
|
|
552
|
+
}
|
|
553
|
+
}
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
## card.authorization.updated
|
|
557
|
+
|
|
558
|
+
An authorization progress summary and one change are recorded.
|
|
559
|
+
|
|
560
|
+
| Field | Type | Presence | Meaning |
|
|
561
|
+
| --- | --- | --- | --- |
|
|
562
|
+
| `envelope_version` | number | Required | Version of the event envelope. |
|
|
563
|
+
| `event_id` | string | Required | Delivery event identifier. |
|
|
564
|
+
| `environment` | string | Required | Environment of the operation or event. |
|
|
565
|
+
| `program_id` | string | Required | Program identifier assigned for this environment. |
|
|
566
|
+
| `origin_connection_id` | string | Required | Connection that originated the event or authorization. |
|
|
567
|
+
| `connection_sequence` | number | Required | Per-connection sequence, when available. |
|
|
568
|
+
| `occurred_at` | string | Required | Time when the event or authorization occurred. |
|
|
569
|
+
| `event_kind` | string | Required | Event kind. |
|
|
570
|
+
| `data` | object | Required | Kind-specific event payload. |
|
|
571
|
+
| `data.lifecycle_revision` | number | Required | Authorization lifecycle projection revision. |
|
|
572
|
+
| `data.operation_type` | string | Required | Authorization or lifecycle operation kind. |
|
|
573
|
+
| `data.resource_version` | string | Required | Version identifying this operation within its lineage. |
|
|
574
|
+
| `data.external_authorization_id` | string | Required | Stable identifier for the authorization lineage. |
|
|
575
|
+
| `data.mapping_revision` | string | Required | Original mapping revision. |
|
|
576
|
+
| `data.authorization` | object | Required | Authorization projection, when observed. |
|
|
577
|
+
| `data.charge` | string or null | Required | Event field. |
|
|
578
|
+
| `data.issuer` | object | Required | Event field. |
|
|
579
|
+
| `data.refunds` | object | Required | Event field. |
|
|
580
|
+
| `data.change` | object | Required | Event field. |
|
|
581
|
+
|
|
582
|
+
### Example
|
|
583
|
+
|
|
584
|
+
```json
|
|
585
|
+
{
|
|
586
|
+
"envelope_version": 2,
|
|
587
|
+
"event_id": "00000000-0000-4000-8000-000000000001",
|
|
588
|
+
"environment": "dev",
|
|
589
|
+
"program_id": "cprog_SYNTHETIC00000001",
|
|
590
|
+
"origin_connection_id": "pconn_SYNTHETIC00000001",
|
|
591
|
+
"connection_sequence": 1,
|
|
592
|
+
"occurred_at": "2026-11-18T00:00:00Z",
|
|
593
|
+
"event_kind": "card.authorization.updated",
|
|
594
|
+
"data": {
|
|
595
|
+
"lifecycle_revision": 1,
|
|
596
|
+
"operation_type": "authorization_requested",
|
|
597
|
+
"resource_version": "v1",
|
|
598
|
+
"external_authorization_id": "synthetic-auth",
|
|
599
|
+
"mapping_revision": "synthetic-mapping",
|
|
600
|
+
"authorization": {
|
|
601
|
+
"amount": "1.000000",
|
|
602
|
+
"currency": "USDC"
|
|
603
|
+
},
|
|
604
|
+
"charge": null,
|
|
605
|
+
"issuer": {
|
|
606
|
+
"state": "authorized",
|
|
607
|
+
"cleared_amount": "0.000000",
|
|
608
|
+
"reversed_amount": "0.000000",
|
|
609
|
+
"refunded_amount": "0.000000",
|
|
610
|
+
"entry_count": 0,
|
|
611
|
+
"unlinked_count": 0
|
|
612
|
+
},
|
|
613
|
+
"refunds": {
|
|
614
|
+
"case_count": 0,
|
|
615
|
+
"status_counts": {
|
|
616
|
+
"awaiting_charge_final": 0,
|
|
617
|
+
"awaiting_funds": 0,
|
|
618
|
+
"payable": 0,
|
|
619
|
+
"paid": 0,
|
|
620
|
+
"failed": 0,
|
|
621
|
+
"not_payable": 0
|
|
622
|
+
},
|
|
623
|
+
"total_amount": "0.000000",
|
|
624
|
+
"total_paid_amount": "0.000000",
|
|
625
|
+
"total_excess_amount": "0.000000"
|
|
626
|
+
},
|
|
627
|
+
"change": {
|
|
628
|
+
"type": "authorization.recorded",
|
|
629
|
+
"at": "2026-11-18T00:00:00Z"
|
|
630
|
+
}
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
<!-- event-type-schema-sha256: 3d4d1d072cb1275342229dd6b8516b716b12a9cd75301e834e2a3d9762ee3c83 -->
|
|
636
|
+
|
|
637
|
+
## Delivery authentication
|
|
638
|
+
|
|
639
|
+
See [deliveries](../deliveries.md) for the headers, signing input, verification and inbox handling.
|