跳转到主要内容
POST
curl
Didit 的创建 Bank Link 端点会在您的服务器上启动一次 Bank Link 流程,用于连接银行或续期连接,并返回托管页面的 url。 每个字段都有默认值,因此最简请求就是 {},再加上您需要的字段。 请将返回的 id 与您的用户关联保存,并通过获取银行链接或 bank.link.completed Webhook 自行确认结果。 请参阅快速开始和Bank Link。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的开发者 -> API 密钥中获取。主密钥拥有完全访问权限。命名密钥可以设置范围:可按资源设置无权限、只读或读写,可限定为部分工作流或已批准的会话,可限定为一组 IP 地址,并可设置过期日期。401 表示密钥错误、已被撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或执行该操作,或请求来自其 IP 列表之外的地址;会话相关路由返回 404,表示该会话不在密钥的工作流或状态范围内。没有媒体访问权限的密钥会将图片、视频和 PDF 的 URL 返回为 null;没有会话写入权限的密钥会将会话链接和令牌返回为 null。请参阅 https://docs.didit.me/console/api-keys。

请求头

Idempotency-Key
string

您为单次操作选择的可选重试安全密钥,最长 255 个字符(可使用 UUID)。使用相同密钥、endpoint、查询参数和请求体重复发送的请求,会返回第一次的响应,状态码和响应体均相同,且不会再次运行或计费。同一密钥若用于其他 endpoint、查询参数或请求体,将返回 409 idempotency_key_reused;若第一个请求仍在处理中,则返回 409 idempotency_key_in_progress 及 Retry-After。失败的请求(任何 4xx 或 5xx)不会被存储,因此您可以使用相同密钥再次发送。无论您使用 API 密钥还是访问 token 调用,密钥都归属于您的应用。请参阅重试与幂等性。

Required string length: 1 - 255

请求体

application/json

创建 Bank Link。最小请求为 {} 加上您需要的字段:每个字段都有默认值。

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

如果银行或用户授予的权限少于您的请求,请完成链接并仅对已授予的权限计费。否则链接以 failed 结束,并带有 reduced_grant,且不产生任何费用。

sandbox
object

仅限沙盒应用:选择 Didit 测试银行客户。在生产应用中忽略。

响应

链接已创建。

为单个用户执行的一次银行链接运行:连接银行,或续期连接。请使用 get_link 自行确认链接,切勿信任浏览器发送的 ID。

id
string<uuid>
必填

链接的标识符。

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 嵌入式银行链接的令牌,目前尚未发布:今天请打开 url。仅在创建链接时返回;之后的读取中为 null。用途单一且有效期短,不包含任何个人数据。切勿记录该令牌。

expires_at
string<date-time>
必填

未使用的链接失效的时间。

connection_id
string<uuid> | null
必填

当 status 为 completed 时,该链接所创建或续期的连接。

check_id
string<uuid> | null
必填

当请求了 ownership.compare(值不为 none)时,此链接的股权结构比对结果。

reused
boolean
必填

当用户已共享完全相同的账户,链接因而作为现有连接的续期完成时(duplicates: reuse),返回 true。不会重复收费。

error
object | null
必填

当 status 为 failed 时,链接失败的原因。否则为 null。

quote
object
必填

链接的价格,在创建时固定。收取的费用为报价的金额。读取操作从不计费。

vendor_data
string | null
必填

请求中的您方引用。

最后修改于 2026年11月22日