Java / Kotlin SDK

import cd.rdcpass.Environment;
import cd.rdcpass.RdcPass;

// Staging environment: https://gateway.staging.rdcpass.cd
RdcPass client = RdcPass.builder()
    .environment(Environment.SANDBOX)
    .keyId("key_test_3c7e1a9f42")
    .keySecret(System.getenv("RDCPASS_KEY_SECRET"))
    .encryptionKey(System.getenv("RDCPASS_ENCRYPTION_KEY"))
    .build();

import java.nio.file.Path;
import cd.rdcpass.RdcPass;

// fromEnv() reads RDCPASS_KEY_ID, RDCPASS_KEY_SECRET,
// RDCPASS_ENCRYPTION_KEY and RDCPASS_ENVIRONMENT.
// Production (https://api.rdcpass.cd) also requires your mTLS client certificate.
RdcPass client = RdcPass.builder()
    .fromEnv()
    .clientCertificate(Path.of("/etc/rdcpass/client.crt"), Path.of("/etc/rdcpass/client.key"))
    .build();

import java.time.LocalDate;
import java.util.List;

import cd.rdcpass.RdcPass;
import cd.rdcpass.models.Identifier;
import cd.rdcpass.models.Match;
import cd.rdcpass.models.kyc.KycValidation;
import cd.rdcpass.models.kyc.KycValidationCreateParams;

public class ValidateIdentity {
    public static void main(String[] args) {
        RdcPass client = RdcPass.builder().fromEnv().build();

        KycValidation validation = client.kyc().validations().create(
            KycValidationCreateParams.builder()
                .reference("cust-0001")
                .identifier(Identifier.rdcpassId("COD-2103-0214-4937"))
                .match(Match.builder()
                    .fullName("Kabeya Mwamba Tshisekedi")
                    .dateOfBirth(LocalDate.of(1988, 4, 12))
                    .build())
                .purpose("customer_onboarding")
                .scopes(List.of("kyc.documents.primary", "kyc.phone_numbers"))
                .build());

        System.out.println(validation.getResult());                   // VERIFIED
        System.out.println(validation.getKyc().getBasic().getFullName()); // Kabeya Mwamba Tshisekedi
        System.out.println(validation.getScopesWithheld());           // []
    }
}

{
  "id": "kyc_8d2f6a1c93",
  "object": "kyc_validation",
  "livemode": true,
  "reference": "cust-0001",
  "status": "completed",
  "result": "verified",
  "certified_account": true,
  "identifier": {
    "type": "rdcpass_id",
    "value": "COD-2103-0214-4937"
  },
  "match": {
    "full_name": "match",
    "date_of_birth": "match",
    "age": "not_provided",
    "score": 0.98
  },
  "account": {
    "rdcpass_id": "COD-2103-0214-4937",
    "status": "active",
    "certified": true,
    "created_at": "2025-03-14T09:22:41Z",
    "level_of_assurance": "LOA3"
  },
  "kyc": {
    "basic": {
      "full_name": "Kabeya Mwamba Tshisekedi",
      "first_name": "Kabeya",
      "last_name": "Tshisekedi",
      "date_of_birth": "1988-04-12",
      "age": 38,
      "gender": "male",
      "nationality": "COD"
    },
    "documents": {
      "primary": {
        "type": "passport",
        "number": "OB1234567",
        "issued_at": "2022-06-01",
        "expires_at": "2027-05-31",
        "issuing_authority": "Direction Générale de Migration",
        "status": "valid",
        "image": {
          "content_type": "image/jpeg",
          "url": "https://files.rdcpass.cd/d/9f2c41e8b7a3?sig=Qm9fX2t5Y19zaWc&exp=1790418002",
          "expires_at": "2026-09-26T10:20:02Z"
        }
      }
    },
    "phone_numbers": [
      {
        "number": "+243812345678",
        "operator": "Vodacom",
        "is_primary": true,
        "verified": true
      },
      {
        "number": "+243991234567",
        "operator": "Airtel",
        "is_primary": false,
        "verified": true
      }
    ]
  },
  "scopes_applied": [
    "kyc.basic",
    "kyc.documents.primary",
    "kyc.phone_numbers"
  ],
  "scopes_withheld": [],
  "purpose": "customer_onboarding",
  "created_at": "2026-09-26T10:15:02Z"
}

// 1. Build the authorize URL. The SDK generates state and the PKCE
//    code_verifier / code_challenge (S256) for you.
AuthorizationRequest auth = client.login().createAuthorizationUrl(
    AuthorizationUrlParams.builder()
        .clientId("app_8f2a1c0e9b")
        .redirectUri("https://yourapp.example.com/callback")
        .scopes(List.of("openid", "profile", "rdcpass:kyc.phone_numbers"))
        .build());
// Store auth.getState() and auth.getCodeVerifier() in the user's session,
// then redirect to auth.getUrl().

// 2. On your callback, check state and exchange the code.
if (!returnedState.equals(session.getState())) {
    throw new IllegalStateException("state mismatch");
}
TokenResponse tokens = client.login().exchangeCode(
    ExchangeCodeParams.builder()
        .clientId("app_8f2a1c0e9b")
        .code(code)
        .codeVerifier(session.getCodeVerifier())
        .redirectUri("https://yourapp.example.com/callback")
        .build());
UserInfo user = client.login().userInfo(tokens.getAccessToken());

// Submit up to 10,000 items asynchronously (Prefer: respond-async).
Batch batch = client.kyc().validations().batches().create(
    KycValidationBatchCreateParams.builder()
        .purpose("customer_onboarding")
        .addItem(KycValidationCreateParams.builder()
            .reference("cust-0001").identifier(Identifier.rdcpassId("COD-2103-0214-4937")).build())
        .addItem(KycValidationCreateParams.builder()
            .reference("cust-0002").identifier(Identifier.ceni("1234567890123")).build())
        .build(),
    RequestOptions.builder().respondAsync(true).build());

// Poll GET /v1/batches/{id} until the batch reaches a final status.
Batch done = client.batches().waitFor(batch.getId(), Duration.ofSeconds(5), Duration.ofMinutes(30));
System.out.println(done.getStatus() + " " + done.getSucceededItems() + " " + done.getFailedItems());

// Iterate every result; autoPager() follows next_cursor page by page.
for (BatchResult item : client.batches().results(batch.getId(), ListParams.limit(500)).autoPager()) {
    System.out.println(item.getReference() + " " + item.getStatus());
}

@PostMapping("/webhooks/rdcpass")
public ResponseEntity<Void> rdcpassWebhook(@RequestBody byte[] rawBody, @RequestHeader HttpHeaders headers) {
    // Use the raw body: the signature covers "{timestamp}.{rawBody}".
    Event event;
    try {
        event = client.webhooks().constructEvent(rawBody, headers.toSingleValueMap());
    } catch (SignatureVerificationException e) {
        return ResponseEntity.badRequest().build();
    }

    switch (event.getType()) {
        case "kyc_validation.completed":
            System.out.println(event.getData().getObject(Job.class).getStatus());
            break;
        case "batch.completed":
        case "batch.completed_with_errors":
            Batch batch = event.getData().getObject(Batch.class);
            System.out.println(batch.getId() + " " + batch.getFailedItems());
            break;
        default:
            break;
    }
    return ResponseEntity.ok().build();
}

try {
    client.kyc().validations().create(
        KycValidationCreateParams.builder()
            .identifier(Identifier.rdcpassId("COD-2103-0214-4937"))
            .purpose("customer_onboarding")
            .scopes(List.of("kyc.biometrics.iris"))
            .build());
} catch (RdcPassException e) {
    System.err.println(e.getStatus() + " " + e.getCode() + " " + e.getMessage() + " " + e.getRequestId());
    if ("scope_not_granted".equals(e.getCode())) {
        // 403: request the scope for your application in the console
    }
}

RdcPass client = RdcPass.builder()
    .fromEnv()
    .maxRetries(5) // default 3; set 0 to disable
    .build();

// Every POST gets an Idempotency-Key automatically. Pass your own to make
// retries safe across process restarts:
client.fraud().reports().create(
    FraudReportCreateParams.builder()
        .type("identity_usurpation")
        .subject(FraudSubject.of(Identifier.rdcpassId("COD-2103-0214-4937")))
        .description("Account opened with a stolen passport.")
        .build(),
    RequestOptions.builder()
        .idempotencyKey("fraud-case-INC-2026-88213")
        .maxRetries(1)
        .build());

// The SDK logs through SLF4J under the "cd.rdcpass" logger —
// set it to DEBUG in your logging configuration to trace requests.
RdcPass client = RdcPass.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(20)) // per attempt (default 30s)
    .build();

// Override per request.
client.aml().screenings().create(
    AmlScreeningCreateParams.builder()
        .subject(AmlSubject.of(Identifier.rdcpassId("COD-1907-5521-0386")))
        .purpose("regulatory_compliance")
        .build(),
    RequestOptions.builder().timeout(Duration.ofSeconds(60)).build());

// Every resource also has an async variant returning CompletableFuture:
// client.async().kyc().validations().create(params)