> ## 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.

# 创建银行链接 API：连接或续期银行

> Didit 的创建银行链接端点会在您的服务器上启动一次银行链接流程，并返回用户连接银行所用的托管 URL。

Didit 的创建 Bank Link 端点会在您的服务器上启动一次 Bank Link 流程，用于连接银行或续期连接，并返回托管页面的 `url`。
每个字段都有默认值，因此最简请求就是 `{}`，再加上您需要的字段。
请将返回的 `id` 与您的用户关联保存，并通过[获取银行链接](https://docs.didit.me/zh/standalone-apis/bank-link-get.md)或 `bank.link.completed` Webhook 自行确认结果。
请参阅[快速开始](https://docs.didit.me/zh/core-technology/bank-verification/quickstart.md)和[Bank Link](https://docs.didit.me/zh/core-technology/bank-verification/bank-link.md)。


## OpenAPI

````yaml zh/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: >-
      银行数据服务涵盖银行链接、连接、账户、余额、交易、机构和覆盖范围。银行数据可用于沙盒应用。在宣布开放生产访问之前，生产应用的调用将返回
      `404`。沙盒环境不收费。使用 API
      密钥进行的调用，需要具备银行数据权限（`bank-data`）的密钥：读取操作需要读取权限，会更改数据的操作需要写入权限。账户核验是例外，它需要会话的写入权限或完全访问权限，而不需要银行数据权限。银行数据不属于完全访问权限的一部分：完全访问密钥会被拒绝，调用返回
      `403
      bank_data_access_denied`，直到您创建具备该权限的密钥为止。原始银行数据（账户、余额、交易以及变更流）同样会拒绝不携带 API
      密钥的请求。


      除账户核验外，`/v3/bank/` 下的每个拒绝响应都具有相同的 JSON
      结构（`code`、`message`、`request_id`、`field`、`next_action`、`retry_after`）。不是操作的路径、不是
      UUID 的 ID 或未知的子资源，对于所有方法都返回 `404 not_found`；任何意外错误都返回 `500 internal_error`
      及 `request_id`。在银行数据不可用时，每个操作都返回平台标准的 `404`，与访问未知路由时完全相同。
paths:
  /v3/bank/links/:
    post:
      tags:
        - Bank Data
      summary: 创建银行链接
      description: >-
        创建 Bank Link：即一次流程运行，用户在其中连接银行或续期连接。将用户引导至 `url`。`client_token` 用于 Didit
        的嵌入式 Bank Link，目前尚未发布：今天请打开 `url`。完成的链接会生成一个连接。


        最小请求为 `{}` 加上您需要的字段。默认值：`mode` 为 connect，`access` 为 one_time，`data` 仅为
        accounts，`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: 请求被拒绝：您的合同未包含该国家/地区的费率，或密钥缺少银行数据权限。
          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）。使用相同密钥、endpoint、查询参数和请求体重复发送的请求，会返回第一次的响应，状态码和响应体均相同，且不会再次运行或计费。同一密钥若用于其他
        endpoint、查询参数或请求体，将返回 `409` `idempotency_key_reused`；若第一个请求仍在处理中，则返回
        `409` `idempotency_key_in_progress` 及 `Retry-After`。失败的请求（任何 `4xx` 或
        `5xx`）不会被存储，因此您可以使用相同密钥再次发送。无论您使用 API 密钥还是访问 token
        调用，密钥都归属于您的应用。请参阅[重试与幂等性](/zh/integration/api-errors#重试与幂等性)。
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: 创建 Bank Link。最小请求为 `{}` 加上您需要的字段：每个字段都有默认值。
      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: >-
            如果银行或用户授予的权限少于您的请求，请完成链接并仅对已授予的权限计费。否则链接以 `failed` 结束，并带有
            `reduced_grant`，且不产生任何费用。
          default: false
        sandbox:
          type: object
          description: 仅限沙盒应用：选择 Didit 测试银行客户。在生产应用中忽略。
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                测试银行客户：`personal_basic`（一个活期账户，60
                笔交易）、`business_multi`（企业持有的三个账户）、`long_history`（一个账户，包含 400 天和
                1,400 笔交易；读取时返回最近 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: 为单个用户执行的一次银行链接运行：连接银行，或续期连接。请使用 `get_link` 自行确认链接，切勿信任浏览器发送的 ID。
      properties:
        id:
          type: string
          description: 链接的标识符。
          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 嵌入式银行链接的令牌，目前尚未发布：今天请打开 `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: >-
            当用户已共享完全相同的账户，链接因而作为现有连接的续期完成时（`duplicates: reuse`），返回
            `true`。不会重复收费。
        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: 本次请求的标识符。联系支持团队时请提供此标识符。
        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 企业验证。不能与 `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: 报价的标识符。
          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` 的合计金额（美元）。合计金额只会下降：当授权额度减少，或用户选择价格较低的国家/地区时。'
          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- 后跟 32 个小写 UUID 十六进制字符。
        limit:
          type: integer
          description: 超出限额的作用域对应的预算；与 X-RateLimit-Limit 相同。
        remaining:
          type: integer
          minimum: 0
          description: 剩余额度，下限为零；与 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 页面：请将 `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: 剩余额度，下限为零；与响应体中的 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 的开发者 -> API
        密钥中获取。主密钥拥有完全访问权限。命名密钥可以设置范围：可按资源设置无权限、只读或读写，可限定为部分工作流或已批准的会话，可限定为一组 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.