> ## 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.
# Didit Java 与 Kotlin SDK：KYC、AML 与交易
> Didit 官方 Java 与 Kotlin SDK 快速入门：为服务端 API 提供类型化构建器、同步与异步调用、Webhook 验证及令牌检查。
适用于 Java 和 Kotlin 的官方 Didit 库。它需要 Java 11 或更高版本，仅依赖 `java.net.http`、Jackson 和 JSpecify 可空性注解。每个方法都有一个 `...Async` 变体，返回 `CompletableFuture`。各 SDK 的共同内容，请参阅[服务端 SDK 概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)。
## 安装
```kotlin Gradle theme={null}
implementation("me.didit:didit-java:1.0.1")
```
```xml Maven theme={null}
me.didit
didit-java
1.0.1
```
该构件为 [Maven Central 上的 `me.didit:didit-java`](https://central.sonatype.com/artifact/me.didit/didit-java)。其源代码和变更日志位于 GitHub 上的 [didit-protocol/sdk-java](https://github.com/didit-protocol/sdk-java)。
## 配置客户端
`new Didit()` 会从环境变量中读取 `DIDIT_API_KEY`。如需覆盖该值，或设置应用范围调用（案件、网络、监管报告）所需的组织和应用 ID，请使用构建器。
```java theme={null}
import java.time.Duration;
import me.didit.Didit;
import me.didit.core.RequestOptions;
import me.didit.types.SessionsRetrieveDecisionParams;
Didit client = Didit.builder()
.apiKey(System.getenv("DIDIT_API_KEY"))
.organizationId(System.getenv("DIDIT_ORGANIZATION_ID"))
.applicationId(System.getenv("DIDIT_APPLICATION_ID"))
.timeout(Duration.ofSeconds(30))
.maxRetries(2)
.build();
// Options for a single call.
var decision = client.sessions().retrieveDecision("11111111-2222-3333-4444-555555555555",
SessionsRetrieveDecisionParams.builder().build(),
RequestOptions.builder().timeout(Duration.ofSeconds(5)).build());
System.out.println(decision.status().orElse(null));
```
请求类型是构建器，其 `build()` 会检查必填字段。可选的响应字段为 `Optional` 值；在 Kotlin 中，请使用 `.getOrNull()` 读取。本页以及每个 [API 参考](https://docs.didit.me/zh/api-reference/overview.md)页面中的代码片段都是某个方法的方法体，所需的导入语句位于其上方。
## 创建会话
为某个工作流创建[验证会话](https://docs.didit.me/zh/sessions-api/create-session.md)，并将您的用户引导至其 URL。
```java theme={null}
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
Didit client = new Didit();
var session = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/done")
.build());
System.out.println(session.url());
```
## 读取决策
用户完成验证后（或 webhook 到达时），请[读取决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。每个功能结果都是一个列表，每个工作流节点对应一项。
```java theme={null}
import java.util.List;
import me.didit.Didit;
Didit client = new Didit();
var decision = client.sessions().retrieveDecision("11111111-2222-3333-4444-555555555555");
decision.status().ifPresent(status -> System.out.println(status));
for (var verification : decision.idVerifications().orElse(List.of())) {
System.out.println(verification.status().orElse(null));
}
```
## 验证 Webhook
传入原始请求体（保持接收时的原样）以及请求头。对于任何无效或已过期的投递，`Webhooks.verify` 都会抛出 `WebhookVerificationException`；否则返回类型化的事件。
```java theme={null}
import java.util.Map;
import me.didit.errors.WebhookVerificationException;
import me.didit.webhooks.SessionStatusUpdatedEvent;
import me.didit.webhooks.WebhookEvent;
import me.didit.webhooks.Webhooks;
public class DiditWebhookHandler {
private final String secret = System.getenv("DIDIT_WEBHOOK_SECRET");
public int handle(byte[] rawBody, Map headers) {
WebhookEvent event;
try {
event = Webhooks.verify(rawBody, headers, secret);
} catch (WebhookVerificationException e) {
System.out.println("rejected: " + e.reason());
return 400;
}
if (event instanceof SessionStatusUpdatedEvent) {
SessionStatusUpdatedEvent updated = (SessionStatusUpdatedEvent) event;
System.out.println(updated.sessionId().orElse("") + " " + updated.status().orElse(""));
}
return 200;
}
}
```
在 Spring Boot 中，请以 `@RequestBody byte[] body` 接收请求体，以 `@RequestHeader Map headers` 接收请求头。若在轮换一个密钥的同时需要接受两个密钥，请传入 `VerifyOptions`。事件和签名方案详见 [Webhooks](https://docs.didit.me/zh/integration/webhooks.md)。
## 筛查交易
将支付、提现或加密货币转账提交至[交易监控](https://docs.didit.me/zh/transaction-monitoring/overview.md)；响应中包含其状态和风险评分。
```java theme={null}
import me.didit.Didit;
import me.didit.types.TransactionsCreateParams;
Didit client = new Didit();
var transaction = client.transactions().create(TransactionsCreateParams.builder()
.transactionId("txn-1001")
.transactionCategory(TransactionsCreateParams.TransactionCategory.of("finance"))
.transactionDetails(TransactionsCreateParams.TransactionDetails.builder()
.direction(TransactionsCreateParams.TransactionDetails.Direction.of("outbound"))
.amount(1500.0)
.currency("EUR")
.build())
.subject(TransactionsCreateParams.Subject.builder()
.entityType("individual")
.vendorData("user-123")
.fullName("Maria Garcia")
.build())
.build());
System.out.println(transaction.status().orElse(null) + " " + transaction.score().orElse(null));
```
## 验证 Authentication token
`Authentication` 会在您的后端检查您的 [Authentication](https://docs.didit.me/zh/authentication/overview.md) 签发方所签名的访问令牌，无需为每个请求调用 Didit。它还可以交换授权码、刷新 token、检查和撤销会话，以及执行升级验证。
> [!NOTE]
>
> token 验证会执行[在服务器上验证令牌](https://docs.didit.me/zh/authentication/tokens-and-jwks.md#在服务器上验证令牌)中的检查，针对您应用的签发方和签名密钥进行。
```java theme={null}
import me.didit.authentication.AccessTokenClaims;
import me.didit.authentication.Authentication;
import me.didit.errors.TokenVerificationException;
public class CurrentUser {
// The publishable key (pk_live_... or pk_test_...) carries your issuer URL.
private final Authentication auth = Authentication.builder()
.publishableKey("pk_live_...")
.clientId("your-application-id")
.build();
public String subject(String accessToken) {
try {
AccessTokenClaims claims = auth.verifyAccessToken(accessToken);
return claims.subject();
} catch (TokenVerificationException e) {
System.out.println("rejected: " + e.reason());
return null;
}
}
}
```
## 错误
每个异常都继承自非受检异常 `DiditException`。
```java theme={null}
import me.didit.Didit;
import me.didit.errors.ApiStatusException;
import me.didit.errors.NotFoundException;
Didit client = new Didit();
try {
client.sessions().retrieveDecision("11111111-2222-3333-4444-555555555555");
} catch (NotFoundException e) {
System.out.println("no such session");
} catch (ApiStatusException e) {
System.out.println(e.statusCode() + " " + e.requestId().orElse(""));
}
```
## 列表与文件
```java theme={null}
import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.IdVerificationVerifyParams;
import me.didit.types.SessionsListParams;
Didit client = new Didit();
// Lists page through every result.
for (var session : client.sessions().list(SessionsListParams.builder().status("Approved").build())) {
System.out.println(session);
}
// Uploads take a Path or a FileUpload (bytes or a stream).
var result = client.idVerification().verify(IdVerificationVerifyParams.builder()
.frontImage(Path.of("id-front.jpg"))
.backImage(Path.of("id-back.jpg"))
.build());
System.out.println(result);
```
[API 参考](https://docs.didit.me/zh/api-reference/overview.md)中的服务端 endpoint 页面都为其操作提供了 Java 示例，但 1.0.1 版本尚未提供的 endpoint 和字段除外，它们列在[概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)中。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.