@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,78 @@
|
|
|
1
|
+
# Idempotency
|
|
2
|
+
|
|
3
|
+
This page shows how to preserve a single operation across retries and avoid accidental duplicate actions.
|
|
4
|
+
|
|
5
|
+
## Where a key is required
|
|
6
|
+
|
|
7
|
+
The [API reference](reference/api.md) lists required headers per operation. Binding session creation, provider proof submission, session cancellation, authorization creation, subsequent fact submission, intent card replacement, and history replay require an explicit `Idempotency-Key` of 16–255 visible ASCII characters. On `POST /api/card/connect/sessions`, the optional `x-facto-card-selection: 1` header is bound into the idempotency digest alongside the request body bytes.
|
|
8
|
+
|
|
9
|
+
## Prepare and send
|
|
10
|
+
|
|
11
|
+
1. Derive or assign a stable key from identifiers that do not change between attempts. Do not use the current time, a delivery attempt or a new random retry value.
|
|
12
|
+
2. Persist the key and the exact original serialized body before sending. Preserve property order and encoding; Engine compares raw bytes.
|
|
13
|
+
3. Sign each attempt with a fresh nonce, while sending the original key and exactly the same body bytes.
|
|
14
|
+
4. If the outcome is unknown, retry the same operation or query its original identity. Do not create a new operation merely to retry.
|
|
15
|
+
|
|
16
|
+
These instructions cover Facto SDK requests. The [Interlace profile](interlace-adapter-v1.md) permits at most one supplier funds write and requires read-only recovery after an unknown response; generic SDK retries do not authorize resending it.
|
|
17
|
+
|
|
18
|
+
`deriveAuthorizationIdempotencyKey` is only for the original authorization (`fact_type: 'authorization_requested'`). Its result depends only on the program connection, authorization reference and supplier reference, not on the operation type or resource version, so using it for a later fact (clearing, reversal, refund, chargeback, settlement or an authorization update) would reuse the original authorization's key and fail with `integrity_conflict`. Assign each subsequent fact its own stable key, for example from its `resource_version`, and persist it with the fact's exact body.
|
|
19
|
+
|
|
20
|
+
The tested example derives the key using the program connection, authorization reference and supplier reference, then uses it for dispatch and lookup:
|
|
21
|
+
|
|
22
|
+
<!-- example:authorization -->
|
|
23
|
+
```typescript
|
|
24
|
+
import { deriveAuthorizationIdempotencyKey, pollAuthorization, type CardClient } from '@facto-to/card'
|
|
25
|
+
|
|
26
|
+
export async function authorizeAndReconcile(card: CardClient, input: {
|
|
27
|
+
connectionId: string
|
|
28
|
+
externalAuthorizationId: string
|
|
29
|
+
externalCardId: string
|
|
30
|
+
originalCredentialKeyId: string
|
|
31
|
+
supplierTransactionId: string
|
|
32
|
+
verificationTime: string
|
|
33
|
+
verificationEvidenceId: string
|
|
34
|
+
}, persistOriginal: (key: string, body: string) => Promise<void>) {
|
|
35
|
+
const authorization = {
|
|
36
|
+
external_card_id: input.externalCardId,
|
|
37
|
+
external_authorization_id: input.externalAuthorizationId,
|
|
38
|
+
supplier_transaction_id: input.supplierTransactionId,
|
|
39
|
+
amount: '10.00',
|
|
40
|
+
currency: 'USD' as const,
|
|
41
|
+
resource_version: 'authorization-v1',
|
|
42
|
+
mapping_revision: 'mapping-v1',
|
|
43
|
+
cardholder_verification: {
|
|
44
|
+
method: 'provider_attested' as const,
|
|
45
|
+
verified_at: input.verificationTime,
|
|
46
|
+
evidence_id: input.verificationEvidenceId,
|
|
47
|
+
},
|
|
48
|
+
}
|
|
49
|
+
const key = deriveAuthorizationIdempotencyKey({
|
|
50
|
+
connectionId: input.connectionId,
|
|
51
|
+
externalAuthorizationId: input.externalAuthorizationId,
|
|
52
|
+
supplierTransactionId: input.supplierTransactionId,
|
|
53
|
+
})
|
|
54
|
+
// The SDK appends program_id to these fields before JSON serialization.
|
|
55
|
+
const rawBody = JSON.stringify({ ...authorization, program_id: card.scope.programId })
|
|
56
|
+
await persistOriginal(key, rawBody)
|
|
57
|
+
const accepted = await card.authorizations.create(authorization, { idempotencyKey: key })
|
|
58
|
+
const original = { resource_version: authorization.resource_version, mapping_revision: authorization.mapping_revision }
|
|
59
|
+
const criteria = { by: 'external_authorization_id' as const, external_authorization_id: input.externalAuthorizationId, ...original }
|
|
60
|
+
const terminal = await pollAuthorization(card, criteria, { deadlineEpochMs: Date.now() + 30_000, intervalMs: 1_000, maxIntervalMs: 5_000, backoffFactor: 2 })
|
|
61
|
+
const byKey = await card.authorizations.lookup({ by: 'idempotency_key', idempotency_key: key, original_credential_key_id: input.originalCredentialKeyId })
|
|
62
|
+
const bySupplier = await card.authorizations.lookup({ by: 'supplier_transaction_id', supplier_transaction_id: input.supplierTransactionId, ...original })
|
|
63
|
+
const byCharge = await card.authorizations.lookup({ by: 'charge_id', charge_id: accepted.charge_id })
|
|
64
|
+
return { accepted, terminal, bySupplier, byKey, byCharge, key, authorization }
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
<!-- /example:authorization -->
|
|
68
|
+
|
|
69
|
+
## Reuse outcomes
|
|
70
|
+
|
|
71
|
+
| Attempt | Result and action |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| Same key, same body after an unknown outcome | Recover the same operation or query its status; never assume acceptance. |
|
|
74
|
+
| Same key, different bytes | `integrity_conflict`; even equivalent JSON with different whitespace can conflict. Determine the original operation before taking another action. |
|
|
75
|
+
| New key, same operation identity, different normalized content | `integrity_conflict`; changing the key does not create a new authorization identity. Some fields do not participate in normalization for certain requests, so do not rely on this conflict as a detector for every changed field. |
|
|
76
|
+
| After an explicit refusal | Do not depend on the result of resending the same key and body. Treat the refusal as final for this authorization. A later attempt is a new authorization with a new network authorization reference and a new key. |
|
|
77
|
+
|
|
78
|
+
The HMAC signature does not cover `Idempotency-Key`; Engine constrains its reuse through the idempotency record and exact body-byte comparison.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Integration checklist
|
|
2
|
+
|
|
3
|
+
Use this checklist to verify your implementation before requesting production access. The local tools exercise synthetic traffic; they cannot certify production eligibility.
|
|
4
|
+
|
|
5
|
+
- [ ] Register the callback and keys using [getting access](getting-access.md); record the separately received SHA-256 digest, SDK version and contract version, and agree the key compromise procedure.
|
|
6
|
+
- [ ] Verify exact delivery bytes, key scope and signature using [deliveries](deliveries.md); test duplicate security headers and unknown event kinds.
|
|
7
|
+
- [ ] Synchronize clocks and reject stale timestamps and reused nonces; run `expired_timestamp` and `nonce_replay` from [quickstart](quickstart.md).
|
|
8
|
+
- [ ] Keep the same request body and idempotency key for retries; run `authorization_replay` and `byte_integrity_conflict` and follow [idempotency](idempotency.md).
|
|
9
|
+
- [ ] Handle successful, explicit and unknown outcomes separately, including 429, 5xx, timeouts and 409 identity conflicts; run `retry_503`, `retry_after_429`, `explicit_402`, and read [errors](errors.md).
|
|
10
|
+
- [ ] Handle unknown event kinds conservatively and nullable card display fields without treating them as invalid; send `nullableCard` and review [events](reference/events.md).
|
|
11
|
+
- [ ] Test duplicate, out-of-order, sequence-gap and unsequenced deliveries without assuming contiguous delivery; test lease takeover and fenced effects; see [deliveries](deliveries.md).
|
|
12
|
+
- [ ] Treat unknown open status values conservatively and closed authorization outcomes as invalid; see [versioning](versioning.md).
|
|
13
|
+
- [ ] Exercise all four status lookups, reconciliation pagination and replay; see [authorizations](authorizations.md) and [reconciliation](reconciliation.md).
|
|
14
|
+
|
|
15
|
+
The delivery CLI reports HTTP responses only; it does not validate your business processing or provide an exactly-once guarantee.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Interlace 中文接入与结果回执
|
|
2
|
+
|
|
3
|
+
Facto 定义 [Adapter v1 规范](interlace-adapter-v1.zh.md)和验收判据,Interlace 实现适配并提交结果。规范不代表供应商已经支持,也不代表真实资金整链已经通过。[English profile](interlace-adapter-v1.md) 与中文规范等义。
|
|
4
|
+
|
|
5
|
+
## 安装与环境
|
|
6
|
+
|
|
7
|
+
需要 Node.js 20.9 或更新版本。本指南对应 Apache-2.0 许可的 `@facto-to/card@0.0.1-beta.2`;待该确切版本在 npm 可用后安装:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-exact @facto-to/card@0.0.1-beta.2
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
发行前仅可使用通过获批渠道获取且已核验 SHA-256 的候选 tarball,安装命令见 [quickstart](quickstart.md)。
|
|
14
|
+
|
|
15
|
+
| 场景 | `environment` | `apiBaseUrl` | 条件 |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| 本地模拟器 | `dev` | [quickstart](quickstart.md) 中的 loopback origin | 仅合成数据和密钥 |
|
|
18
|
+
| Test | `dev` | 显式设置 `https://test-api.facto.to` | 单独签发 Test scope、凭据和 grants;不自行发送资金请求 |
|
|
19
|
+
| 外部 dev | `dev` | 默认 `https://dev-api.facto.to` | 不是 Test;单独核验部署和运行授权 |
|
|
20
|
+
| production | `production` | 显式提供批准的地址 | 目前未确定生产地址,也没有上线授权 |
|
|
21
|
+
|
|
22
|
+
Test 使用 `FACTO_ENVIRONMENT=dev` 和 `FACTO_API_BASE_URL=https://test-api.facto.to`。不要把模拟器示例直接改地址后作为真实请求运行。各部署的凭据、grants 和 delivery 注册必须隔离。`apiKeySecret` 必须显式指定编码(拒绝裸字符串):Facto 签发的 `hmac_secret` 是 43 位 base64url 字符串,Engine 用该字符串的 UTF-8 字节验签,因此必须传 `{ encoding: 'utf8', value }`;`{ encoding: 'hex', value }` 和 `Uint8Array` 只用于集成约定明确在带外以 hex 或原始字节下发的密钥,不能因为字符串看起来像 hex 就选 `hex`(Engine 会返回 401)。不猜测编码、不打印 secret 或签名;首期联调锁定纯异步受理(预受理校验不满足同步返回 `402`,受理通过返回 `200 processing`,终局由出站 Webhook 与 `lookup` 确认;实时同步审批待共享账本落地前全环境关闭);参见[认证](authentication.md)、[授权](authorizations.md)和[获取接入资料](getting-access.md)。
|
|
23
|
+
|
|
24
|
+
本源码文档不会改写任何已发布包的字节,也不表示新的 npm 版本已经发布。
|
|
25
|
+
|
|
26
|
+
## 执行顺序
|
|
27
|
+
|
|
28
|
+
1. 按 [quickstart](quickstart.md) 运行本地 simulator、首个 SDK 请求、vectors 和 deliveries。最小 HTTP receiver 只证明传输,不验签、不持久化,不能用于真实接收端。合成通过不等于真实 P1–P7 通过。
|
|
29
|
+
2. 按[规范](interlace-adapter-v1.zh.md)实现请求关联、最多一次资金写、unknown 只读恢复、清算投影和独立子交易。旧字段语义不同时,在 Adapter 中保留原值并完成 profile,不以运营标记伪造清算。
|
|
30
|
+
3. 按[授权](authorizations.md)、[幂等](idempotency.md)、[delivery](deliveries.md)和[对账](reconciliation.md)接入现有 SDK,保留供应商原记录、冻结请求映射和 Facto 对象的关联。通用 SDK 重试不授权重发 Interlace 资金写。
|
|
31
|
+
4. Interlace 提供自有 HTTPS callback URL、所需事件/操作 scope 和实现版本。Facto 审批并通过安全渠道签发 program/connection、请求 key、delivery verification registry、mapping revision、环境 origin 和 grants。不要在普通邮件中发送密钥。
|
|
32
|
+
5. Facto 组织同一主体、卡及关联交易的 P1–P7 Test 联合验收。真实 KYC/发卡、资金、重投或开关须先批准具名环境、费用、scope 和停止条件;沙箱可能产生真实费用和主网资金变化。Test 整链通过后才考虑外部 dev,并另行验证迁移、部署候选和运行准入。
|
|
33
|
+
6. 按下列格式提交结果。未支持或未执行的项如实标注,不把缺失项写成通过。
|
|
34
|
+
|
|
35
|
+
真实 Interlace 适配实证、完整 Test/dev 生命周期 UAT 和生产准入尚未完成。合成示例、部署或局部验证不能代替整链验收。
|
|
36
|
+
|
|
37
|
+
## 结果回执
|
|
38
|
+
|
|
39
|
+
随实现提供以下非敏感信息:
|
|
40
|
+
|
|
41
|
+
- profile `facto-interlace-v1`、实际安装的 `@facto-to/card` 版本及完整性摘要、实现版本、部署环境/API 版本、生效时间及实现和联调联系人。
|
|
42
|
+
- 原生账本字段到 profile 的映射,尤其 `clientTransactionId`、动作自身 ID、父 backlink、`clearingEvidence` 各字段和退款占用;幂等保留期及权威索引行为。说明文字不能代替行为证据。
|
|
43
|
+
- 未支持条目的编号、原因和交付安排;不得自行修改合同后宣称兼容。
|
|
44
|
+
|
|
45
|
+
逐项按 [P1–P7](interlace-adapter-v1.zh.md#p1p7-验收) 返回。初始为 NOT_RUN,只有实际完成且证据齐全才能填 PASS。Interlace 提供供应商账本、接口、Adapter 和自有接收端证据;Facto 提供 SDK/后端、账务、界面和实际收款证据,双方按稳定关联联合核验。P1/P7 跨系统结果由 Facto 汇总;不要求 Interlace 读取 Facto 内部数据库或代证用户到账。只完成一侧不能标联合项 PASS。
|
|
46
|
+
|
|
47
|
+
| 用例 | 状态(PASS / FAIL / BLOCKED / NOT_RUN) | 实际结果及证据 |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| P1 唯一关联与幂等 | NOT_RUN | 同 scope 请求、交易和 Facto 对象映射;重复/并发真实执行计数 |
|
|
50
|
+
| P2 unknown 恢复 | NOT_RUN | 丢响应后原 ID 只读查询、零/多/错结果;资金 POST 未增加 |
|
|
51
|
+
| P3 权威清算 | NOT_RUN | 原始清算事实、标准化投影及与冲正 CLOSED 的区分 |
|
|
52
|
+
| P4 部分冲正 | NOT_RUN | 未清算父交易、独立子 ID/backlink、原金额/冲正额/剩余额 |
|
|
53
|
+
| P5 已清算退款 | NOT_RUN | 清算前置、独立子交易、多次部分退款及并发占用不超本金 |
|
|
54
|
+
| P6 安全与异常 | NOT_RUN | 重复/乱序、权限拒绝、错误签名和身份冲突的消费者结果 |
|
|
55
|
+
| P7 对账 | NOT_RUN | 同一供应商、SDK、账务和 UI 对象;实际资金回流与费用另证 |
|
|
56
|
+
|
|
57
|
+
每条证据关联执行时间、环境/实现版本、用例编号、预期与实际结果、去 query/hash 的安全页面地址、非敏感角色/scope、脱敏 API 请求/响应及必要的只读账务断言。需要截图的关键业务前后状态使用正式截图,凭据页不得截图。保留可验证三来源关联的非敏感请求/交易 ID,不拼接不同主体的材料。
|
|
58
|
+
|
|
59
|
+
不得附 secret、token、签名密钥、完整 PAN/CVV、KYC 文档或认证回调 URL。受限证据通过约定的安全渠道处理;普通邮件只发送安全索引和脱敏内容。
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Facto–Interlace Adapter v1
|
|
2
|
+
|
|
3
|
+
[Chinese profile](interlace-adapter-v1.zh.md) | [Chinese integration and results](integration.zh.md) | [Guide](README.md)
|
|
4
|
+
|
|
5
|
+
These are Facto's adaptation requirements, not a claim that Interlace supports them or that Test has passed. Interlace owns its ledger facts, stable identifiers, idempotent execution and queryability, and maps real facts to the SDK. Facto owns scope verification, frozen requests, versions and predecessors, accounting, authorization projections and callbacks. The reference consumer must not invent supplier facts. This sandbox profile is Facto's choice, not a universal industry JSON format.
|
|
6
|
+
|
|
7
|
+
## Request and transaction identity
|
|
8
|
+
|
|
9
|
+
Each authorization, partial reversal and merchant refund has a distinct client business request ID, not a new trace ID for each HTTP delivery. Before execution, Interlace must durably bind it to scope and immutable request semantics. A successful transaction has its own stable ID. Every child action must have its own ID, distinct from the parent, and a backlink to the original consumption; each partial refund has a separate child ID.
|
|
10
|
+
|
|
11
|
+
One scope, request ID and semantics produce at most one business operation. A change of card, action, amount, currency or parent must produce a conflict, not a second operation. Concurrent calls, redelivery and timeouts must not duplicate the operation. Scope includes supplier account, card, deployment/customer environment and the corresponding Facto program/connection; do not reuse IDs or credentials across scopes. The supplier must state its idempotency retention period and retain the request-to-transaction association with the transaction record. Expiry does not authorize resending.
|
|
12
|
+
|
|
13
|
+
Facto sends each supplier funds write at most once. After an unknown response, use read-only queries; do not automatically retry a funds request. Generic SDK retry rules do not override this restriction. Do not infer request-to-child association from matching card, amount, time, a unique new row, parent ID or arrival order.
|
|
14
|
+
|
|
15
|
+
The sandbox uses the existing `POST /open-api/v3/vcc/simulate/{auth|reversal|refund}`, retaining `cardId`, `amount` and the child action's `relatedTransactionId`. It additionally requires `clientTransactionId` to hold the durable business request ID. This is a new profile requirement, not proof that an identically named field in old documentation already supports it. If the native field has different semantics, Interlace must retain its original value and implement this profile in its adapter. A successful response must contain `responseCode=APPROVE`, `reasonCode=APPROVE`, the action's own `transactionId` and the unchanged `clientTransactionId`. The current Interlace Adapter consumes UUID transaction IDs; the general SDK interface requires only a stable string and does not impose UUIDs on other suppliers.
|
|
16
|
+
|
|
17
|
+
Persist the original request and scope before sending. The actual response, authoritative original record read back by that ID, and original request ID must agree before establishing a trusted association. APPROVE does not prove Facto has debited funds or the user has received them.
|
|
18
|
+
|
|
19
|
+
## Read-only recovery of unknown outcomes
|
|
20
|
+
|
|
21
|
+
Timeouts, disconnections, incomplete responses, identity conflicts and uncertain service errors remain unknown. Do not release the reservation, change the request ID or proceed with subsequent actions. If the supplier ID is known, query that exact transaction. Otherwise use the existing transaction list or query with the original `clientTransactionId` and original account/card. Interlace must adapt that entrypoint into an authoritative, unambiguous business-request index; an old endpoint accepting a filter is not enough.
|
|
22
|
+
|
|
23
|
+
Zero results or `not_observed` mean only that nothing has been observed; continue to hold. Multiple results, ineffective filtering, or mismatched scope, amount, currency or parent-child relationship are conflicts and remain on hold. Even a unique match must be read back by exact supplier ID and checked against the original record. Do not select the first page row, latest transaction or an apparently unique transaction with the same amount. Read-only recovery binds only the original reservation and idempotent request; it creates or resends no funds request.
|
|
24
|
+
|
|
25
|
+
Query the existing Facto object through the SDK using its original scope and locator. Retain the three-way linkage: the supplier's original record proves the original transaction, the frozen approval/dispatch mapping proves the request binding, and the official SDK shows the same Facto object's status. The base authorization projection has an optional `supplier_transaction_id` string; it does not guarantee a UUID or supply the original supplier amount/currency. The USDC amount in an approved lifecycle projection is not the supplier's original USD record.
|
|
26
|
+
|
|
27
|
+
## Authoritative clearing and refundable principal
|
|
28
|
+
|
|
29
|
+
Authorization holds, preauthorization reductions or releases, consumption clearing, merchant refunds, Facto payments and user refunds are distinct facts. `CLOSED`, `completeTime`, APPROVE, silence, exclusion of known reversals or a manual declaration alone cannot prove consumption clearing. Network clearing entries do not prove Facto received funds or the user received a refund.
|
|
30
|
+
|
|
31
|
+
Interlace must provide this new normalized projection from its real clearing ledger on the existing exact transaction readback. Existing authoritative native fields may be mapped to it, but the mapping must be explicit and demonstrated; it cannot be inferred from operating parameters, test flags or CLOSED. A separate clearing object or additional event UUID is not required. Reject when the projection is absent; do not claim the old API is already compatible:
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"clearingEvidence": {
|
|
36
|
+
"profile": "facto-interlace-v1",
|
|
37
|
+
"state": "CLEARED",
|
|
38
|
+
"amount": "0.02",
|
|
39
|
+
"currency": "USD",
|
|
40
|
+
"occurredAt": "2026-01-01T00:00:00Z",
|
|
41
|
+
"revision": 1,
|
|
42
|
+
"refundableAmount": "0.02"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
This is synthetic, not a supplier sample. The parent record must also contain the exact transaction ID, account read scope, card, type, original amount/currency and client-request association. `amount` is the currently cleared principal, `occurredAt` the actual clearing time, and `revision` a monotonically increasing revision of the object's facts. This profile consumes ordinary equal-amount clearing only; differences and multiple captures must not be treated as equal clearing. `refundableAmount` is principal available after successful and accepted/in-flight refund reservations, without additional advances. It indicates supplier-side availability, not funds returned to Facto.
|
|
48
|
+
|
|
49
|
+
Different facts at the same revision conflict; an old revision must not overwrite newer facts. Missing or unparseable fields, negative values, currency mismatch, invalid time or revision, and out-of-range net amounts all remain on hold. Corrections must preserve prior facts and associations rather than silently overwrite them.
|
|
50
|
+
|
|
51
|
+
## Partial reversals and merchant refunds
|
|
52
|
+
|
|
53
|
+
For an uncleared partial reversal, the original consumption remains PENDING. The reversal child has its own transaction ID, original request ID, original consumption backlink, amount/currency and status. In the synthetic example, reversing 0.01 of a 0.02 consumption leaves 0.01 pending; it cannot disappear or become settled.
|
|
54
|
+
|
|
55
|
+
A cleared merchant refund requires valid authoritative clearing evidence for that original consumption and sufficient supplier refundable principal. A refund is a distinct child action, not a clearing difference adjustment. The existing Interlace projection uses type 0 for refund, type 14 for reversal and type 1 for consumption; type alone proves neither parent-child linkage nor final status. The refund child record must have its own ID, original client request ID, `relatedCardTransactionId` pointing to the original consumption, correct card/amount/currency and authoritative status.
|
|
56
|
+
|
|
57
|
+
The supplier must atomically ensure successful and in-flight refunds for one consumption do not exceed refundable principal; two concurrent requests must not both refund against stale availability. Facto retains its existing final-send fence, irreversible reservations and shared limit rather than creating a second ledger. Acceptance, a refund child record or supplier balance credit is not Facto receipt or user receipt. Reconcile actual lawful return of funds to Facto, fees and final evidence separately. Until funds return, wait for funds; do not automatically advance money or refund the user. The approved manual full-principal, no-gas-deduction boundary remains in force.
|
|
58
|
+
|
|
59
|
+
## SDK and callbacks
|
|
60
|
+
|
|
61
|
+
- Dispatch authorization with `card.authorizations.create`, real source facts, correct scope, `external_card_id`, `external_authorization_id`, `resource_version`, `mapping_revision`, `amount`, `currency`, CVM facts and an explicit `idempotencyKey`. Asynchronous `processing` is not terminal.
|
|
62
|
+
- Submit subsequent `clearing`, `reversal` and `refund` facts with `card.authorizations.recordFact`, `fact_type`, `predecessor_version`, stable versions and idempotency keys. Even where generic SDK types make supplier, parent or client association fields optional, this adapter must supply enough evidence to prove the association. `status: "recorded"` does not mean funds movement completed.
|
|
63
|
+
- Use `card.authorizations.lookup` with the original authorization ref, supplier ref, original idempotency locator or charge locator, scope and version. Unknown/`not_observed` does not release the hold for resending; lifecycle and payment_details each require approval.
|
|
64
|
+
- Use `verifyEventDelivery`, `decodeDeliveryEvent` and `receiveEventDelivery` for callbacks: verify the raw body and full scope, durably deduplicate by stable event identity, and ACK only after persistence. A delivery attempt is not a business idempotency key.
|
|
65
|
+
|
|
66
|
+
Supplier events can be duplicated or arrive out of order. Use stable event identity, resource version and predecessor to prevent duplicates and regression. Do not merge different partial refunds merely because they share a parent and type. Conflicting content under the same event identity must not overwrite the ledger. Read the original object to investigate missing or conflicting facts; do not reconstruct them from arrival order. Supplier signatures and Facto SDK verification each establish their own sender and cannot replace one another.
|
|
67
|
+
|
|
68
|
+
## P1–P7 acceptance
|
|
69
|
+
|
|
70
|
+
| Case | Required evidence | Not accepted |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| P1 | Unique association of the same user/card authorization request, client request ID, own supplier UUID and Facto operation; duplicates and concurrency add no funds-request effect | Guessing from card, time or amount |
|
|
73
|
+
| P2 | Read-only recovery by original request after a lost write response; zero, multiple or wrong objects remain on hold; actual supplier POST count does not increase | Resending, changing key or presenting a mock as real evidence |
|
|
74
|
+
| P3 | Authoritative readback of ordinary equal-amount clearing, distinct from CLOSED caused by full reversal | CLOSED, silence or operational confirmation alone |
|
|
75
|
+
| P4 | Uncleared partial reversal with independent child ID/backlink, pending remainder and complete reconciliation | Calling a reversal a merchant refund |
|
|
76
|
+
| P5 | Cleared merchant refund with independent child ID/backlink and safe totals across multiple partial and concurrent refunds | Returning only the parent ID or treating an adjustment as a refund |
|
|
77
|
+
| P6 | Duplicates, reordering, denied permission, invalid signatures and identity conflicts create no new debit or refund | Testing only claim counts or removing positive tests |
|
|
78
|
+
| P7 | Traceable amount and status for the same object across supplier, SDK/backend, accounting and UI; separate evidence of actual funds return | Treating supplier credit as user receipt |
|
|
79
|
+
|
|
80
|
+
Facto first completes production Adapter consumer tests explicitly marked synthetic. Interlace then supplies its adapted version, field mapping, reproducible sandbox behavior and redacted real evidence. Consider dev only after each approved real sandbox scenario passes Test. A specification, implementation, merge, deployment or local green result does not substitute for the full lifecycle. Mark unadapted or unexecuted items NOT COMPLETE. Real funds, environment and operational permissions require separate approval.
|
|
81
|
+
|
|
82
|
+
## References
|
|
83
|
+
|
|
84
|
+
- [Stripe idempotent requests](https://docs.stripe.com/api/idempotent_requests) and [uncertain errors and retries](https://docs.stripe.com/error-low-level): this profile chooses the stricter read-only policy after unknown outcomes.
|
|
85
|
+
- [Adyen refunds](https://docs.adyen.com/online-payments/refund) and [idempotency](https://docs.adyen.com/development-resources/api-idempotency): original payment association, child reconciliation, scope and retention.
|
|
86
|
+
- [Adyen capture](https://docs.adyen.com/online-payments/capture) and [settlement details](https://docs.adyen.com/reporting/settlement-reconciliation/transaction-level/settlement-details-report): authorization, capture, settlement and actual receipt are distinct; authoritative evidence need not be a clearing webhook.
|
|
87
|
+
- [Stripe webhooks](https://docs.stripe.com/webhooks) and [Adyen event handling](https://docs.adyen.com/development-resources/webhooks/handle-webhook-events): duplicates, reordering, verification and stable identity; their vendor-specific APIs are not copied directly.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Facto–Interlace Adapter v1
|
|
2
|
+
|
|
3
|
+
[English](interlace-adapter-v1.md) | [中文接入与结果回执](integration.zh.md) | [指南](README.md)
|
|
4
|
+
|
|
5
|
+
本规范是 Facto 确定的适配要求,不代表 Interlace 已支持或 Test 已通过。Interlace 负责其账本事实、稳定标识、幂等执行和可查询性,并将真实事实映射到 SDK;Facto 负责 scope、冻结请求、版本与前驱、账务、授权投影和回调。参考消费者不得自行制造供应商事实。这里的沙箱 profile 是 Facto 的选择,不是行业统一 JSON。
|
|
6
|
+
|
|
7
|
+
## 请求和交易关联
|
|
8
|
+
|
|
9
|
+
授权、部分冲正、商户退款各有不复用的客户端业务请求 ID,不是每次 HTTP 投递的新 trace ID。执行前,Interlace 必须将 ID 与 scope 和不可变请求语义持久绑定;成功交易有自己的稳定 ID。子动作必须有不同于父交易的独立 ID 和指回原消费的关联(backlink),每次部分退款都有独立子 ID。
|
|
10
|
+
|
|
11
|
+
同一 scope、请求 ID 和语义只能产生一个业务操作;卡、动作、金额、币种或父交易改变时必须冲突,不能创建第二笔。并发、重投和超时不能产生重复操作。scope 包括供应商账户、卡、deployment/customer environment 和对应 Facto program/connection,ID 和凭据不能跨 scope 使用。供应商须说明幂等保留期,并随交易记录保留交易与请求的关联;保留期过期不能授权重发。
|
|
12
|
+
|
|
13
|
+
Facto 对供应商资金写请求采取最多一次策略:响应未知后只读查询,不自动重试资金请求。通用 SDK 的重试规则不改变此限制。不能用相同卡、金额、时间、唯一新增行、父 ID 或到达顺序猜测请求与子交易的关联。
|
|
14
|
+
|
|
15
|
+
沙箱沿用 `POST /open-api/v3/vcc/simulate/{auth|reversal|refund}`,保留 `cardId`、`amount` 和子动作的 `relatedTransactionId`,并要求 `clientTransactionId` 为持久业务请求 ID。这是新增 profile 要求,不能从旧文档同名字段推断已支持;若原字段语义不同,Interlace 在适配层保留原值并完成此 profile。成功响应须包含 `responseCode=APPROVE`、`reasonCode=APPROVE`、动作自身 `transactionId` 和原样 `clientTransactionId`。当前 Interlace Adapter 消费 UUID 形态的交易 ID;SDK 通用接口只要求稳定字符串,不把 UUID 推广为通用要求。
|
|
16
|
+
|
|
17
|
+
出站前持久保存原请求及 scope。实际响应、按该 ID 权威读回的原记录和原请求 ID 必须一致,才建立可信关联。APPROVE 不证明 Facto 已扣款或用户到账。
|
|
18
|
+
|
|
19
|
+
## unknown 只读恢复
|
|
20
|
+
|
|
21
|
+
超时、断连、不完整响应、身份冲突和不确定服务错误均保持 unknown:不释放占用、不换请求 ID、不继续后继动作。已知供应商 ID 时精确查询交易;未知 ID 时用原 `clientTransactionId` 和原账户/卡查询既有交易列表或查询入口。Interlace 必须将该入口适配为权威、无歧义的业务请求索引,旧接口接受过滤参数本身不够。
|
|
22
|
+
|
|
23
|
+
零结果或 `not_observed` 只表示尚未观察到,继续 hold(保留占用并暂停后续资金动作,允许按原请求只读查证,不释放占用或重试资金请求);多结果、过滤未生效、scope、金额、币种或父子关系不一致均冲突 hold。唯一匹配仍须按供应商 ID 精确读回核对原记录,不能选分页首行、最近一笔或看似唯一的同金额交易。只读恢复只绑定原占用和原幂等请求,不创建或重发资金请求。
|
|
24
|
+
|
|
25
|
+
SDK 按原 scope 和 locator(定位原对象的查询标识)查询原 Facto 对象。保留三来源关联:供应商原记录证明原交易,冻结批准/dispatch 映射证明原请求绑定,正式 SDK 证明 Facto 同一对象状态。基础 authorization 投影的 `supplier_transaction_id` 是可选字符串,不保证返回 UUID,也不提供供应商原金额/币种;获批 lifecycle 投影中的 USDC 金额不能冒充供应商原 USD 记录。
|
|
26
|
+
|
|
27
|
+
## 权威清算和可退本金
|
|
28
|
+
|
|
29
|
+
授权占用、预授权减少或释放、消费清算、商户退款、Facto 支付和用户返款是不同事实。`CLOSED`、`completeTime`、APPROVE、无新事件、排除已知冲正或人工声明都不能单独证明消费清算。网络清算记账也不等于 Facto 实际收款或用户返款到账。
|
|
30
|
+
|
|
31
|
+
Interlace 须从真实清算账本,在既有精确交易读回记录上提供以下新增标准化投影;可以映射现有原生权威字段,但映射必须明确并经实证,不能由运营参数、测试标记或 CLOSED 推算。无需强制独立清算对象或额外事件 UUID。没有投影时拒绝,不能宣称旧 API 已兼容:
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"clearingEvidence": {
|
|
36
|
+
"profile": "facto-interlace-v1",
|
|
37
|
+
"state": "CLEARED",
|
|
38
|
+
"amount": "0.02",
|
|
39
|
+
"currency": "USD",
|
|
40
|
+
"occurredAt": "2026-01-01T00:00:00Z",
|
|
41
|
+
"revision": 1,
|
|
42
|
+
"refundableAmount": "0.02"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
示例为合成数据,不是供应商样本。父记录还须包含精确交易 ID、账户读取 scope、卡、类型、原金额/币种和客户端请求关联。`amount` 是当前已清算本金,`occurredAt` 是实际清算时间,`revision` 是对象事实的单调修订号。本 profile 仅消费普通等额清算,差额和多次 capture 不能视作等额清算。`refundableAmount` 扣除已成功及已受理/在途退款占用,不含额外垫资;它只表示供应商侧可退,不表示资金已回 Facto。
|
|
48
|
+
|
|
49
|
+
同 revision 不同事实冲突,旧 revision 不得覆盖新事实;缺字段、解析失败、负数、币种不符、时间或版本无效、净额越界均 hold。更正必须保留前序事实及关联,不得静默覆盖。
|
|
50
|
+
|
|
51
|
+
## 部分冲正和商户退款
|
|
52
|
+
|
|
53
|
+
未清算部分冲正时原消费仍为 PENDING;reversal 子动作有自身交易 ID、原请求 ID、原消费 backlink、金额/币种和状态。合成例中原消费 0.02 冲正 0.01 后,剩余 0.01 仍未决,不能消失或变为已结算。
|
|
54
|
+
|
|
55
|
+
已清算商户退款必须先取得该原消费有效的权威清算事实并核实可退本金足够。refund 是独立子动作,不是清算差额调整。既有 Interlace 投影使用 type 0 退款、type 14 冲正、type 1 消费;类型本身不足以证明父子关系或最终状态。退款子记录须包含自身 ID、原客户端请求 ID、指回原消费的 `relatedCardTransactionId`、正确卡/金额/币种和权威状态。
|
|
56
|
+
|
|
57
|
+
供应商须原子保证同一消费成功及在途退款合计不超过可退本金,不能让两个并发请求都凭过时余额退款。Facto 沿用最终发送 fence、不可逆占用和共同额度,不另造第二账本。受理、退款子记录或 supplier balance credit 不等于 Facto 收款或用户到账。Facto 合法资金实际回流、费用和最终凭据另行对账;未回流时等待资金,不自动垫款或发用户退款。已批准的人工全本金、不扣 gas 边界继续适用。
|
|
58
|
+
|
|
59
|
+
## SDK 与回调
|
|
60
|
+
|
|
61
|
+
- 授权使用 `card.authorizations.create`,提供真实源事实、正确 scope、`external_card_id`、`external_authorization_id`、`resource_version`、`mapping_revision`、`amount`、`currency`、CVM 事实及显式 `idempotencyKey`。异步 `processing` 不是终局。
|
|
62
|
+
- 后续事实使用 `card.authorizations.recordFact`,以 `fact_type`(`clearing`、`reversal`、`refund`)、`predecessor_version`、稳定版本和幂等键提交。即使 SDK 通用类型允许供应商、父交易或客户端关联字段缺省,此 Adapter 仍须提供足以证明关联的事实。`status: "recorded"` 不代表资金完成。
|
|
63
|
+
- `card.authorizations.lookup` 使用原授权 ref、供应商 ref、原幂等 locator 或 charge locator,以及原 scope 和版本。unknown/`not_observed` 不解封重发;lifecycle 与 payment_details 分别需要批准。
|
|
64
|
+
- 回调使用 `verifyEventDelivery`、`decodeDeliveryEvent` 和 `receiveEventDelivery`:以原始 body 和完整 scope 验签,以稳定事件身份持久去重,落盘成功才 ACK;delivery attempt 不是业务幂等键。
|
|
65
|
+
|
|
66
|
+
供应商事件可能重复、乱序。使用稳定事件身份、资源版本和 predecessor 防重、防倒退;不能按同父交易和同类型合并不同部分退款。同一事件身份的冲突内容不得覆盖旧账。缺失或冲突时按原对象只读查证,不按到达顺序重建事实。供应商签名与 Facto SDK 验签分别证明各自发送者,不能互相替代。
|
|
67
|
+
|
|
68
|
+
## P1–P7 验收
|
|
69
|
+
|
|
70
|
+
| 编号 | 必须证明 | 不接受的替代 |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| P1 | 同用户/卡授权请求、客户端请求 ID、自身供应商 UUID、Facto 操作唯一关联;重复/并发不增加资金请求效果 | 按卡、时间、金额猜关联 |
|
|
73
|
+
| P2 | 写响应丢失后按原请求只读找回;零、多、错对象继续 hold,实际供应商 POST 计数不增加 | 重发验证、换 key、以 mock 冒实证 |
|
|
74
|
+
| P3 | 原消费普通等额清算可权威读回,并与全额冲正造成的 CLOSED 区分 | 仅凭 CLOSED、静默期或运营确认 |
|
|
75
|
+
| P4 | 未清算部分冲正有独立子 ID/backlink,剩余额未决且完整对账 | 把冲正称为商户退款 |
|
|
76
|
+
| P5 | 已清算商户退款有独立子 ID/backlink,多次部分退款及并发总额安全 | 只返回父 ID、把调整当退款 |
|
|
77
|
+
| P6 | 重复、乱序、权限拒绝、签名无效和身份冲突不引入新扣款或退款 | 只测 claim 数或删正向测试 |
|
|
78
|
+
| P7 | 供应商、SDK/后端、账务和界面可追溯同一对象金额与状态;实际资金回流另有证据 | 用 supplier credit 冒充用户到账 |
|
|
79
|
+
|
|
80
|
+
Facto 先完成明确标为合成的生产 Adapter 消费测试;Interlace 再提供适配版本、字段映射、可复跑的沙箱行为和脱敏真实证据。批准的真实沙箱场景逐项通过 Test 后才考虑 dev;规范、实现、合并、部署或本地绿都不能代替整链。未适配或未执行的项标为 NOT COMPLETE。真实资金、环境和运行权限须另行批准。
|
|
81
|
+
|
|
82
|
+
## 参考资料
|
|
83
|
+
|
|
84
|
+
- [Stripe 幂等请求](https://docs.stripe.com/api/idempotent_requests)、[不确定错误与重试](https://docs.stripe.com/error-low-level):本 profile 选择更严格的未知后只读。
|
|
85
|
+
- [Adyen 退款](https://docs.adyen.com/online-payments/refund)、[幂等](https://docs.adyen.com/development-resources/api-idempotency):原支付关联、子操作对账及 scope 和保留期。
|
|
86
|
+
- [Adyen capture](https://docs.adyen.com/online-payments/capture)、[结算明细](https://docs.adyen.com/reporting/settlement-reconciliation/transaction-level/settlement-details-report):授权、capture、结算和实际到账不同;权威事实不限定必须来自清算 webhook。
|
|
87
|
+
- [Stripe webhooks](https://docs.stripe.com/webhooks)、[Adyen 事件处理](https://docs.adyen.com/development-resources/webhooks/handle-webhook-events):重复、乱序、验签及稳定身份;不直接复制其专属 API。
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Not yet available
|
|
2
|
+
|
|
3
|
+
This page lists current integration limits so you can avoid relying on unavailable capabilities.
|
|
4
|
+
|
|
5
|
+
- Real-time synchronous authorization approval (`decision_mode: "synchronous"`) is closed in every environment pending shared-ledger rollout; initial integrations use asynchronous admission (`200 processing` + finality webhook/`lookup`, with pre-admission `402` refusals).
|
|
6
|
+
- Payout or funding-result notifications are not provided.
|
|
7
|
+
- A refund money-movement API is not provided; subsequent refund facts may be reported and recorded, but they do not themselves move money. The original authorization's approved lifecycle projection can include refund cases. Reading a subsequent fact separately requires an explicitly approved read scope covering its exact mapping revision, operation type, resource version, time window and required fields; without that coverage, the query returns `not_observed`.
|
|
8
|
+
- Amount adjustments and reversals may be recorded as subsequent facts but do not perform funds handling.
|
|
9
|
+
- Per-transaction statements and currency-specific reconciliation statements are not provided.
|
|
10
|
+
- Treasury or funding balance queries are not provided.
|
|
11
|
+
- Partner queries of a cardholder's available limit are not provided.
|
|
12
|
+
|
|
13
|
+
These limitations do not imply a delivery date or commitment.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Quickstart
|
|
2
|
+
|
|
3
|
+
Prerequisites: Node.js 20.9 or later and npm. These commands use only local synthetic data and credentials.
|
|
4
|
+
|
|
5
|
+
## Install the exact beta
|
|
6
|
+
|
|
7
|
+
Create an empty directory and install `0.0.1-beta.2` once that version is available on npm:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
mkdir card-work
|
|
11
|
+
cd card-work
|
|
12
|
+
npm init -y
|
|
13
|
+
npm install --save-exact @facto-to/card@0.0.1-beta.2
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
For pre-release verification, copy the retained tarball into the new directory,
|
|
17
|
+
verify its SHA-256 against the independently supplied digest, and use this command
|
|
18
|
+
in place of the registry install:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install --ignore-scripts --save-exact ./facto-to-card-0.0.1-beta.2.tgz
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Expected: npm completes installation without error. The package has no runtime dependencies.
|
|
25
|
+
|
|
26
|
+
## Start the simulator
|
|
27
|
+
|
|
28
|
+
In the same directory start the service in the background:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
./node_modules/.bin/facto-card simulator 8787 > simulator.log 2>&1 & echo $! > simulator.pid
|
|
32
|
+
node -e 'let n=0;function probe(){const s=require("net").connect(8787,"127.0.0.1");s.once("connect",()=>{s.end();console.log("port_ready:8787")});s.once("error",()=>{if(++n>=50){console.error("port_not_ready");process.exitCode=1}else setTimeout(probe,100)})}probe()'
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Expected: `port_ready:8787`; `simulator.log` contains `simulator_listening:http://127.0.0.1:8787`. The simulator listens only on loopback and uses synthetic test credentials. Leave it running for the next step.
|
|
36
|
+
|
|
37
|
+
## Send a first SDK request
|
|
38
|
+
|
|
39
|
+
Save this tested JavaScript as `first-request.mjs` in the same directory:
|
|
40
|
+
|
|
41
|
+
<!-- example:first-request -->
|
|
42
|
+
```javascript
|
|
43
|
+
import { randomUUID } from 'node:crypto'
|
|
44
|
+
import { pathToFileURL } from 'node:url'
|
|
45
|
+
import { createCardClient } from '@facto-to/card'
|
|
46
|
+
|
|
47
|
+
// All of these values are synthetic and valid only for the loopback simulator.
|
|
48
|
+
export async function firstRequest(apiBaseUrl = 'http://127.0.0.1:8787') {
|
|
49
|
+
const card = createCardClient({
|
|
50
|
+
environment: 'dev',
|
|
51
|
+
apiBaseUrl,
|
|
52
|
+
connectionId: 'pconn_SYNTHETIC00000001',
|
|
53
|
+
programId: 'synthetic-program',
|
|
54
|
+
apiKeyId: 'synthetic-key',
|
|
55
|
+
apiKeySecret: { encoding: 'utf8', value: 'SYNTHETIC-TEST-KEY-NOT-A-SECRET' },
|
|
56
|
+
})
|
|
57
|
+
const id = randomUUID()
|
|
58
|
+
const accepted = await card.authorizations.create({
|
|
59
|
+
external_card_id: 'synthetic-card',
|
|
60
|
+
external_authorization_id: `example-${id}`,
|
|
61
|
+
amount: '10.00',
|
|
62
|
+
currency: 'USD',
|
|
63
|
+
resource_version: 'authorization-v1',
|
|
64
|
+
mapping_revision: 'mapping-v1',
|
|
65
|
+
cardholder_verification: { method: 'provider_attested', verified_at: '2026-01-01T00:00:00Z', evidence_id: 'synthetic-evidence' },
|
|
66
|
+
}, { idempotencyKey: `example-request-${id}` })
|
|
67
|
+
console.log(`authorization_status:${accepted.status}`)
|
|
68
|
+
return accepted
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await firstRequest()
|
|
72
|
+
```
|
|
73
|
+
<!-- /example:first-request -->
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
node first-request.mjs
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Expected: `authorization_status:processing`. The client configuration is for this loopback simulator only; it contains no real credentials.
|
|
80
|
+
|
|
81
|
+
## Run authorization and recovery vectors
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
./node_modules/.bin/facto-card vectors http://127.0.0.1:8787
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Expected: one `vector_passed:<name>` line for each of `authorization`, `authorization_replay`, `integrity_conflict`, `operation_identity_conflict`, `byte_integrity_conflict`, `clearing_fact`, `fact_status`, `fact_missing_predecessor`, `fact_version_conflict`, `fact_authorization_updated`, `fact_reversal`, `fact_refund`, `fact_chargeback`, `fact_settlement`, `status`, `status_supplier_ref`, `trimmed_supplier_ref`, `supplier_namespace_conflict`, `status_idempotency_key`, `status_charge_id`, `status_not_observed`, `status_failed_receipt`, `sync_closed`, `sync_expired`, `explicit_402`, `status_sync_closed`, `status_sync_expired`, `status_explicit_402`, `retry_503`, `retry_after_429`, `invalid_502`, `nested_500_hint_false`, `bad_signature`, `expired_timestamp`, `nonce_replay`, `reconciliation`, and `history_replay`; exit status is zero. A `vector_failed:<name>` line and nonzero exit indicate a failed vector.
|
|
88
|
+
|
|
89
|
+
## Send sample deliveries
|
|
90
|
+
|
|
91
|
+
Start a minimal local HTTP receiver to inspect transport only:
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
node -e 'require("http").createServer((req,res)=>{req.resume();req.on("end",()=>{res.writeHead(200);res.end("ok")})}).listen(8788,"127.0.0.1",()=>console.log("receiver_listening"))' > receiver.log 2>&1 & echo $! > receiver.pid
|
|
95
|
+
node -e 'let n=0;function probe(){const s=require("net").connect(8788,"127.0.0.1");s.once("connect",()=>{s.end();console.log("port_ready:8788")});s.once("error",()=>{if(++n>=50){console.error("port_not_ready");process.exitCode=1}else setTimeout(probe,100)})}probe()'
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Expected: `port_ready:8788`; `receiver.log` contains `receiver_listening`. Then send all shipped delivery scenarios, including duplicate, out-of-order, gap, nullable-card and unsequenced deliveries:
|
|
99
|
+
|
|
100
|
+
```sh
|
|
101
|
+
./node_modules/.bin/facto-card deliveries http://127.0.0.1:8788/events
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Expected: `delivery_response:<vector>:<index>:200` for each delivery, a `vector_passed:<name>` line for each of the 14 shipped scenarios, and exit status zero. The tool reports HTTP responses only; it does not verify business processing results. This minimal receiver deliberately does not verify signatures or persist state.
|
|
105
|
+
|
|
106
|
+
To exercise your own receiver, run `./node_modules/.bin/facto-card simulator-config`. The printed `delivery_verification_config` contains the complete synthetic registry for each independent scenario: key ID and UTF-8 key, key version and validity, environment, program connection, card program, target revision, approved event kinds and selection. Load the matching entry as trusted key and expected scope in a local test receiver only; see the complete values and encoding instructions in [simulator configuration](simulator.md#delivery-verification-configuration). These are test-only credentials whose keys are published in this guide. **Never load these synthetic entries into a receiver that accepts real Facto traffic:** anyone could sign a delivery that such a receiver would accept. You can select one group with `--scenario duplicate` (replace `duplicate` with the desired scenario). By default only loopback callbacks are allowed. `--allow-non-loopback` explicitly permits another callback; use it only for an endpoint you control.
|
|
107
|
+
|
|
108
|
+
To model an operator-requested redelivery after the original sample:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
./node_modules/.bin/facto-card replay http://127.0.0.1:8787 http://127.0.0.1:8788/events --scenario duplicate
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Expected: `history_replay_accepted`, `delivery_response:duplicate:1:200`, and `vector_passed:duplicate`. The CLI first requests synthetic replay, then models later callback delivery. A real receiver should verify and deduplicate the same event ID and body; the minimal receiver above only reports transport.
|
|
115
|
+
|
|
116
|
+
Stop both local services:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
kill "$(cat simulator.pid)" "$(cat receiver.pid)"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Expected: both processes terminate. See [deliveries](deliveries.md) before implementing a production receiver.
|
|
123
|
+
|
|
124
|
+
## Next steps
|
|
125
|
+
|
|
126
|
+
Read [concepts](concepts.md), arrange [access](getting-access.md), and implement [authentication](authentication.md), [authorization handling](authorizations.md), and [deliveries](deliveries.md). Use the [integration checklist](integration-checklist.md) before production.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Reconciliation and recovery
|
|
2
|
+
|
|
3
|
+
This page explains how to inspect delivery history, request replay, recover dead letters, and report lifecycle changes.
|
|
4
|
+
|
|
5
|
+
## Page through a fixed snapshot
|
|
6
|
+
|
|
7
|
+
1. Select an approved fixed `selection_id` or a time window within your approved coverage, a target revision and a page size from 1 to 100. Sequence ranges are not a query option.
|
|
8
|
+
2. Call `card.deliveries.list`. Retain the returned snapshot token and cursor.
|
|
9
|
+
3. For every next page, send the same selection and snapshot token with the returned cursor. Do not widen the time window or change target revision midway.
|
|
10
|
+
4. Stop when `complete` is true. `snapshot_at` identifies the snapshot; it is not a sequence watermark.
|
|
11
|
+
|
|
12
|
+
Results contain delivery metadata such as `event_id`, origin connection, nullable `connection_sequence`, event digest, target revision and `delivery_state`. They do **not** return the event kind, original body or signature, and cannot be used as independently verifiable event deliveries. A missing sequence does not prove an event will never be delivered: it may be invisible, outside the selected range or outside your authorization.
|
|
13
|
+
|
|
14
|
+
Reconciliation `event_sha256` includes the `sha256:` prefix; `verifyEventDelivery` returns `bodyDigest` as bare hexadecimal. Normalize before comparison using the tested `sameDeliveryDigest` function below.
|
|
15
|
+
|
|
16
|
+
| `delivery_state` | Meaning |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
| `pending` | Awaiting delivery. |
|
|
19
|
+
| `held` | Delivery is held. |
|
|
20
|
+
| `accepted` | The target accepted a delivery; this does not prove the recipient's business processing succeeded. |
|
|
21
|
+
| `failed` | An attempt failed and is awaiting retry. |
|
|
22
|
+
| `dead_lettered` | Retry processing has ended in a dead letter. |
|
|
23
|
+
| `indeterminate` | The result of an attempt is unknown. |
|
|
24
|
+
|
|
25
|
+
## Request historical replay
|
|
26
|
+
|
|
27
|
+
Submit only the program reference and an already approved selection ID with `card.deliveryReplays.create` and a stable idempotency key; the SDK supplies the program reference. Replay needs a separately approved grant. You cannot select individual events or a sequence range in this request. HTTP 202 means the request was accepted, not that any event was returned or delivered, and it guarantees neither delivery nor timing. Events are sent later through the normal delivery channel, using the normal sending budget. Their event ID and body stay the same; timestamp and signature change. Verify every arriving replay. Replay is an operational action, not a synchronous way to fill a gap during a delivery handler.
|
|
28
|
+
|
|
29
|
+
## Recover a dead letter
|
|
30
|
+
|
|
31
|
+
`card.deadLetters.list` and `card.deadLetters.replay` cover the legacy binding-event channel within your authorized connection. They do not cover charge events or the newer fixed-selection replay. A successful request does not prove that the event has been delivered again; an out-of-scope ID does not provide cross-tenant discovery.
|
|
32
|
+
|
|
33
|
+
## Operational reconciliation
|
|
34
|
+
|
|
35
|
+
Process and deduplicate deliveries as they arrive. Periodically compare your records with the approved reconciliation view. If you find `dead_lettered`, `failed`, `indeterminate`, or an expected event absent from your records, use the onboarding contact channel to arrange an appropriate replay with Facto.
|
|
36
|
+
|
|
37
|
+
Original delivery and replay share one sending budget for the same event and target. Once exhausted, replay to that same target will not send again; contact Facto through the onboarding channel.
|
|
38
|
+
|
|
39
|
+
## Report a lifecycle event
|
|
40
|
+
|
|
41
|
+
Use `card.events.record` with the original certified provider assertion. The SDK does not mint that assertion. The local simulator accepts a synthetic assertion only for demonstration; it does not certify a provider signature or perform a real lifecycle effect.
|
|
42
|
+
|
|
43
|
+
The tested example covers pagination, historical replay, dead-letter lookup and replay, and lifecycle submission. Supply actual approved IDs and assertions from your integration.
|
|
44
|
+
|
|
45
|
+
<!-- example:reconciliation -->
|
|
46
|
+
```typescript
|
|
47
|
+
import type { CardInboundEventInput, CardClient } from '@facto-to/card'
|
|
48
|
+
|
|
49
|
+
export function sameDeliveryDigest(eventSha256: string, bodySha256: string): boolean {
|
|
50
|
+
return eventSha256 === bodySha256
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export async function reconcileAndReplay(card: CardClient, targetRevision: string, selectionId: string, replayKey: string) {
|
|
54
|
+
let cursor: string | undefined
|
|
55
|
+
let snapshot: string | undefined
|
|
56
|
+
const items = []
|
|
57
|
+
do {
|
|
58
|
+
const page = await card.deliveries.list({
|
|
59
|
+
target_revision: targetRevision,
|
|
60
|
+
selection_id: selectionId,
|
|
61
|
+
page_size: 100,
|
|
62
|
+
...(snapshot ? { snapshot_token: snapshot } : {}),
|
|
63
|
+
...(cursor ? { cursor } : {}),
|
|
64
|
+
})
|
|
65
|
+
items.push(...page.items)
|
|
66
|
+
snapshot = page.snapshot_token
|
|
67
|
+
cursor = page.next_cursor ?? undefined
|
|
68
|
+
if (page.complete) break
|
|
69
|
+
if (!cursor) throw new Error('incomplete_page_without_cursor')
|
|
70
|
+
} while (true)
|
|
71
|
+
const replay = await card.deliveryReplays.create({ selection_id: selectionId }, { idempotencyKey: replayKey })
|
|
72
|
+
return { items, replay }
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export async function recoverDeadLetter(card: CardClient, deadLetterId: string) {
|
|
76
|
+
const page = await card.deadLetters.list({ limit: 10 })
|
|
77
|
+
const replay = await card.deadLetters.replay(deadLetterId)
|
|
78
|
+
return { page, replay }
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export async function recordInboundEvent(card: CardClient, event: CardInboundEventInput) {
|
|
82
|
+
// Supply the original certified provider JWS assertion; the SDK does not mint it.
|
|
83
|
+
return card.events.record(event)
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
<!-- /example:reconciliation -->
|