메인 콘텐츠로 건너뛰기
POST
curl
Didit의 Create a Bank Link 엔드포인트는 서버에서 한 번의 Bank Link 실행을 시작하여 은행을 연결하거나 연결을 갱신하고, 호스팅된 url을 반환합니다. 모든 필드에는 기본값이 있으므로 가장 간단한 요청은 {}에 원하는 값을 더한 형태입니다. 반환된 id는 사용자와 연결해 저장하고, 결과는 Bank Link 조회 또는 bank.link.completed webhook을 통해 직접 확인하세요. 빠른 시작과 Bank Link를 참고하세요.

인증

x-api-key
string
header
필수

귀사 애플리케이션의 API 키입니다. Business Console의 Developers -> API keys에서 확인할 수 있습니다. 기본 키는 모든 권한을 가집니다. 명명된 키는 범위를 지정할 수 있습니다. 리소스별로 권한 없음, 읽기 또는 쓰기를 설정할 수 있고, 일부 워크플로나 승인된 세션으로 제한할 수 있으며, 허용된 IP 목록으로 제한할 수 있고, 만료일을 설정할 수 있습니다. 401은 키가 잘못되었거나, 취소되었거나, 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스 또는 작업에 대한 권한이 없거나, 요청이 IP 목록 밖의 주소에서 왔음을 의미합니다. 세션 경로에서 발생한 404는 세션이 키의 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 동영상 및 PDF URL을 null로 받으며, 세션 쓰기 권한이 없는 키는 세션 링크와 토큰을 null로 받습니다. 자세한 내용은 https://docs.didit.me/console/api-keys 를 참조합니다.

헤더

Idempotency-Key
string

한 작업을 위해 직접 정하는 선택적 재시도 안전 키입니다. 최대 255자이며 UUID를 사용할 수 있습니다. 같은 키, 엔드포인트, 쿼리, 본문으로 반복된 요청에는 첫 번째 응답이 같은 상태 코드와 같은 본문으로 반환되며, 다시 실행되거나 다시 과금되지 않습니다. 같은 키를 다른 엔드포인트, 쿼리 또는 본문과 함께 사용하면 409 idempotency_key_reused가 반환되고, 첫 번째 요청이 아직 실행 중이면 Retry-After와 함께 409 idempotency_key_in_progress가 반환됩니다. 실패한 요청(모든 4xx 또는 5xx)은 저장되지 않으므로 같은 키로 다시 보낼 수 있습니다. 키는 API 키로 호출하든 액세스 토큰으로 호출하든 사용자의 애플리케이션에 속합니다. 재시도 및 멱등성을 참고하세요.

Required string length: 1 - 255

본문

application/json

은행 링크를 생성합니다. 가장 간단한 요청은 원하는 값을 더한 {}입니다. 모든 필드에는 기본값이 있습니다.

mode
enum<string>
기본값:connect

connect(기본값)는 새 연결을 만듭니다. renew는 connection_id가 필요하며 해당 연결의 설정을 재사용합니다.

사용 가능한 옵션:
connect,
renew
connection_id
string<uuid>

갱신할 연결입니다. mode: renew인 경우에만 사용합니다.

access
enum<string>
기본값:one_time

one_time(기본값)은 데이터를 한 번만 읽습니다. ongoing은 동의가 끝나거나 누군가 중단할 때까지 접근을 유지합니다. institution_id를 설정하면, 지속적인 접근을 유지할 수 없는 은행은 화면을 띄우기 전에 400 ongoing_access_not_available을 반환합니다. 설정하지 않으면 은행 선택 화면에는 지속적인 접근이 가능한 은행만 표시됩니다.

사용 가능한 옵션:
one_time,
ongoing
country
string

선택 사항입니다. 지정하지 않으면 사용자가 애플리케이션에서 활성화된 국가 중에서 선택합니다. Bank Link가 지원하는 국가여야 하며, ZZZ를 포함한 그 외의 값은 400 invalid_request를 반환하며 field: country가 표시됩니다. 빈 요청 본문은 유효합니다.

Pattern: ^[A-Z]{3}$
institution_id
string

선택 사항입니다. list_institutions에서 가져온 은행을 미리 선택하며, 선택 화면을 건너뜁니다.

Maximum string length: 64
segment
enum<string>
기본값:any

선택기를 필터링하고, 은행이 로그인을 구분하는 경우 어떤 로그인을 열지 은행에 알려 줍니다. 기본값은 any입니다.

사용 가능한 옵션:
personal,
business,
any
data
enum<string>[]

읽을 대상입니다. accounts는 항상 포함되며, 이름, 유형, 통화, 식별자와 은행이 공유하는 경우 보유자 이름이 들어갑니다. 기본값은 ["accounts"]입니다.

Maximum array length: 3
사용 가능한 옵션:
accounts,
balances,
transactions
history_days
integer
기본값:90

요청할 거래 내역의 일수입니다. 1에서 365 사이이며 기본값은 90입니다. 은행은 이보다 적게 제공할 수 있습니다. 각 계좌는 실제로 제공한 기간을 history_coverage에 보고합니다. history_from과 함께 보낼 수 없습니다.

필수 범위: 1 <= x <= 365
history_from
string<date>

history_days 대신 요청할 이력의 시작 날짜입니다. history_days와 함께 보낼 수 없으며, 둘을 함께 보내면 400 history_window_ambiguous로 응답합니다. 365일보다 오래되었거나 미래인 날짜는 400 window_not_available로 응답합니다.

extended_history
enum<string>
기본값:standard

allow_extra_auth를 사용하면 추가 확인을 한 번 더 요구하는 은행에서도 이전 내역을 제공받을 수 있습니다.

사용 가능한 옵션:
standard,
allow_extra_auth

지속 액세스에만 해당합니다. 은행에 액세스를 유지해 달라고 요청할 일수이며, 1 이상이어야 합니다. 기본값은 은행이 허용하는 최대 기간입니다. 연결은 은행이 실제로 승인한 날짜를 consent.expires_at에 보고합니다. access: one_time을 사용하면 400 invalid_request를 반환하며 field: consent_days가 표시됩니다.

필수 범위: 1 <= x <= 32767
ownership
object

선택 사항입니다. 계좌 소유자를 개인 또는 기업과 비교합니다.

end_user
object

계정을 연결하는 개인 또는 기업입니다.

redirect_url
string<uri>

브라우저가 마지막에 이동할 주소이며, link_id, status, 서명된 state가 함께 전달됩니다(표시용으로만 사용하세요. webhook과 get_link가 공식 결과입니다). 샌드박스 애플리케이션에서는 localhost, 127.0.0.1, [::1]의 일반 http 주소(포트와 경로는 자유, 자격 증명과 프래그먼트 없음)는 등록이 필요하지 않습니다. 그 밖의 주소는 400 redirect_url_not_registered로 응답합니다. 다른 주소의 등록은 아직 제공되지 않습니다. redirect_url을 보내지 않으면 사용자는 Didit의 자체 결과 페이지에서 절차를 마칩니다.

Maximum string length: 2048
allowed_origins
string<uri>[]

현재 사용되지 않으며, 아직 출시되지 않은 Didit 내장 Bank Link를 위해 예약되어 있습니다. HTTPS 출처, 최대 50개.

Maximum array length: 50
language
string

선택 사항입니다. es 또는 pt-BR과 같은 언어 코드입니다. 지정하지 않으면 브라우저 언어를 사용합니다.

Maximum string length: 16
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
vendor_data
string

귀사의 참조 값이며, 링크와 연결에 반환됩니다.

Maximum string length: 255
expires_in
integer
기본값:3600

링크의 유효 기간을 초 단위로 나타내며, 300에서 86400 사이입니다. 기본값은 3600입니다.

필수 범위: 300 <= x <= 86400
duplicates
enum<string>
기본값:reuse

reuse(기본값)는 이미 공유 중인 계정으로 연결되는 링크를 해당 연결의 갱신으로 완료합니다. allow는 독립된 두 번째 연결을 만듭니다.

사용 가능한 옵션:
reuse,
allow
allow_one_time_fallback
boolean
기본값:false

ongoing과 함께 사용하면, 지속적인 접근을 유지할 수 없는 은행에서도 최종 사용자가 은행 화면에서 축소된 접근 권한을 확인한 후 일회성 읽기로 계속 진행할 수 있습니다. 견적에는 그 비용이 표시됩니다. access: ongoing일 때만 사용할 수 있으며, 일회성 접근에서는 400 invalid_request와 field: allow_one_time_fallback을 반환합니다.

accept_reduced_grant
boolean
기본값:false

은행 또는 사용자가 요청한 범위보다 적은 권한을 부여하는 경우, 링크를 완료하고 부여된 범위에 대해서만 요금을 부과합니다. 그렇지 않으면 링크는 reduced_grant와 함께 failed 상태로 종료되며 요금은 부과되지 않습니다.

sandbox
object

샌드박스 애플리케이션에만 적용됩니다. Didit Test Bank 고객을 선택합니다. 라이브 애플리케이션에서는 무시됩니다.

응답

링크가 생성되었습니다.

한 사용자를 위한 Bank Link의 실행 한 번입니다. 은행을 연결하거나 연결을 갱신합니다. 링크는 get_link로 직접 확인하십시오. 브라우저가 보낸 id는 절대 신뢰하지 마십시오.

id
string<uuid>
필수

링크의 ID입니다.

mode
enum<string>
필수
사용 가능한 옵션:
connect,
renew
access
enum<string>
필수
사용 가능한 옵션:
one_time,
ongoing
status
enum<string>
필수

링크의 상태입니다. completed, cancelled, expired, failed는 최종 상태입니다.

사용 가능한 옵션:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
필수

사용자를 안내할 호스팅 페이지입니다. 링크를 생성할 때만 반환되며, 토큰이 저장되지 않으므로 이후 조회에서는 null입니다.

client_token
string | null
필수

Didit의 임베디드 Bank Link용 토큰이며, 아직 출시되지 않았습니다. 현재는 url을 여십시오. 링크를 생성할 때만 반환되며, 이후 조회에서는 null입니다. 용도가 단일하고 수명이 짧습니다. 개인 데이터를 포함하지 않습니다. 절대 로그에 남기지 마십시오.

expires_at
string<date-time>
필수

사용되지 않은 링크가 작동을 멈추는 시점입니다.

connection_id
string<uuid> | null
필수

status가 completed일 때 이 링크로 생성되거나 갱신된 연결입니다.

check_id
string<uuid> | null
필수

이 링크에서 ownership.compare를 none 이외의 값으로 요청한 경우의 소유 구조 결과입니다.

reused
boolean
필수

사용자가 정확히 이 계정들을 이미 공유하고 있어서 링크가 기존 연결의 갱신으로 완료된 경우 true입니다(duplicates: reuse). 이중으로 요금이 청구되지 않습니다.

error
object | null
필수

status가 failed인 경우 링크가 실패한 이유입니다. 그렇지 않으면 null입니다.

quote
object
필수

링크 생성 시 고정되는 링크 가격입니다. 청구되는 금액은 견적의 금액입니다. 조회는 절대 과금되지 않습니다.

vendor_data
string | null
필수

요청에 있던 귀사의 참조 값입니다.

마지막 수정일 2026년 11월 22일