메인 콘텐츠로 건너뛰기
지속적인 은행 데이터 피드는 고객이 다시 로그인하지 않아도 회계 또는 장부 기장 애플리케이션에 각 고객의 은행 계좌 잔액과 거래 내역을 매일 제공합니다. Didit을 사용하면 지속적인 액세스 권한이 있는 링크를 만들고, 새 데이터가 도착하면 webhook을 받고, 커서로 변경된 내용만 읽고, 동의가 언제 종료되는지 확인하고, 고객이 떠날 때 연결을 중지하거나 삭제할 수 있습니다. 이 가이드는 고객 한 명에 대한 매일 피드를 처음부터 설정하는 과정을 안내합니다. 같은 코드를 모든 고객에게 사용하며, 고객과 은행마다 연결을 하나씩 만듭니다.

필요한 항목

  • 샌드박스 애플리케이션에서 사용할 은행 데이터 권한이 있는 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를 최종 사용자와 함께 저장하십시오.

Step 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단계: 첫 번째 사본 불러오기

빈 커서로 요청하면 현재 모든 거래가 reset: true와 함께 added로 반환됩니다. 페이지를 넘기며 모두 읽고, 커서는 마지막에만 저장합니다:
  • 첫 번째 읽기는 실제 스냅샷입니다. 읽기가 시작된 시점에 연결에 있던 모든 거래를 정확히 한 번씩 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 기준 upsert로 적용하십시오. 이미 보유한 거래는 업데이트되고, 아직 보유하지 않은 거래는 추가됩니다.
  • removed에는 reason이 포함됩니다. 보유하지 않은 id는 무시하십시오. 보류 중인 거래가 확정되면 pending_booked와 함께 removed에 포함되어 빠지고, 확정된 거래는 added로 도착합니다.
거래 id를 키로 사용하십시오. 이 값은 조회, 동기화, 갱신 전반에서 동일하게 유지됩니다. identity_quality를 확인하십시오. derived인 경우 은행의 정정이 removed 한 건과 added 한 건으로 나타날 수 있습니다. 조회에는 요금이 청구되지 않습니다. 다만 데이터는 동기화가 실행될 때만 바뀌므로 webhook마다 한 번 조회하면 충분합니다. 더 빨리 가져오려면 Sync Now를 사용하십시오: 요청 시 은행 데이터 새로 고침.

5단계: 재설정 처리

재생 기간보다 오래된 커서는 bootstrap: true와 함께 410 cursor_expired로 응답합니다. 변경 로그는 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를 받으면 피드를 중단합니다.
  • 샌드박스 요금제 테스트를 통과합니다.
마지막 수정일 2026년 11월 22일