> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 银行数据快速入门：连接测试银行并读取交易

> Didit 测试银行快速入门：在沙盒应用中创建密钥与链接，完成连接、读取账户、余额与交易，并进行同步与删除。

银行数据功能可用于沙盒应用。
生产环境中的应用在宣布开放生产环境访问之前，调用会返回 `404`，沙盒环境则不产生任何费用。
本快速入门将通过可直接复制粘贴的请求，带您从沙盒应用获取 Didit Test Bank 的账户、余额和交易数据。

> [!NOTE]
>
> 下方每个响应都已精简，仅保留关键字段。
> 请将 API 密钥保存在您的服务器上：它不会传输到浏览器或应用中。

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

银行数据不属于完全访问权限。
使用完全访问权限的密钥（包括应用的主密钥）调用任何银行数据接口都会被拒绝，并返回 `403 bank_data_access_denied`。

1. 在 [Business Console](https://business.didit.me) 中，打开您的沙盒应用并进入 **API keys**。
2. 创建一个自定义访问权限的密钥，并添加 **Bank data**：读取类操作选择 **Read**，用于创建、修改或删除数据的调用选择 **Write**。
3. 复制密钥并将其导出：

```bash theme={null}
export DIDIT_API_KEY="your-sandbox-key"
```

有关全部资源的列表，请参阅 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)。

## 第 2 步: 创建链接

链接代表用户连接银行时经历的一次界面流程。
为 Test Bank 创建一个持续链接：

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/links/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "access": "ongoing",
    "country": "ESP",
    "data": ["accounts", "balances", "transactions"],
    "history_days": 90,
    "vendor_data": "client-7731"
  }'
```

`country` 是用户银行所在国家/地区的三字母代码，为可选项。
如果已知该信息，请传入此参数，这样用户只会看到该国家/地区的银行；未传入时，用户可以从您可服务的所有国家/地区中选择。
如需一次性访问，请发送 `"access": "one_time"`（默认值）。

```json theme={null}
{
  "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40",
  "mode": "connect",
  "access": "ongoing",
  "status": "created",
  "url": "https://verify.didit.me/bank/link/...",
  "expires_at": "2026-11-22T13:00:00Z",
  "connection_id": null
}
```

请将链接的 `id` 与对应用户一同保存。
`url` 和 `client_token` 仅在创建链接时返回一次。

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

在浏览器中打开 `url`，或通过电子邮件或聊天工具发送给用户。
用户会看到同意页面，选择 **Didit Test Bank**，使用其中一位测试客户登录，然后选择要共享的账户。
[沙盒页面](https://docs.didit.me/zh/core-technology/bank-verification/sandbox.md)列出了测试客户以及每位客户会提供的内容。

如需在之后将用户返回您的网站，请参阅[返回您的网站](https://docs.didit.me/zh/integration/bank-link/return-to-your-site.md)。
如果没有 `redirect_url`，用户会停留在 Didit 的结果页面，您需要通过 Webhook 或读取接口获知结果。

## 步骤 4: 接收 Webhook 并确认

与任何 [Webhook](https://docs.didit.me/zh/integration/webhooks.md) 一样，在控制台中为目标订阅 `bank.*` 事件。
终端用户完成操作后，系统会先发送 `bank.link.completed`，其中包含 `link_id` 和 `connection_id`；首次同步存储账户后，再发送 `bank.connection.created`。

切勿信任浏览器发送给您的链接 ID。
请自行读取该链接：

```bash theme={null}
curl https://verification.didit.me/v3/bank/links/$LINK_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{ "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40", "status": "completed", "connection_id": "5e1d2a70-3b4c-4d5e-8f60-71829304a5b6" }
```

`status` 为 `completed`，或为以下终态之一：`cancelled`、`expired`、`failed`。`failed` 状态的链接会携带 `error.code`；`cancelled` 状态的链接则为 `error: null`。

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

```bash theme={null}
curl https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/accounts/ -H "x-api-key: $DIDIT_API_KEY"
curl https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/balances/ -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/transactions/?date_from=2026-01-01" -H "x-api-key: $DIDIT_API_KEY"
```

金额以十进制字符串表示，转出资金为负数。
只要还有更多数据未读取，一页交易记录就会包含 `next_page_token`。
请参阅[账户、余额和交易](https://docs.didit.me/zh/core-technology/bank-verification/accounts-balances-transactions.md)。

## 步骤 6 跟踪变更数据流

变更数据流只返回自您上次读取以来发生变化的内容。
您的第一次读取（不带游标）会返回完整快照：连接中的每笔交易都会以 `added` 形式返回，并带有 `reset: true`。
第一页可能带有 `has_more: true` 和 `next_page_token`，但此时还没有 `next_cursor`。
当 `has_more` 为 `true` 时，请使用 `page_token` 继续读取。请保存最后一页（即 `has_more: false` 的那一页）的 `next_cursor`，供下次读取使用：

```bash theme={null}
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/" -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?page_token=$NEXT_PAGE_TOKEN" -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?cursor=$NEXT_CURSOR" -H "x-api-key: $DIDIT_API_KEY"
```

`reset: true` 表示响应是完整快照：请用它替换您的副本，而不是追加到副本中。
`bank.data.updated` 会告诉您一次同步何时存储了新内容。

## 第 7 步 立即同步

持续连接会自动同步。
如需立即读取银行数据，请发起一次同步：

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/refresh/ -H "x-api-key: $DIDIT_API_KEY"
```

每家银行每天允许的无人值守读取次数有限。
连接上的 `sync.live_syncs_left_today` 和 `sync.budgets` 会显示剩余次数以及重置时间，超出限制的调用会返回 `429 refresh_limit_reached` 以及重置时间。
请参阅 [按需刷新银行数据](https://docs.didit.me/zh/use-cases/refresh-bank-data-on-demand.md)。

## 步骤 8 停止访问与删除

停止访问和删除是两个不同的调用。

```bash theme={null}
# Stop access at the bank. The connection keeps its data until you delete it.
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/revoke/ -H "x-api-key: $DIDIT_API_KEY"

# Delete the connection and its data. Irreversible.
curl -X DELETE https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

已删除连接的响应只包含 `id`、`status`、`status_reason`、`created_at` 和 `erasure` 字段。
参见 [数据、同意与删除](https://docs.didit.me/zh/core-technology/bank-verification/data-consent-and-deletion.md)。

## 后续步骤

* [连接](https://docs.didit.me/zh/core-technology/bank-verification/connections.md)：一次性和持续访问、同意及续期。
* [银行 Webhook](https://docs.didit.me/zh/core-technology/bank-verification/webhooks.md)
* [定价](https://docs.didit.me/zh/getting-started/bank-verification-pricing.md)
* [API 参考](https://docs.didit.me/zh/standalone-apis/bank-data.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.