您需要准备的内容
- 具有银行数据权限的 API 密钥,用于您的沙盒应用。请参阅 快速入门。
- 用于接收
bank.*事件的 Webhook 目标。请参阅 银行 Webhook。 - 数据库中的一张表,用于为每个客户存储连接 ID、变更流游标和同意到期时间。
步骤 1 创建具有持续访问权限的链接
access: ongoing会让访问权限保持开启,直至同意结束。consent_days只是一项请求:实际日期由银行决定,并显示在连接信息中。history_from用于请求从某个日期开始的历史记录,例如年初。如果您更倾向于使用history_days(1 至 365),可以改用它,但两者不能同时使用。银行可能提供的数据较少:每个账户都会通过history_coverage报告实际覆盖范围。ownership.compare: none会跳过账户持有人比对,因此无需提供参考身份。如需将账户持有人与 Didit 中已验证的企业进行比对,请使用business。end_user.reference是您为该客户设置的 ID。它可以被搜索,并可让 Didit 识别同一客户再次连接相同账户的情况。- 将客户引导至托管验证页面,并通过重定向 URL将其返回您的产品。
id 与客户一起存储。
步骤 2 等待连接
客户端完成操作后,会收到包含connection_id 的 bank.link.completed。
请确认该事件,因为绝不能信任浏览器:
connection_id,然后等待 bank.connection.created。此时即可读取账户、余额和近期交易(sync.initial_status 为 succeeded 或 partial)。
bank.connection.history_complete 会在历史数据回填结束后发出。
对于每个账户,history_coverage.oldest_booking_date 表示银行实际提供的历史数据最早可追溯到的记账日期。
步骤 3: 加载第一份副本
空游标会返回所有当前交易,每笔都标记为added 且 reset: true。
逐页读取,并仅在最后保存游标:
- 首次读取是真正的快照:它返回连接在读取开始时拥有的每一笔交易,每笔仅以
added形式返回一次,并且是其当前状态,即使您在翻页时运行了同步。 - 翻页期间发生的变更会在从
next_cursor开始的下一次读取中返回:您已收到的交易会以modified形式再次返回,新交易则以added形式返回。 - 仅在收到
has_more: false的响应后,才保存next_cursor。 - 如果翻页中途失败,请从您已保存的游标重新开始。
- 使用
GET /v3/bank/accounts/{account_id}/balances/读取余额。
步骤 4 - 在每个 Webhook 到达时保持数据最新
Didit 会在每个活跃的持续连接上自动同步,每天一到四次,具体取决于银行(sync.frequency_per_day)。
当一次同步存储了变更时,bank.data.updated 会随 connection_id、account_ids 和计数一同送达。
使用您保存的游标调用变更信息流:
added为新交易,包括待处理交易。modified为已变更的交易,内容为其当前状态。对每一条按id执行插入或更新操作:您已持有的交易会被更新,尚未持有的交易则会被新增。removed带有reason。忽略您没有的id。当待处理交易入账时,它会以pending_booked原因出现在removed中,入账后的交易则会出现在added中。
id 用作主键:它在多次读取、同步和续期之间保持不变。
检查 identity_quality:当其值为 derived 时,银行更正可能表现为一条 removed 加一条 added。
读取操作不计费,但数据只有在同步运行时才会变化,因此每个 Webhook 读取一次即可。
如需更快获取数据,请使用 Sync Now:按需刷新银行数据。
第 5 步 处理重置
游标早于重放窗口时,接口返回410 cursor_expired,并带有 bootstrap: true。
变更日志可重放 90 天,因此对于每日运行的任务,这种情况很少见。
请从空游标重新开始,并用返回的结果替换您的副本,而不是追加到现有副本中。
从空游标发起的每次读取都会带有 reset: true,因此新连接和过期游标可以走同一段代码路径。
步骤 6 关注同意的到期时间
同意有一个到期日期:consent.expires_at。
Didit 会在到期前 14 天、7 天和 1 天发送 bank.connection.consent_expiring。
需要续期时,调用 renew_connection。在剩余有效期超过 30 天时,它会返回 409 renewal_not_needed。
供终端用户完成续期的页面暂不可用。
如果终端用户任由同意过期,连接状态将变为 renewal_required:您仍可以读取已同步的数据。
详情请参阅银行同意的续期。
步骤 7 停止访问并删除
- 客户离开您的产品:调用
revoke_connection立即停止读取,或调用delete_connection停止读取并删除已存储的数据。 - 客户在银行停止共享:
bank.connection.revoked会随附ended_by到达。请停止该连接的数据推送。
价格
持续访问按每个活跃连接每月计费。 该价格包含连接中的所有账户、余额、交易、银行提供时最多 365 天的历史记录、自动同步、在银行限制范围内的实时同步、续期、Webhook 以及所有读取操作。 未完成的链接免费,状态为renewal_required、paused 或 revoked 的连接同样免费。
请参阅 定价。
检查清单
- 每个客户与每家银行只建立一个连接,并保存其游标和授权到期时间。
- Webhook 处理程序具备幂等性,以事件 ID 为键。
-
reset: true会替换您的副本,绝不会追加。 - 已处理
removed及其原因。 - 授权到期提醒已与您向客户发出的通知对接。
-
bank.connection.revoked会停止数据推送。 - 沙盒中的沙盒套餐通过测试。