SDK Java e Kotlin para KYC, AML e transações

A biblioteca oficial da Didit para Java e Kotlin. Ela exige Java 11 ou superior e depende apenas de java.net.http, Jackson e das anotações de nulidade do JSpecify. Todo método tem uma variante ...Async que retorna um CompletableFuture. Consulte a visão geral dos SDKs de servidor para ver o que todos os SDKs têm em comum.

Instalação

implementation("me.didit:didit-java:1.0.1")

<dependency>
  <groupId>me.didit</groupId>
  <artifactId>didit-java</artifactId>
  <version>1.0.1</version>
</dependency>

O artefato é me.didit:didit-java no Maven Central. O código-fonte e o changelog estão em didit-protocol/sdk-java no GitHub.

Configurar o cliente

new Didit() lê DIDIT_API_KEY do ambiente. Use o builder para substituí-la ou para definir os IDs da organização e da aplicação exigidos pelas chamadas no escopo da aplicação (casos, redes, relatórios regulatórios).

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));

Os tipos de requisição são builders cujo build() verifica os campos obrigatórios. Os campos opcionais da resposta são valores Optional; em Kotlin, leia-os com .getOrNull(). Os trechos desta página e de cada página da referência da API são o corpo de um método, com as importações necessárias acima deles.

Criar uma sessão

Crie uma sessão de verificação para um workflow e envie seu usuário para a URL dela.

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());

Ler a decisão

Quando o usuário terminar (ou quando o webhook chegar), leia a decisão. O resultado de cada recurso é uma lista com uma entrada por nó do fluxo.

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));
}

Verificar um webhook

Passe o corpo bruto, exatamente como foi recebido, e os cabeçalhos da requisição. Webhooks.verify lança WebhookVerificationException para qualquer coisa que não seja uma entrega válida e recente e, caso contrário, retorna um evento tipado.

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<String, String> 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;
    }
}

No Spring Boot, receba o corpo como @RequestBody byte[] body e os cabeçalhos como @RequestHeader Map<String, String> headers. Para aceitar dois segredos enquanto faz a rotação de um deles, passe VerifyOptions. Consulte Webhooks para conhecer os eventos e o esquema de assinatura.

Analisar uma transação

Envie um pagamento, saque ou transferência de cripto para o monitoramento de transações; a resposta traz o status e a pontuação de risco.

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));

Verificar tokens de Authentication

Authentication verifica os tokens de acesso que o seu emissor de Authentication assina, no seu backend, sem chamar a Didit a cada requisição. Ele também troca códigos, renova tokens, verifica e revoga sessões e executa step-ups.

A verificação de tokens executa as checagens descritas em Verificar um token no seu servidor, com base no emissor e nas chaves de assinatura da sua aplicação.

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;
        }
    }
}

Erros

Toda exceção estende a DiditException não verificada (unchecked).

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(""));
}

Listas e arquivos

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);

As páginas de endpoints de servidor da referência da API têm um exemplo em Java para a respectiva operação, exceto os endpoints e campos que ainda não estão em nenhuma versão 1.0.1, listados na visão geral.

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

SDK Java e Kotlin para KYC, AML e transações

Instalação

Configurar o cliente

Criar uma sessão

Ler a decisão

Verificar um webhook

Analisar uma transação

Verificar tokens de Authentication

Erros

Listas e arquivos

​Instalação

​Configurar o cliente

​Criar uma sessão

​Ler a decisão

​Verificar um webhook

​Analisar uma transação

​Verificar tokens de Authentication

​Erros

​Listas e arquivos

Instalação

Configurar o cliente

Criar uma sessão

Ler a decisão

Verificar um webhook

Analisar uma transação

Verificar tokens de Authentication

Erros

Listas e arquivos