> ## 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. # EUDI 钱包验证 API > 借助 Didit 将 EUDI 钱包身份验证集成到您自己的应用中。查看国家/地区覆盖范围、认证步骤、结果和定价。 从后端使用您的应用 API 密钥启动 EUDI 钱包验证。 您不需要工作流或 `workflow_id`。 开始请求的响应描述的是下一步身份认证操作，并不是已通过的身份认证结果。 ## 覆盖范围与激活 | 属性 | 值 | | - | - | | 钱包 | EUDI Wallet | | 钱包 ID | `eudi` | | 国家/地区 | ![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/at.svg)奥地利、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/be.svg)比利时、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/bg.svg)保加利亚、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/hr.svg)克罗地亚、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/cy.svg)塞浦路斯、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/cz.svg)捷克、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/dk.svg)丹麦、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/ee.svg)爱沙尼亚、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/fi.svg)芬兰、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/fr.svg)法国、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/de.svg)德国、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/gr.svg)希腊、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/hu.svg)匈牙利、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/ie.svg)爱尔兰、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/it.svg)意大利、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/lv.svg)拉脱维亚、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/lt.svg)立陶宛、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/lu.svg)卢森堡、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/mt.svg)马耳他、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/nl.svg)荷兰、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/pl.svg)波兰、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/pt.svg)葡萄牙、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/ro.svg)罗马尼亚、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/sk.svg)斯洛伐克、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/si.svg)斯洛文尼亚、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/es.svg)西班牙、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/se.svg)瑞典、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/is.svg)冰岛、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/li.svg)列支敦士登、![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/no.svg)挪威 | | 生产环境钱包激活 | ⏳ 即将推出 | | 已发布的钱包价格 | 即将推出 | 钱包激活独立于 API 部署以及您的应用是否符合资格。 对于标注为即将推出的钱包，即使文档中列出了 endpoint，也不会因此激活该钱包。 当前已发布的费率，请参阅[数字身份钱包定价](https://docs.didit.me/zh/getting-started/pricing.md#数字身份钱包定价)。 ## 用户需要做什么 按照启动请求返回的下一步操作执行。 钱包的认证体验决定用户使用浏览器、其他设备还是应用。 ## 接收结果 请参阅[数字身份钱包 API 指南](https://docs.didit.me/zh/standalone-apis/digital-id-wallets.md)，以跟踪验证进度并获取其结果。 只有已完成且已验证的结果，才能作为钱包已完成对用户身份认证的证明。 返回的身份属性因钱包而异；请勿假设一定会返回地址、肖像或所有所请求的属性。 ## 相关内容 * [数字身份钱包 API](https://docs.didit.me/zh/standalone-apis/digital-id-wallets.md) * [钱包覆盖范围与属性](https://docs.didit.me/zh/core-technology/id-verification/digital-id-wallets.md) * [定价](https://docs.didit.me/zh/getting-started/pricing.md#数字身份钱包定价) ## OpenAPI ````yaml zh/openapi-25.json POST /v3/id-verification/wallets/eudi/ 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: [] paths: /v3/id-verification/wallets/eudi/: post: tags: - Digital ID wallets summary: 开始 EUDI Wallet 验证 description: >- 在不使用任何工作流的情况下发起 EUDI Wallet 登录（用户所属的成员国；签发机构因国家/地区而异；AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。 operationId: start_eudi_wallet_verification parameters: - in: header name: Idempotency-Key schema: type: string description: >- 可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。 requestBody: content: application/json: schema: $ref: >- #/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest example: country: AUT vendor_data: your-customer-reference metadata: reference: example return_url: https://app.example.com/identity/complete application/x-www-form-urlencoded: schema: $ref: >- #/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest multipart/form-data: schema: $ref: >- #/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest required: true responses: '201': content: application/json: schema: $ref: >- #/components/schemas/DigitalIdWalletApiWalletVerificationResponse example: request_id: 00000000-0000-4000-8000-000000000001 wallet_verification: wallet: id: eudi name: EUDI Wallet issuing_authority: >- The user's own member state; the issuer differs per country country: AUT status: Not Finished outcome: pending error: null interaction: redirect simulated: false expires_at: '2026-01-01T10:10:00Z' next_action: type: redirect url: https://wallet.example.com/authorize identity: null attributes: null level_of_assurance: null verified_at: null signature_valid: null credential_type: person_identification vendor_data: your-customer-reference metadata: reference: example created_at: '2026-01-01T10:00:00Z' description: '' '400': content: application/json: schema: $ref: >- #/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest description: >- 字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。 '403': content: application/json: schema: $ref: >- #/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden description: >- 缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。 '409': content: application/json: schema: $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError' description: >- 错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。 '502': content: application/json: schema: $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError' description: 错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。 '503': content: application/json: schema: $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError' description: 错误 wallet_not_configured：此环境无法访问该钱包。 security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl --request POST \ --url https://verification.didit.me/v3/id-verification/wallets/eudi/ \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Idempotency-Key: your-unique-attempt-key' \ --header 'Content-Type: application/json' \ --data '{ "country": "AUT", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_wallets.start_eudi( vendor_data="your-customer-reference", metadata={"reference": "example"}, country="AUT", return_url="https://app.example.com/identity/complete", ) 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.idWallets.startEudi({ vendor_data: "your-customer-reference", metadata: { reference: "example" }, country: "AUT", return_url: "https://app.example.com/identity/complete", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEudi(ctx, didit.IDWalletsStartEudiParams{\n\tBody: didit.DigitalIDWalletAPIEudiWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIEudiWalletVerificationStartCountryEnum(\"AUT\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.Map; import me.didit.Didit; import me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartCountryEnum; import me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idWallets().startEudi(DigitalIdWalletApiEudiWalletVerificationStartRequest.builder() .vendorData("your-customer-reference") .metadata(Map.of("reference", "example")) .country(DigitalIdWalletApiEudiWalletVerificationStartCountryEnum.of("AUT")) .returnUrl("https://app.example.com/identity/complete") .build()); System.out.println(result); - lang: php label: PHP source: |- idWallets->startEudi([ 'vendor_data' => 'your-customer-reference', 'metadata' => ['reference' => 'example'], 'country' => 'AUT', 'return_url' => 'https://app.example.com/identity/complete', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_wallets.start_eudi( vendor_data: "your-customer-reference", metadata: { reference: "example" }, country: "AUT", return_url: "https://app.example.com/identity/complete" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdWallets.StartEudiAsync(new DigitalIdWalletApiEudiWalletVerificationStartRequest { VendorData = "your-customer-reference", Metadata = new Dictionary { ["reference"] = "example" }, Country = "AUT", ReturnUrl = "https://app.example.com/identity/complete", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DigitalIdWalletApiEudiWalletVerificationStartRequest: type: object description: >- 发起 EUDI Wallet 验证（AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR）。 properties: vendor_data: type: string nullable: true description: 您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。 metadata: type: object additionalProperties: {} nullable: true description: 与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。 sandbox_scenario: type: string minLength: 1 description: >- 仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。 country: allOf: - $ref: >- #/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartCountryEnum description: |- EUDI Wallet 身份的 ISO 3166-1 alpha-3 国家/地区代码。 * `AUT` - AUT * `BEL` - BEL * `BGR` - BGR * `HRV` - HRV * `CYP` - CYP * `CZE` - CZE * `DNK` - DNK * `EST` - EST * `FIN` - FIN * `FRA` - FRA * `DEU` - DEU * `GRC` - GRC * `HUN` - HUN * `IRL` - IRL * `ITA` - ITA * `LVA` - LVA * `LTU` - LTU * `LUX` - LUX * `MLT` - MLT * `NLD` - NLD * `POL` - POL * `PRT` - PRT * `ROU` - ROU * `SVK` - SVK * `SVN` - SVN * `ESP` - ESP * `SWE` - SWE * `ISL` - ISL * `LIE` - LIE * `NOR` - NOR return_url: type: string format: uri minLength: 1 description: >- 用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。 maxLength: 2048 device: allOf: - $ref: '#/components/schemas/DigitalIdWalletApiDeviceEnum' default: same_device description: |- 用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。 * `same_device` - same_device * `cross_device` - cross_device required: - country - return_url DigitalIdWalletApiWalletVerificationResponse: type: object description: 单次独立钱包验证，正如每个钱包 endpoint 返回的结果一样。 properties: request_id: type: string format: uuid wallet_verification: $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationResult' vendor_data: type: string nullable: true metadata: type: object additionalProperties: {} nullable: true description: 启动时发送的元数据对象，或 null。 created_at: type: string format: date-time required: - created_at - metadata - request_id - vendor_data - wallet_verification DigitalIdWalletApiWalletVerificationStartBadRequest: oneOf: - $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError' - $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationFieldErrors' DigitalIdWalletApiWalletVerificationStartForbidden: oneOf: - $ref: >- #/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage - $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError' DigitalIdWalletApiWalletVerificationError: type: object properties: error: type: string description: 稳定的机器可读代码，例如 wallet_unavailable。 detail: type: string required: - detail - error DigitalIdWalletApiEudiWalletVerificationStartCountryEnum: enum: - AUT - BEL - BGR - HRV - CYP - CZE - DNK - EST - FIN - FRA - DEU - GRC - HUN - IRL - ITA - LVA - LTU - LUX - MLT - NLD - POL - PRT - ROU - SVK - SVN - ESP - SWE - ISL - LIE - NOR type: string description: |- * `AUT` - AUT * `BEL` - BEL * `BGR` - BGR * `HRV` - HRV * `CYP` - CYP * `CZE` - CZE * `DNK` - DNK * `EST` - EST * `FIN` - FIN * `FRA` - FRA * `DEU` - DEU * `GRC` - GRC * `HUN` - HUN * `IRL` - IRL * `ITA` - ITA * `LVA` - LVA * `LTU` - LTU * `LUX` - LUX * `MLT` - MLT * `NLD` - NLD * `POL` - POL * `PRT` - PRT * `ROU` - ROU * `SVK` - SVK * `SVN` - SVN * `ESP` - ESP * `SWE` - SWE * `ISL` - ISL * `LIE` - LIE * `NOR` - NOR DigitalIdWalletApiDeviceEnum: enum: - same_device - cross_device type: string description: |- * `same_device` - 同一设备 * `cross_device` - 跨设备 DigitalIdWalletApiWalletVerificationResult: type: object properties: wallet: allOf: - $ref: '#/components/schemas/DigitalIdWalletApiWallet' readOnly: true country: type: string status: type: string description: 待处理时为未完成，随后为已通过（已核验）或已拒绝。 outcome: $ref: >- #/components/schemas/DigitalIdWalletApiWalletVerificationResultOutcomeEnum error: type: string nullable: true readOnly: true interaction: allOf: - $ref: '#/components/schemas/DigitalIdWalletApiInteractionEnum' readOnly: true simulated: type: boolean readOnly: true expires_at: type: string format: date-time next_action: allOf: - $ref: '#/components/schemas/DigitalIdWalletApiWalletNextAction' nullable: true readOnly: true identity: allOf: - $ref: '#/components/schemas/DigitalIdWalletApiWalletIdentity' nullable: true readOnly: true attributes: type: object additionalProperties: {} nullable: true readOnly: true level_of_assurance: type: string nullable: true verified_at: type: string format: date-time nullable: true signature_valid: type: boolean nullable: true description: 凭证签名验证通过后为 true；模拟凭证为 null。 credential_type: type: string nullable: true required: - attributes - country - credential_type - error - expires_at - identity - interaction - level_of_assurance - next_action - outcome - signature_valid - simulated - status - verified_at - wallet DigitalIdWalletApiWalletVerificationFieldErrors: type: object description: 请求验证错误：每个被拒绝的字段及其消息。 additionalProperties: type: array items: type: string DigitalIdWalletApiClientCredentialsForbiddenErrorMessage: type: object properties: detail: type: string default: Forbidden - User doesn't have permission DigitalIdWalletApiWallet: type: object properties: id: type: string description: 钱包的目录 ID，例如 bankid_se。 name: type: string issuing_authority: type: string nullable: true required: - id - issuing_authority - name DigitalIdWalletApiWalletVerificationResultOutcomeEnum: enum: - pending - verified - cancelled - timeout - failed type: string description: |- * `pending` - 待处理 * `verified` - 已验证 * `cancelled` - 用户已取消 * `timeout` - 已超时 * `failed` - 已失败 DigitalIdWalletApiInteractionEnum: enum: - redirect - in_app - digital_credentials type: string description: |- * `redirect` - 重定向 * `in_app` - 应用内 * `digital_credentials` - 数字凭证 DigitalIdWalletApiWalletNextAction: type: object properties: type: allOf: - $ref: '#/components/schemas/DigitalIdWalletApiWalletNextActionTypeEnum' description: >- redirect：将用户浏览器重定向至 url。confirm_in_app：向用户显示 verification_code，用户核对该验证码与其钱包应用中的代码一致后在应用内确认；随后进行轮询。request_digital_credential：在您最初发起流程的源上通过用户手势调用 digital_credentials.request 请求钱包，然后将返回的内容发送至 POST .../verifications/{request_id}/response/。 * `redirect` - redirect * `confirm_in_app` - confirm_in_app * `request_digital_credential` - request_digital_credential url: type: string format: uri description: 仅限 redirect：用户使用钱包登录的页面。 digital_credentials: allOf: - $ref: >- #/components/schemas/DigitalIdWalletApiWalletDigitalCredentialsRequest description: 仅限 request_digital_credential：传递给钱包的请求内容。 verification_code: type: string description: 仅限 confirm_in_app：钱包应用上同步显示的 4 位比对码。 poll_interval_seconds: type: integer description: >- 仅限 confirm_in_app：调用 POST .../verifications/{request_id}/poll/ 以获取即时反馈的频率。Didit 还会在后台轮询待处理的登录，因此即使您不进行轮询，Webhook 也会报告结果。 required: - type DigitalIdWalletApiWalletIdentity: type: object properties: full_name: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true date_of_birth: type: string format: date nullable: true nationality: type: string nullable: true description: ISO3 国籍，仅在钱包明确声明时提供（绝不进行推断）。 issuing_state: type: string description: 签发该身份的方案所属的 ISO3 国家/地区。 required: - date_of_birth - first_name - full_name - issuing_state - last_name - nationality DigitalIdWalletApiWalletNextActionTypeEnum: enum: - redirect - confirm_in_app - request_digital_credential type: string description: |- * `redirect` - 重定向 * `confirm_in_app` - 应用内确认 * `request_digital_credential` - 请求数字凭证 DigitalIdWalletApiWalletDigitalCredentialsRequest: type: object properties: protocol: type: string description: openid4vp-v1-signed。 request: type: object additionalProperties: {} description: >- 原样传递：在浏览器中为 navigator.credentials.get({digital: request})，或在 Android 上作为 GetDigitalCredentialOption 的 requestJson 传入 JSON.stringify(request)。由 Didit 为您的应用签名。 required: - protocol - request securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 BearerAuth: type: http scheme: bearer description: 该应用的客户端凭证访问 token。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.