跳转到主要内容
POST
curl
在生产环境中,账户核验支持尼日利亚、加纳和肯尼亚。 其他国家的请求会返回 404 和 code: country_not_covered,且不计费。 更多国家将陆续开放,银行验证定价始终显示各国当前提供的服务。
您的后端发送姓名和账户,并读取结果。它相当于银行验证步骤中的账户核验,但不包含本人验证。

按各国的书写方式提供账户信息

部分国家还要求提供 bic;企业账户还需提供 registration_id。空格、短横线和点号会被忽略。如果某个国家的核验所需的键缺失,将返回 400 并指明该字段,例如 "field": "account.bank_code", "reason": "required"。 要核验个人账户,请发送 holder.full_name;要核验企业账户,请发送 holder.business_name。

发送账户持有人的同意

在某些国家,每次账户核验前都需要账户持有人的明确同意。 请在您的产品中征得同意,然后发送 "consent": true。 如果未发送,这些国家的核验请求将被拒绝,返回 400(field: consent,reason: required),且不计费。 在其他国家,consent 为可选项;如果您发送了该字段,Didit 会将其与该次核验的费用一并记录。 沙盒密钥与正式密钥在同样的国家要求同意。

读取结果

计费与重试

银行做出应答的每次核验,均按该账户所在国家的账户核验价格计费一次,无论结果如何。返回错误的请求不计费:请求体被拒绝(400)、额度不足(402)、账户暂不支持核验(404)或银行无法应答(503)。 没有幂等键,也没有可用于回读核验结果的 endpoint。重试的请求会执行一次新的核验,并生成新的 request_id,且会再次计费,因此请务必保存响应。Didit 仅存储费用记录,包括请求 ID、国家、结果和脱敏后的账户,绝不存储姓名或完整的账号。

在沙盒中测试

沙盒 API 密钥不会调用银行,也不产生任何费用。若存在 IBAN,则取其最后 4 个字符;否则取账号的最后 4 个字符,以决定返回的结果: IBAN、CLABE 和 CBU 包含校验位。请使用通过所有格式校验的沙盒示例值。

访问方式

使用应用的 x-api-key 进行身份验证,或使用其客户端凭证 bearer token(持有者 token)。限定范围的 API 密钥需要具备会话的写入权限。该 endpoint 与其他接口共享写入限制,即每个 API 密钥每分钟 300 次请求。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
country
string
必填

账户所在的国家/地区,采用 ISO 3166-1 alpha-3 代码,例如 NGA。支持小写。

Required string length: 3
示例:

"NGA"

account
object
必填

按所在国家/地区记录方式填写的账户:iban,或带有该国家/地区所需银行代码或分支机构代码(sort_code、routing_number、transit_institution、bsb、ifsc、bank_code 或 bic)的 account_number。墨西哥使用 clabe,阿根廷使用 cbu_cvu,这两者已标识银行。如果所在国家/地区有要求,企业账户需添加 registration_id。空格、短横线和点号将被忽略。该国家/地区的核验中未使用的键将被忽略;如果缺少其所需的键,则会返回指明该键的 400。

示例:
holder
object
必填

核对账户所依据的名称。full_name 和 business_name 中仅能传入一个。

vendor_data
string | null

您为此项检查指定的自身参考编号,将原样返回。

示例:

"payout_20481"

当账户持有人明确同意此项核查时设为 true。在账户核查需要此类同意的国家/地区为必填项:若未提供,核查将被拒绝并返回 400(其 field 为 consent,reason 为 required),且不计费。在其他国家/地区此项为选填,当您发送时,Didit 会将其与核查费用一同记录。

示例:

true

响应

银行已响应。无论结果如何,该核验均会计费。

request_id
string<uuid>
必填

此检查的 ID。

result
enum<string>
必填

match:银行持有以您发送的姓名开设的账户。close_match:以相近姓名开设,例如缺少中间名或有拼写错误。no_match:以其他姓名开设,或不存在此类账户。cannot_verify:银行未比对姓名即返回响应,例如账户已被冻结或注销。

可用选项:
match,
close_match,
no_match,
cannot_verify
holder_name
string | null
必填

仅在 close_match 时,且仅在银行返回时提供:银行记录中的账户名称。其他情况下为 null。

account
string
必填

账户,已脱敏并仅保留后 4 位字符。

vendor_data
string | null
必填

您的自身参考编号,与您发送的内容一致。

created_at
string<date-time>
必填

检查运行的时间,以 UTC 表示。

最后修改于 2026年11月7日