> ## 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.

# Bank Data Quickstart: Connect a Test Bank and Read Transactions

> From a sandbox application to the accounts, balances and transactions of the Didit Test Bank: create a key and a link, connect, read, sync and delete.

Bank data is available for sandbox applications.
A live application's calls answer `404` until live access is announced, and nothing is charged in sandbox.
This quickstart takes you from a sandbox application to the accounts, balances and transactions of the Didit Test Bank with copy-paste requests.

> [!NOTE]
>
> Every response below is shortened to the fields that matter.
> Keep the API key on your server: it never reaches a browser or an app.

## Step 1: create an API key with the Bank data permission

Bank data is not part of full access.
A full-access key, including the application's primary secret, is refused on every Bank data call with `403 bank_data_access_denied`.

1. In the [Business Console](https://business.didit.me), open your sandbox application and go to **API keys**.
2. Create a key with custom access and add **Bank data**: **Read** for the reads, **Write** for the calls that create, change or delete something.
3. Copy the key and export it:

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

See [API keys](https://docs.didit.me/console/api-keys.md) for the full list of resources.

## Step 2: create a link

A link is one run of the screens where a person connects a bank.
Create an ongoing one for the 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` is the three-letter country of the person's bank and is optional.
Send it when you know it, so the person sees only that country's banks; without it they choose among every country you can serve.
For one-time access send `"access": "one_time"` (the default).

```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
}
```

Keep the link `id` with your user.
The `url` and the `client_token` are returned once, when the link is created.

## Step 3: open the link and connect the Didit Test Bank

Open the `url` in a browser, or send it to the person by email or chat.
The person sees the consent screen, picks **Didit Test Bank**, signs in with one of the test customers and chooses the accounts to share.
The [sandbox page](https://docs.didit.me/core-technology/bank-verification/sandbox.md) lists the test customers and what each gives you.

To return the person to your site afterwards, see [Return to your site](https://docs.didit.me/integration/bank-link/return-to-your-site.md).
Without a `redirect_url` the person finishes on Didit's result page and you learn the result from the webhook or from a read.

## Step 4: receive the webhooks and confirm

Subscribe a destination to the `bank.*` events in the console, as for any [webhook](https://docs.didit.me/integration/webhooks.md).
When the person finishes, `bank.link.completed` arrives with the `link_id` and the `connection_id`, then `bank.connection.created` when the first sync has stored the accounts.

Never trust a link id that a browser sends you.
Read the link yourself:

```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" }
```

The `status` is `completed` or a final one (`cancelled`, `expired`, `failed`). A `failed` link carries an `error.code`; a `cancelled` one reads `error: null`.

## Step 5: read accounts, balances and transactions

```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"
```

Amounts are decimal strings, negative for money out.
A page of transactions carries `next_page_token` while there is more to read.
See [Accounts, balances and transactions](https://docs.didit.me/core-technology/bank-verification/accounts-balances-transactions.md).

## Step 6: follow the change feed

The change feed returns only what changed since your last read.
Your first read, with no cursor, is the full snapshot: every transaction the connection has, each as `added`, with `reset: true`.
A first page can carry `has_more: true` with a `next_page_token` and no `next_cursor` yet.
Keep reading with `page_token` while `has_more` is `true`, and store the `next_cursor` of the last page (the one with `has_more: false`) for next time:

```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` means the response is a full snapshot: replace your copy with it instead of adding to it.
`bank.data.updated` tells you when a sync stored something new.

## Step 7: sync now

An ongoing connection syncs by itself.
To read the bank now, ask for a sync:

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

A bank allows a limited number of unattended reads a day.
`sync.live_syncs_left_today` and `sync.budgets` on the connection say how many are left and when they reset, and a call beyond the limit answers `429 refresh_limit_reached` with the reset time.
See [Refresh bank data on demand](https://docs.didit.me/use-cases/refresh-bank-data-on-demand.md).

## Step 8: stop access and delete

Stopping access and deleting are two different calls.

```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"
```

A deleted connection answers only its `id`, `status`, `status_reason`, `created_at` and `erasure`.
See [Data, consent and deletion](https://docs.didit.me/core-technology/bank-verification/data-consent-and-deletion.md).

## Next steps

* [Connections](https://docs.didit.me/core-technology/bank-verification/connections.md): one-time and ongoing access, consent and renewal.
* [Bank webhooks](https://docs.didit.me/core-technology/bank-verification/webhooks.md)
* [Pricing](https://docs.didit.me/getting-started/bank-verification-pricing.md)
* [API reference](https://docs.didit.me/standalone-apis/bank-data.md)


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