跳转到主要内容
银行数据功能可用于沙盒应用。 生产环境中的应用在宣布开放生产环境访问之前,调用会返回 404,沙盒环境则不产生任何费用。 本快速入门将通过可直接复制粘贴的请求,带您从沙盒应用获取 Didit Test Bank 的账户、余额和交易数据。
下方每个响应都已精简,仅保留关键字段。 请将 API 密钥保存在您的服务器上:它不会传输到浏览器或应用中。

步骤 1:使用银行数据权限创建 API 密钥

银行数据不属于完全访问权限。 使用完全访问权限的密钥(包括应用的主密钥)调用任何银行数据接口都会被拒绝,并返回 403 bank_data_access_denied。
  1. 在 Business Console 中,打开您的沙盒应用并进入 API keys。
  2. 创建一个自定义访问权限的密钥,并添加 Bank data:读取类操作选择 Read,用于创建、修改或删除数据的调用选择 Write。
  3. 复制密钥并将其导出:
有关全部资源的列表,请参阅 API 密钥。

第 2 步: 创建链接

链接代表用户连接银行时经历的一次界面流程。 为 Test Bank 创建一个持续链接:
country 是用户银行所在国家/地区的三字母代码,为可选项。 如果已知该信息,请传入此参数,这样用户只会看到该国家/地区的银行;未传入时,用户可以从您可服务的所有国家/地区中选择。 如需一次性访问,请发送 "access": "one_time"(默认值)。
请将链接的 id 与对应用户一同保存。 url 和 client_token 仅在创建链接时返回一次。

第 3 步 打开链接并连接 Didit Test Bank

在浏览器中打开 url,或通过电子邮件或聊天工具发送给用户。 用户会看到同意页面,选择 Didit Test Bank,使用其中一位测试客户登录,然后选择要共享的账户。 沙盒页面列出了测试客户以及每位客户会提供的内容。 如需在之后将用户返回您的网站,请参阅返回您的网站。 如果没有 redirect_url,用户会停留在 Didit 的结果页面,您需要通过 Webhook 或读取接口获知结果。

步骤 4: 接收 Webhook 并确认

与任何 Webhook 一样,在控制台中为目标订阅 bank.* 事件。 终端用户完成操作后,系统会先发送 bank.link.completed,其中包含 link_id 和 connection_id;首次同步存储账户后,再发送 bank.connection.created。 切勿信任浏览器发送给您的链接 ID。 请自行读取该链接:
status 为 completed,或为以下终态之一:cancelled、expired、failed。failed 状态的链接会携带 error.code;cancelled 状态的链接则为 error: null。

第 5 步: 读取账户、余额和交易

金额以十进制字符串表示,转出资金为负数。 只要还有更多数据未读取,一页交易记录就会包含 next_page_token。 请参阅账户、余额和交易。

步骤 6 跟踪变更数据流

变更数据流只返回自您上次读取以来发生变化的内容。 您的第一次读取(不带游标)会返回完整快照:连接中的每笔交易都会以 added 形式返回,并带有 reset: true。 第一页可能带有 has_more: true 和 next_page_token,但此时还没有 next_cursor。 当 has_more 为 true 时,请使用 page_token 继续读取。请保存最后一页(即 has_more: false 的那一页)的 next_cursor,供下次读取使用:
reset: true 表示响应是完整快照:请用它替换您的副本,而不是追加到副本中。 bank.data.updated 会告诉您一次同步何时存储了新内容。

第 7 步 立即同步

持续连接会自动同步。 如需立即读取银行数据,请发起一次同步:
每家银行每天允许的无人值守读取次数有限。 连接上的 sync.live_syncs_left_today 和 sync.budgets 会显示剩余次数以及重置时间,超出限制的调用会返回 429 refresh_limit_reached 以及重置时间。 请参阅 按需刷新银行数据。

步骤 8 停止访问与删除

停止访问和删除是两个不同的调用。
已删除连接的响应只包含 id、status、status_reason、created_at 和 erasure 字段。 参见 数据、同意与删除。

后续步骤

最后修改于 2026年11月22日