필요한 항목
- 샌드박스 애플리케이션에서 사용할 은행 데이터 권한이 있는 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를 받으면 피드를 중단합니다. - 샌드박스 요금제 테스트를 통과합니다.