> ## 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.
# Java 및 Kotlin SDK: KYC, AML, 거래 모니터링
> Didit 공식 Java 및 Kotlin SDK 빠른 시작 가이드입니다. 서버 API용 타입 빌더, 동기·비동기 호출, 웹훅 검증, 토큰 확인을 다룹니다.
공식 Didit 라이브러리는 Java와 Kotlin용입니다. Java 11 이상이 필요하며, `java.net.http`, Jackson, JSpecify 널 가능성 어노테이션에만 의존합니다. 모든 메서드에는 `CompletableFuture`를 반환하는 `...Async` 변형이 있습니다. 모든 서버 SDK가 공유하는 내용은 [서버 SDK 개요](https://docs.didit.me/ko/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와 애플리케이션 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/ko/api-reference/overview.md) 페이지의 코드 조각은 메서드 본문이며, 필요한 import는 그 위에 있습니다.
## 세션 생성
워크플로에 대한 [인증 세션](https://docs.didit.me/ko/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/ko/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/ko/integration/webhooks.md)를 참조하세요.
## 거래 스크리닝
결제, 출금 또는 암호화폐 송금을 [거래 모니터링](https://docs.didit.me/ko/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 토큰 검증
`Authentication`은 백엔드에서, 요청마다 Didit을 호출하지 않고도 [Authentication](https://docs.didit.me/ko/authentication/overview.md) 발급자가 서명한 액세스 토큰을 검증합니다. 또한 코드를 교환하고, 토큰을 갱신하며, 세션을 확인하고 취소하고, 추가 인증을 실행합니다.
> [!NOTE]
>
> 토큰 검증은 애플리케이션의 발급자와 서명 키를 기준으로 [서버에서 토큰 검증하기](https://docs.didit.me/ko/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/ko/api-reference/overview.md)의 서버 엔드포인트 페이지에는 각 작업에 대한 Java 샘플이 있습니다. 다만 아직 1.0.1 릴리스에 포함되지 않은 엔드포인트와 필드는 예외이며, 이는 [개요](https://docs.didit.me/ko/integration/server-sdks/overview.md)에 명시되어 있습니다.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.