> ## 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 Link 생성 API: 은행 연결 및 갱신

> Didit의 Create a Bank Link 엔드포인트는 서버에서 Bank Link 실행을 시작하고, 사용자가 은행을 연결하는 호스팅 url을 반환합니다.

Didit의 Create a Bank Link 엔드포인트는 서버에서 한 번의 Bank Link 실행을 시작하여 은행을 연결하거나 연결을 갱신하고, 호스팅된 `url`을 반환합니다.
모든 필드에는 기본값이 있으므로 가장 간단한 요청은 `{}`에 원하는 값을 더한 형태입니다.
반환된 `id`는 사용자와 연결해 저장하고, 결과는 [Bank Link 조회](https://docs.didit.me/ko/standalone-apis/bank-link-get.md) 또는 `bank.link.completed` webhook을 통해 직접 확인하세요.
[빠른 시작](https://docs.didit.me/ko/core-technology/bank-verification/quickstart.md)과 [Bank Link](https://docs.didit.me/ko/core-technology/bank-verification/bank-link.md)를 참고하세요.


## OpenAPI

````yaml ko/openapi-25.json POST /v3/bank/links/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 신원 인증 API입니다. x-api-key 헤더로 인증하십시오.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, 연결, 계정, 잔액, 거래, 기관 및 적용 범위. 은행 데이터는 샌드박스 애플리케이션에서 사용할 수 있습니다.
      라이브 애플리케이션의 호출은 라이브 액세스가 공지될 때까지 `404`로 응답합니다. 샌드박스에서는 요금이 부과되지 않습니다. API
      키로 수행하는 호출에는 은행 데이터 권한(`bank-data`)이 있는 키가 필요합니다. 읽기에는 read, 무언가를 변경하는
      작업에는 write 권한이 필요합니다. 계정 확인은 예외입니다. 이 경우에는 은행 데이터 권한이 아니라 세션에 대한 write 액세스
      또는 전체 액세스가 필요합니다. 은행 데이터는 전체 액세스에 포함되지 않습니다. 전체 액세스 키는 거부되며, 해당 권한이 있는 키를
      생성할 때까지 호출은 `403 bank_data_access_denied`로 응답합니다. 원시 은행 데이터(계정, 잔액, 거래 및
      변경 피드)도 API 키가 없는 요청은 거부합니다.


      `/v3/bank/` 아래에서 계정 확인을 제외한 모든 거부 응답은 동일한 JSON 본문(`code`, `message`,
      `request_id`, `field`, `next_action`, `retry_after`)을 가집니다. 작업이 아닌 경로,
      UUID가 아닌 ID 또는 알 수 없는 하위 리소스는 모든 메서드에 대해 `404 not_found`로 응답하며, 예상치 못한 오류는
      `request_id`와 함께 `500 internal_error`로 응답합니다. 은행 데이터를 사용할 수 없는 경우 모든 작업은 알
      수 없는 경로와 마찬가지로 플랫폼의 표준 `404`로 응답합니다.
paths:
  /v3/bank/links/:
    post:
      tags:
        - Bank Data
      summary: 은행 링크 생성
      description: >-
        은행 링크를 생성합니다. 은행 링크는 사용자가 은행을 연결하거나 연결을 갱신하는 흐름의 한 번의 실행입니다. 사용자를 `url`로
        안내하십시오. `client_token`은 Didit의 임베디드 은행 링크용이며 아직 출시되지 않았습니다. 지금은 `url`을
        여십시오. 완료된 링크는 연결을 생성합니다.


        가장 간단한 요청은 `{}`에 원하는 값을 더한 형태입니다. 기본값은 다음과 같습니다. `mode`는 connect,
        `access`는 one_time, `data`는 accounts only, `history_days`는 90,
        `ownership.compare`는 none, `segment`는 any, `duplicates`는 reuse,
        `allow_one_time_fallback`은 false이며, 지속적인 접근의 경우 은행이 허용하는 기간만큼의 동의가
        적용됩니다.


        응답에는 견적이 포함됩니다. 가격은 링크에 고정되며 견적대로 청구됩니다. API 키는 브라우저나 앱에 절대 전달되지 않으며,
        `url`만 전달됩니다.


        결과는 `get_link` 또는 `bank.link.completed` webhook으로 직접 확인하십시오. 브라우저에서 보낸
        링크 ID는 절대 신뢰하지 마십시오. 거래 내역 기간: `history_from` 또는 `history_days` 중 하나만
        보내고 둘 다 보내지 마십시오. 은행이 허용하는 경우 지속적인 접근은 동의가 끝날 때까지 유지되며, 실제 날짜는 각 연결에서
        확인할 수 있습니다.


        은행 데이터 권한(`bank-data`)이 있는 API 키가 필요합니다. 이 작업은 쓰기 작업이며 무언가를 변경합니다. 전체 접근
        권한이 있는 키에는 이 권한이 포함되지 않으므로, 키를 생성할 때 명시적으로 부여하십시오. 그렇지 않으면 호출 시 응답은 `403
        bank_data_access_denied`입니다.
      operationId: createBankLink
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankLinkCreateRequest'
            example:
              mode: connect
              access: ongoing
              country: ESP
              segment: business
              data:
                - accounts
                - balances
                - transactions
              history_from: '2026-01-01'
              consent_days: 180
              ownership:
                compare: none
              end_user:
                reference: client-7731
                email: ana@example.com
              redirect_url: https://app.example.com/bank/return
              allowed_origins:
                - https://app.example.com
              language: es
              vendor_data: client-7731
      responses:
        '201':
          description: 링크가 생성되었습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankLink'
              examples:
                Ongoing business connection:
                  summary: 스페인 기업 계좌의 지속적인 액세스
                  value:
                    id: 0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40
                    mode: connect
                    access: ongoing
                    status: created
                    url: https://verify.didit.me/bank/link/example-link-token
                    client_token: example-client-token
                    expires_at: '2026-11-21T13:00:00Z'
                    connection_id: null
                    check_id: null
                    reused: false
                    error: null
                    quote:
                      id: 7a3e9c52-1d84-4b06-8f2a-c5e0b9d17a43
                      lines:
                        - meter: bank_data_connection_month
                          unit: connection_month
                          price_usd: '0.9000'
                      fallback_lines: null
                      total_usd: '0.9000'
                      valid_until: '2026-11-21T13:00:00Z'
                      scopes:
                        - accounts
                        - balances
                        - transactions
                    vendor_data: client-7731
        '400':
          description: >-
            요청이 어떤 화면도 거치기 전에 거부되었습니다. `field`에는 수정할 항목이 표시됩니다. 허용 범위를 벗어난 값이나
            허용되지 않는 조합의 경우 `invalid_request`가 사용되며, 여기에 표시된 더 구체적인 코드도 사용됩니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Bank cannot keep access open:
                  summary: 은행이 액세스를 계속 열어 둘 수 없음
                  value:
                    code: ongoing_access_not_available
                    message: >-
                      This bank cannot keep access open. Use access one_time or
                      choose another bank.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: institution_id
                    next_action: create_link
                    retry_after: null
                History window ambiguous:
                  summary: 기록 기간이 모호함
                  value:
                    code: history_window_ambiguous
                    message: Send history_from or history_days, not both.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Redirect URL not registered:
                  summary: 리디렉션 URL이 등록되지 않음
                  value:
                    code: redirect_url_not_registered
                    message: >-
                      This redirect_url is not one of the return addresses
                      registered for your application. Addresses are matched
                      exactly (scheme, host, port, path and query); in sandbox a
                      plain http localhost address needs no registration. Send a
                      registered address, or leave redirect_url out (automatic
                      return to your page is then not promised).
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: redirect_url
                    next_action: null
                    retry_after: null
                Segment not available:
                  summary: 세그먼트를 사용할 수 없음
                  value:
                    code: segment_not_available
                    message: >-
                      This bank does not offer this kind of account through Bank
                      Link.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: segment
                    next_action: null
                    retry_after: null
                Window not available:
                  summary: 기간을 사용할 수 없음
                  value:
                    code: window_not_available
                    message: This bank cannot deliver the requested history window.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: 잘못된 요청
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: expires_in
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: 잔액이 견적 가격을 감당할 수 없습니다. 충전한 후 다시 시도하십시오.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Insufficient credits:
                  summary: 크레딧이 부족합니다
                  value:
                    code: insufficient_credits
                    message: The balance cannot cover the quoted price.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: top_up_balance
                    retry_after: null
        '403':
          description: 요청이 거부되었습니다. 계약에 이 국가의 요금이 없거나, API 키에 은행 데이터 권한이 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                No contract rate:
                  summary: 계약 요금 없음
                  value:
                    code: contract_rate_missing
                    message: Your contract has no rate for bank data in this country.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
                Bank data not allowed:
                  summary: 은행 데이터 접근이 허용되지 않음
                  value:
                    code: bank_data_access_denied
                    message: >-
                      Bank data calls need an API key that carries the Bank data
                      permission.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: enable_bank_data_access
                    retry_after: null
        '404':
          description: 이 애플리케이션과 환경에 리소스가 존재하지 않습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: 찾을 수 없음
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/bank/links/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "mode": "connect",
                "access": "ongoing",
                "country": "ESP",
                "segment": "business",
                "data": [
                  "accounts",
                  "balances",
                  "transactions"
                ],
                "history_from": "2026-01-01",
                "consent_days": 180,
                "ownership": {
                  "compare": "none"
                },
                "end_user": {
                  "reference": "client-7731",
                  "email": "ana@example.com"
                },
                "redirect_url": "https://app.example.com/bank/return",
                "allowed_origins": [
                  "https://app.example.com"
                ],
                "language": "es",
                "vendor_data": "client-7731"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.create_link(
                mode="connect",
                access="ongoing",
                country="ESP",
                segment="business",
                data=["accounts", "balances", "transactions"],
                history_from="2026-01-01",
                consent_days=180,
                ownership={
                    "compare": "none",
                },
                end_user={
                    "reference": "client-7731",
                    "email": "ana@example.com",
                },
                redirect_url="https://app.example.com/bank/return",
                allowed_origins=["https://app.example.com"],
                language="es",
                vendor_data="client-7731",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.bank.createLink({
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.CreateLink(ctx, didit.BankCreateLinkParams{\n\tBody: didit.BankLinkCreateRequest{\n\t\tMode:        didit.Some(didit.BankLinkCreateRequestMode(\"connect\")),\n\t\tAccess:      didit.Some(didit.BankLinkCreateRequestAccess(\"ongoing\")),\n\t\tCountry:     didit.String(\"ESP\"),\n\t\tSegment:     didit.Some(didit.BankLinkCreateRequestSegment(\"business\")),\n\t\tData:        didit.Some([]didit.BankLinkCreateRequestData{\"accounts\", \"balances\", \"transactions\"}),\n\t\tHistoryFrom: didit.String(\"2026-01-01\"),\n\t\tConsentDays: didit.Int(180),\n\t\tOwnership: didit.Some(didit.BankLinkOwnershipRequest{\n\t\t\tCompare: didit.Some(didit.BankLinkOwnershipRequestCompare(\"none\")),\n\t\t}),\n\t\tEndUser: didit.Some(didit.BankLinkEndUser{\n\t\t\tReference: didit.String(\"client-7731\"),\n\t\t\tEmail:     didit.String(\"ana@example.com\"),\n\t\t}),\n\t\tRedirectURL:    didit.String(\"https://app.example.com/bank/return\"),\n\t\tAllowedOrigins: didit.Some([]string{\"https://app.example.com\"}),\n\t\tLanguage:       didit.String(\"es\"),\n\t\tVendorData:     didit.String(\"client-7731\"),\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.time.LocalDate;

            import java.util.List;

            import me.didit.Didit;

            import me.didit.types.BankLinkCreateRequest;

            import me.didit.types.BankLinkEndUser;

            import me.didit.types.BankLinkOwnershipRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().createLink(BankLinkCreateRequest.builder()
                    .mode(BankLinkCreateRequest.Mode.of("connect"))
                    .access(BankLinkCreateRequest.Access.of("ongoing"))
                    .country("ESP")
                    .segment(BankLinkCreateRequest.Segment.of("business"))
                    .data(List.of(BankLinkCreateRequest.Data.of("accounts"), BankLinkCreateRequest.Data.of("balances"), BankLinkCreateRequest.Data.of("transactions")))
                    .historyFrom(LocalDate.parse("2026-01-01"))
                    .consentDays(180L)
                    .ownership(BankLinkOwnershipRequest.builder()
                            .compare(BankLinkOwnershipRequest.Compare.of("none"))
                            .build())
                    .endUser(BankLinkEndUser.builder()
                            .reference("client-7731")
                            .email("ana@example.com")
                            .build())
                    .redirectUrl("https://app.example.com/bank/return")
                    .allowedOrigins(List.of("https://app.example.com"))
                    .language("es")
                    .vendorData("client-7731")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->bank->createLink([
                'mode' => 'connect',
                'access' => 'ongoing',
                'country' => 'ESP',
                'segment' => 'business',
                'data' => ['accounts', 'balances', 'transactions'],
                'history_from' => '2026-01-01',
                'consent_days' => 180,
                'ownership' => [
                    'compare' => 'none',
                ],
                'end_user' => [
                    'reference' => 'client-7731',
                    'email' => 'ana@example.com',
                ],
                'redirect_url' => 'https://app.example.com/bank/return',
                'allowed_origins' => ['https://app.example.com'],
                'language' => 'es',
                'vendor_data' => 'client-7731',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.bank.create_link(
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.Bank.CreateLinkAsync(new
            BankLinkCreateRequest

            {
                Mode = new BankLinkCreateRequestMode("connect"),
                Access = new BankLinkCreateRequestAccess("ongoing"),
                Country = "ESP",
                Segment = new BankLinkCreateRequestSegment("business"),
                Data = new BankLinkCreateRequestData[] { "accounts", "balances", "transactions" },
                HistoryFrom = "2026-01-01",
                ConsentDays = 180,
                Ownership = new BankLinkOwnershipRequest
                {
                    Compare = new BankLinkOwnershipRequestCompare("none"),
                },
                EndUser = new BankLinkEndUser
                {
                    Reference = "client-7731",
                    Email = "ana@example.com",
                },
                RedirectUrl = "https://app.example.com/bank/return",
                AllowedOrigins = new string[] { "https://app.example.com" },
                Language = "es",
                VendorData = "client-7731",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        한 작업을 위해 직접 정하는 선택적 재시도 안전 키입니다. 최대 255자이며 UUID를 사용할 수 있습니다. 같은 키,
        엔드포인트, 쿼리, 본문으로 반복된 요청에는 첫 번째 응답이 같은 상태 코드와 같은 본문으로 반환되며, 다시 실행되거나 다시
        과금되지 않습니다. 같은 키를 다른 엔드포인트, 쿼리 또는 본문과 함께 사용하면 `409`
        `idempotency_key_reused`가 반환되고, 첫 번째 요청이 아직 실행 중이면 `Retry-After`와 함께
        `409` `idempotency_key_in_progress`가 반환됩니다. 실패한 요청(모든 `4xx` 또는 `5xx`)은
        저장되지 않으므로 같은 키로 다시 보낼 수 있습니다. 키는 API 키로 호출하든 액세스 토큰으로 호출하든 사용자의 애플리케이션에
        속합니다. [재시도 및 멱등성](/ko/integration/api-errors#재시도와-멱등성)을 참고하세요.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: 은행 링크를 생성합니다. 가장 간단한 요청은 원하는 값을 더한 `{}`입니다. 모든 필드에는 기본값이 있습니다.
      properties:
        mode:
          type: string
          enum:
            - connect
            - renew
          description: >-
            `connect`(기본값)는 새 연결을 만듭니다. `renew`는 `connection_id`가 필요하며 해당 연결의
            설정을 재사용합니다.
          default: connect
        connection_id:
          type: string
          description: '갱신할 연결입니다. `mode: renew`인 경우에만 사용합니다.'
          format: uuid
        access:
          type: string
          enum:
            - one_time
            - ongoing
          description: >-
            `one_time`(기본값)은 데이터를 한 번만 읽습니다. `ongoing`은 동의가 끝나거나 누군가 중단할 때까지 접근을
            유지합니다. `institution_id`를 설정하면, 지속적인 접근을 유지할 수 없는 은행은 화면을 띄우기 전에 `400
            ongoing_access_not_available`을 반환합니다. 설정하지 않으면 은행 선택 화면에는 지속적인 접근이
            가능한 은행만 표시됩니다.
          default: one_time
        country:
          type: string
          description: >-
            선택 사항입니다. 지정하지 않으면 사용자가 애플리케이션에서 활성화된 국가 중에서 선택합니다. Bank Link가 지원하는
            국가여야 하며, `ZZZ`를 포함한 그 외의 값은 `400 invalid_request`를 반환하며 `field:
            country`가 표시됩니다. 빈 요청 본문은 유효합니다.
          pattern: ^[A-Z]{3}$
        institution_id:
          type: string
          description: 선택 사항입니다. `list_institutions`에서 가져온 은행을 미리 선택하며, 선택 화면을 건너뜁니다.
          maxLength: 64
        segment:
          type: string
          enum:
            - personal
            - business
            - any
          description: 선택기를 필터링하고, 은행이 로그인을 구분하는 경우 어떤 로그인을 열지 은행에 알려 줍니다. 기본값은 `any`입니다.
          default: any
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: >-
            읽을 대상입니다. `accounts`는 항상 포함되며, 이름, 유형, 통화, 식별자와 은행이 공유하는 경우 보유자 이름이
            들어갑니다. 기본값은 `["accounts"]`입니다.
          default:
            - accounts
          maxItems: 3
        history_days:
          type: integer
          description: >-
            요청할 거래 내역의 일수입니다. 1에서 365 사이이며 기본값은 90입니다. 은행은 이보다 적게 제공할 수 있습니다. 각
            계좌는 실제로 제공한 기간을 `history_coverage`에 보고합니다. `history_from`과 함께 보낼 수
            없습니다.
          minimum: 1
          maximum: 365
          default: 90
        history_from:
          type: string
          description: >-
            `history_days` 대신 요청할 이력의 시작 날짜입니다. `history_days`와 함께 보낼 수 없으며, 둘을
            함께 보내면 `400 history_window_ambiguous`로 응답합니다. 365일보다 오래되었거나 미래인 날짜는
            `400 window_not_available`로 응답합니다.
          format: date
        extended_history:
          type: string
          enum:
            - standard
            - allow_extra_auth
          description: '`allow_extra_auth`를 사용하면 추가 확인을 한 번 더 요구하는 은행에서도 이전 내역을 제공받을 수 있습니다.'
          default: standard
        consent_days:
          type: integer
          description: >-
            지속 액세스에만 해당합니다. 은행에 액세스를 유지해 달라고 요청할 일수이며, 1 이상이어야 합니다. 기본값은 은행이
            허용하는 최대 기간입니다. 연결은 은행이 실제로 승인한 날짜를 `consent.expires_at`에 보고합니다.
            `access: one_time`을 사용하면 `400 invalid_request`를 반환하며 `field:
            consent_days`가 표시됩니다.
          minimum: 1
          maximum: 32767
        ownership:
          $ref: '#/components/schemas/BankLinkOwnershipRequest'
        end_user:
          $ref: '#/components/schemas/BankLinkEndUser'
        redirect_url:
          type: string
          description: >-
            브라우저가 마지막에 이동할 주소이며, `link_id`, `status`, 서명된 `state`가 함께
            전달됩니다(표시용으로만 사용하세요. webhook과 `get_link`가 공식 결과입니다). 샌드박스 애플리케이션에서는
            `localhost`, `127.0.0.1`, `[::1]`의 일반 `http` 주소(포트와 경로는 자유, 자격 증명과
            프래그먼트 없음)는 등록이 필요하지 않습니다. 그 밖의 주소는 `400
            redirect_url_not_registered`로 응답합니다. 다른 주소의 등록은 아직 제공되지 않습니다.
            `redirect_url`을 보내지 않으면 사용자는 Didit의 자체 결과 페이지에서 절차를 마칩니다.
          format: uri
          maxLength: 2048
        allowed_origins:
          type: array
          items:
            type: string
            format: uri
          description: >-
            현재 사용되지 않으며, 아직 출시되지 않은 Didit 내장 Bank Link를 위해 예약되어 있습니다. HTTPS 출처,
            최대 50개.
          maxItems: 50
        language:
          type: string
          description: 선택 사항입니다. `es` 또는 `pt-BR`과 같은 언어 코드입니다. 지정하지 않으면 브라우저 언어를 사용합니다.
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
          maxLength: 16
        vendor_data:
          type: string
          description: 귀사의 참조 값이며, 링크와 연결에 반환됩니다.
          maxLength: 255
        expires_in:
          type: integer
          description: 링크의 유효 기간을 초 단위로 나타내며, 300에서 86400 사이입니다. 기본값은 3600입니다.
          minimum: 300
          maximum: 86400
          default: 3600
        duplicates:
          type: string
          enum:
            - reuse
            - allow
          description: >-
            `reuse`(기본값)는 이미 공유 중인 계정으로 연결되는 링크를 해당 연결의 갱신으로 완료합니다. `allow`는 독립된
            두 번째 연결을 만듭니다.
          default: reuse
        allow_one_time_fallback:
          type: boolean
          description: >-
            `ongoing`과 함께 사용하면, 지속적인 접근을 유지할 수 없는 은행에서도 최종 사용자가 은행 화면에서 축소된 접근
            권한을 확인한 후 일회성 읽기로 계속 진행할 수 있습니다. 견적에는 그 비용이 표시됩니다. `access:
            ongoing`일 때만 사용할 수 있으며, 일회성 접근에서는 `400 invalid_request`와 `field:
            allow_one_time_fallback`을 반환합니다.
          default: false
        accept_reduced_grant:
          type: boolean
          description: >-
            은행 또는 사용자가 요청한 범위보다 적은 권한을 부여하는 경우, 링크를 완료하고 부여된 범위에 대해서만 요금을 부과합니다.
            그렇지 않으면 링크는 `reduced_grant`와 함께 `failed` 상태로 종료되며 요금은 부과되지 않습니다.
          default: false
        sandbox:
          type: object
          description: 샌드박스 애플리케이션에만 적용됩니다. Didit Test Bank 고객을 선택합니다. 라이브 애플리케이션에서는 무시됩니다.
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                Test Bank 고객입니다: `personal_basic`(현재 계좌 1개, 거래 내역 60건),
                `business_multi`(회사가 보유한 계좌 3개), `long_history`(400일 동안의 거래 내역
                1,400건이 있는 계좌 1개이며, 조회 시 최근 365일이 반환되므로 `history_days`를 365로
                설정하십시오), `pending`(대기 중인 거래 포함), `sparse_fields`(가치일, 거래 상대방
                IBAN, 은행 참조 번호가 없음) 또는 `no_ongoing`(일회성 접근만 허용하는 은행이며
                `allow_one_time_fallback`을 사용하십시오).
            switches:
              type: array
              items:
                type: string
                enum:
                  - partial_grant
                  - renewal_other_login
                  - expired_cursor
                  - webhook_twice
                  - midnight_booking
                  - blocked_popup
                  - bank_app_return
              description: 수락되며 샌드박스 시뮬레이터를 위해 예약되어 있습니다. 현재 이 값들은 아무것도 변경하지 않습니다.
    BankLink:
      type: object
      description: >-
        한 사용자를 위한 Bank Link의 실행 한 번입니다. 은행을 연결하거나 연결을 갱신합니다. 링크는 `get_link`로 직접
        확인하십시오. 브라우저가 보낸 id는 절대 신뢰하지 마십시오.
      properties:
        id:
          type: string
          description: 링크의 ID입니다.
          format: uuid
        mode:
          type: string
          enum:
            - connect
            - renew
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - created
            - opened
            - connecting
            - completed
            - cancelled
            - expired
            - failed
          description: 링크의 상태입니다. `completed`, `cancelled`, `expired`, `failed`는 최종 상태입니다.
        url:
          type: string
          description: >-
            사용자를 안내할 호스팅 페이지입니다. 링크를 생성할 때만 반환되며, 토큰이 저장되지 않으므로 이후 조회에서는
            `null`입니다.
          nullable: true
          format: uri
        client_token:
          type: string
          description: >-
            Didit의 임베디드 Bank Link용 토큰이며, 아직 출시되지 않았습니다. 현재는 `url`을 여십시오. 링크를 생성할
            때만 반환되며, 이후 조회에서는 `null`입니다. 용도가 단일하고 수명이 짧습니다. 개인 데이터를 포함하지 않습니다.
            절대 로그에 남기지 마십시오.
          nullable: true
        expires_at:
          type: string
          description: 사용되지 않은 링크가 작동을 멈추는 시점입니다.
          format: date-time
        connection_id:
          type: string
          description: '`status`가 `completed`일 때 이 링크로 생성되거나 갱신된 연결입니다.'
          format: uuid
          nullable: true
        check_id:
          type: string
          description: 이 링크에서 `ownership.compare`를 `none` 이외의 값으로 요청한 경우의 소유 구조 결과입니다.
          format: uuid
          nullable: true
        reused:
          type: boolean
          description: >-
            사용자가 정확히 이 계정들을 이미 공유하고 있어서 링크가 기존 연결의 갱신으로 완료된 경우
            `true`입니다(`duplicates: reuse`). 이중으로 요금이 청구되지 않습니다.
        error:
          allOf:
            - $ref: '#/components/schemas/BankLinkError'
          nullable: true
          description: '`status`가 `failed`인 경우 링크가 실패한 이유입니다. 그렇지 않으면 `null`입니다.'
        quote:
          $ref: '#/components/schemas/BankLinkQuote'
        vendor_data:
          type: string
          description: 요청에 있던 귀사의 참조 값입니다.
          nullable: true
      required:
        - id
        - mode
        - access
        - status
        - url
        - client_token
        - expires_at
        - connection_id
        - check_id
        - reused
        - error
        - quote
        - vendor_data
    BankDataError:
      type: object
      description: 모든 은행 데이터 작업의 오류 본문입니다. 모든 필드가 항상 포함됩니다.
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: 기계가 읽을 수 있는 오류 코드입니다. 분기 처리는 이 값으로 하고, `message`로는 하지 마십시오.
        message:
          type: string
          description: 개발자를 위한 쉬운 설명입니다. 문구는 변경될 수 있으므로 파싱하지 않아야 합니다.
        request_id:
          type: string
          description: 이 요청의 ID입니다. 지원팀에 문의할 때 이 값을 알려 주십시오.
        field:
          type: string
          description: 오류가 하나의 필드와 관련된 경우 수정해야 할 요청 필드입니다. 그렇지 않으면 `null`입니다.
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: 클라이언트가 추측하지 않고 조치할 수 있도록 다음 단계를 안내합니다. 표준 다음 단계가 없으면 `null`입니다.
          nullable: true
        retry_after:
          type: integer
          description: 재시도 전에 기다릴 시간(초)입니다. 속도 제한 및 일시적 오류에 설정되며, 그 외에는 `null`입니다.
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankLinkOwnershipRequest:
      type: object
      description: 선택 사항입니다. 계좌 소유자를 개인 또는 기업과 비교합니다.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
          description: >-
            계좌 보유자를 비교할 대상입니다. `none`(기본값)은 판정을 제공하지 않으며 참조가 필요하지 않습니다.
            `person`은 `reference_identity` 또는 `session_id`가 필요합니다. `business`는
            `business` 또는 `business_session_id`가 필요합니다. 비교하려는 종류의 참조를 정확히 하나만
            보내며, `none`을 사용하는 경우에는 어떤 참조도 보내지 않습니다.
          default: none
        match:
          type: string
          enum:
            - any_holder
            - all_holders
          description: >-
            법적 보유자 한 명이 일치해야 하는지, 모든 법적 보유자가 일치해야 하는지 나타냅니다. 대리인은 어떤 경우에도 계산에
            포함되지 않습니다.
          default: any_holder
        reference_identity:
          type: object
          description: 계정 소유자와 비교할 호출자가 제공한 값입니다. `session_id`와 함께 보낼 수 없습니다.
          properties:
            full_name:
              type: string
              maxLength: 255
            date_of_birth:
              type: string
              format: date
            address:
              type: string
              maxLength: 500
            phone:
              type: string
              maxLength: 64
            email:
              type: string
              maxLength: 255
        session_id:
          type: string
          description: 비교할 사용자의 완료된 Didit 인증 세션입니다. `reference_identity`와 함께 보낼 수 없습니다.
          format: uuid
        business:
          type: object
          description: 계좌 소유자와 비교할 기업입니다.
          properties:
            legal_name:
              type: string
              maxLength: 255
            registration_id:
              type: string
              maxLength: 128
          required:
            - legal_name
        business_session_id:
          type: string
          description: 비교할 Didit 기업 확인(KYB)입니다. `business`와 함께 보낼 수 없습니다.
          format: uuid
    BankLinkEndUser:
      type: object
      description: 계정을 연결하는 개인 또는 기업입니다.
      properties:
        reference:
          type: string
          description: >-
            해당 개인 또는 회사에 대해 귀사가 사용하는 자체 ID입니다. `end_user_reference`로 검색할 수 있으며,
            반복 연결을 식별하는 데 사용됩니다.
          maxLength: 255
        email:
          type: string
          description: >-
            선택 사항입니다. 은행 경로에 개인의 인증된 주소가 필요하고 주소를 보내지 않은 경우, Bank Link가 개인에게 주소를
            요청합니다. 마케팅 용도로는 절대 사용하지 않습니다.
          format: email
          maxLength: 254
    BankLinkError:
      type: object
      description: 링크가 `failed`로 종료된 이유입니다. 아무것도 게시되거나 청구되지 않았습니다.
      properties:
        code:
          type: string
          enum:
            - duplicate_conflict
            - renewal_login_mismatch
            - reduced_grant
            - corporate_approval_not_supported
            - ongoing_access_not_available
            - bank_unavailable
            - bank_cancelled
            - consent_declined
            - read_limit
            - renewal_not_needed
            - renewal_window_expired
            - first_sync_failed
          description: >-
            링크가 실패한 이유입니다. 실패한 링크는 HTTP 오류가 아닙니다. 링크는 `status: failed`와 이 객체와 함께
            반환됩니다. 그 사이 연결이 변경된 갱신 링크는 `renewal_not_needed` 또는
            `renewal_window_expired`로 반환됩니다.
        message:
          type: string
          description: 개발자를 위한 쉬운 설명입니다.
        conflicts_with:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: >-
            `duplicate_conflict`와 함께 제공되며, 겹치는 활성 연결의 ID입니다. 이 중 하나를 갱신하거나,
            `duplicates: allow`를 사용해 링크를 다시 생성하십시오.
      required:
        - code
        - message
        - conflicts_with
    BankLinkQuote:
      type: object
      description: 링크 생성 시 고정되는 링크 가격입니다. 청구되는 금액은 견적의 금액입니다. 조회는 절대 과금되지 않습니다.
      properties:
        id:
          type: string
          description: 견적의 ID입니다.
          format: uuid
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: 요청한 범위에 대해 이 링크가 청구하는 항목입니다.
        fallback_lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            `allow_one_time_fallback`으로 링크를 생성한 경우에만 일회성 대체 시 청구될 금액입니다. 생성 응답에
            표시되며, 그렇지 않으면 `null`입니다. 데이터를 포함한 일회성 조회는 지속적인 액세스의 첫 달 비용보다 더 많이 들
            수 있습니다.
        total_usd:
          type: string
          description: >-
            `lines`의 USD 합계입니다. 합계는 줄어들 수만 있으며, 부여된 권한이 축소되거나 사용자가 가격이 더 낮은 국가를
            선택하는 경우에 해당합니다.
          pattern: ^-?\d+(\.\d+)?$
        valid_until:
          type: string
          description: 견적은 링크에 고정되며 링크의 전체 유효 기간 동안 유효하므로 `expires_at`과 같습니다.
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: 데이터 범위가 견적 가격을 산정합니다.
      required:
        - id
        - lines
        - fallback_lines
        - total_usd
        - valid_until
        - scopes
    RateLimitBudgetError:
      type: object
      description: >-
        속도 제한 미들웨어 예산 거부 응답에만 반환됩니다. 멱등성 충돌과 엔드포인트별 상한을 포함한 다른 429 오류는 이 메타데이터
        필드를 보장하지 않습니다.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: 기존의 사람이 읽을 수 있는 예산 거부 메시지입니다.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: 불투명한 지원 참조 번호입니다. RL- 뒤에 소문자 UUID 16진수 문자 32자가 이어집니다.
        limit:
          type: integer
          description: 초과된 범위의 예산입니다. X-RateLimit-Limit 값과 같습니다.
        remaining:
          type: integer
          minimum: 0
          description: 남은 예산이며 0 미만으로 내려가지 않습니다. X-RateLimit-Remaining과 같습니다.
        reset:
          type: integer
          format: int64
          description: Unix 초 단위의 윈도우 재설정 시간이며 X-RateLimit-Reset 값과 같습니다.
        window_seconds:
          type: integer
          description: 고정 윈도우 기간(초 단위)이며, 남은 대기 시간이 아닙니다. 재시도하기 전에 Retry-After 값을 준수해야 합니다.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankLinkQuoteLine:
      type: object
      description: 견적의 개별 요금 항목 하나입니다.
      properties:
        meter:
          type: string
          description: >-
            무엇에 대해 요금이 부과되는지 나타냅니다. 예: `bank_data_connection_month`,
            `bank_verification`.
          example: bank_data_connection_month
        unit:
          type: string
          description: '과금 단위 하나가 무엇인지 나타냅니다. 예: `connection_month` 또는 `completed_sign_in`.'
          example: connection_month
        price_usd:
          type: string
          description: 단위당 요금(USD)이며, 소수점 4자리 문자열입니다. 예시의 금액은 참고용이며, 국가별 요금은 요금 페이지에 표시됩니다.
          pattern: ^-?\d+(\.\d+)?$
          example: '0.9000'
      required:
        - meter
        - unit
        - price_usd
  responses:
    Unauthorized:
      description: 인증되지 않음
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: 잘못된 API 키
              value:
                detail: Invalid API Key.
    RateLimitedWrite:
      description: >-
        API 키당 분당 300건으로 정해진 공유 쓰기 요청 한도를 초과했습니다. 재시도하기 전에 `Retry-After`를 준수해야
        합니다.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 300
            remaining: 0
            reset: 1794358860
            window_seconds: 60
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
    BankDataInternalError:
      description: >-
        Didit 측에서 문제가 발생했습니다. `/v3/bank/` 아래의 예기치 않은 오류는 HTML 페이지가 아닌 Bank 오류
        형식으로 응답합니다. 지원팀에 `request_id`를 알려 주십시오.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: 예상치 못한 오류
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  headers:
    BudgetRetryAfter:
      description: 다음 윈도우까지 기다려야 하는 시간(초)을 올림한 값입니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: 예산을 초과한 범위입니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: 초과된 범위의 예산입니다. 본문 한도와 같습니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: 남은 예산이며 0 미만으로 내려가지 않습니다. 본문의 remaining과 같습니다. 미들웨어 예산 거부 응답에만 있습니다.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: Unix 초 단위의 재설정 시간이며 본문의 reset 값과 같습니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        귀사 애플리케이션의 API 키입니다. Business Console의 Developers -> API keys에서 확인할 수
        있습니다. 기본 키는 모든 권한을 가집니다. 명명된 키는 범위를 지정할 수 있습니다. 리소스별로 권한 없음, 읽기 또는 쓰기를
        설정할 수 있고, 일부 워크플로나 승인된 세션으로 제한할 수 있으며, 허용된 IP 목록으로 제한할 수 있고, 만료일을 설정할 수
        있습니다. 401은 키가 잘못되었거나, 취소되었거나, 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스
        또는 작업에 대한 권한이 없거나, 요청이 IP 목록 밖의 주소에서 왔음을 의미합니다. 세션 경로에서 발생한 404는 세션이 키의
        워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 동영상 및 PDF URL을 null로
        받으며, 세션 쓰기 권한이 없는 키는 세션 링크와 토큰을 null로 받습니다. 자세한 내용은
        https://docs.didit.me/console/api-keys 를 참조합니다.

````

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