> ## 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 테스트 은행의 계좌, 잔액, 거래 내역까지: 샌드박스 애플리케이션에서 API 키와 링크를 만들고, 연결, 조회, 동기화, 삭제까지 진행하세요.

뱅크 데이터는 샌드박스 애플리케이션에서 사용할 수 있습니다.
라이브 애플리케이션의 호출은 라이브 액세스가 공지되기 전까지 `404`로 응답하며, 샌드박스에서는 어떤 요금도 청구되지 않습니다.
이 퀵스타트에서는 복사하여 붙여넣기만 하면 되는 요청을 사용해 샌드박스 애플리케이션에서 Didit Test Bank의 계정, 잔액, 거래에 액세스하는 방법을 안내합니다.

> [!NOTE]
>
> 아래 응답은 모두 중요한 필드만 남도록 줄여 표시했습니다.
> API 키는 서버에 보관해야 합니다. API 키는 브라우저나 앱에 절대 전달되지 않습니다.

## 1단계: Bank data 권한으로 API 키 만들기

Bank data는 전체 액세스 권한에 포함되지 않습니다.
애플리케이션의 기본 시크릿을 포함한 전체 액세스 키는 모든 Bank data 호출에서 `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/ko/console/api-keys.md)를 참조하십시오.

## Step 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`는 사용자 은행이 있는 국가의 3자리 국가 코드이며 선택 사항입니다.
알고 있다면 전송하십시오. 그러면 사용자에게 해당 국가의 은행만 표시되며, 전송하지 않으면 귀사가 서비스할 수 있는 모든 국가 중에서 선택하게 됩니다.
일회성 접근을 원하면 `"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/ko/core-technology/bank-verification/sandbox.md)에서 테스트 고객 목록과 각 고객이 제공하는 데이터를 확인할 수 있습니다.

그 후에 최종 사용자를 사이트로 되돌리려면 [사이트로 돌아가기](https://docs.didit.me/ko/integration/bank-link/return-to-your-site.md)를 참고하세요.
`redirect_url`을 설정하지 않으면 최종 사용자는 Didit의 결과 페이지에서 절차를 마치며, 결과는 webhook이나 API 조회를 통해 확인할 수 있습니다.

## 4단계: webhook 수신 및 확인

콘솔에서 `bank.*` 이벤트를 구독하도록 대상을 등록하세요. 다른 [webhook](https://docs.didit.me/ko/integration/webhooks.md)과 마찬가지입니다.
사용자가 절차를 마치면 `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/ko/core-technology/bank-verification/accounts-balances-transactions.md)을 참조하십시오.

## Step 6: 변경 피드 따라가기

변경 피드는 마지막으로 읽은 이후에 변경된 내용만 반환합니다.
커서 없이 처음 읽으면 전체 스냅샷이 반환됩니다. 연결에 있는 모든 거래가 각각 `added`로 반환되고, 응답에는 `reset: true`가 포함됩니다.
첫 페이지에는 아직 `next_cursor` 없이 `has_more: true`와 `next_page_token`만 있을 수 있습니다.
`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/ko/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/ko/core-technology/bank-verification/data-consent-and-deletion.md)를 참조하세요.

## 다음 단계

* [연결](https://docs.didit.me/ko/core-technology/bank-verification/connections.md): 일회성 및 지속적인 접근, 동의, 갱신.
* [은행 webhook](https://docs.didit.me/ko/core-technology/bank-verification/webhooks.md)
* [요금](https://docs.didit.me/ko/getting-started/bank-verification-pricing.md)
* [API 레퍼런스](https://docs.didit.me/ko/standalone-apis/bank-data.md)


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