Incognia API Java Client

Java lightweight client library for Incognia APIs.

Installation

Incognia API Java Client is available on Maven Central. We provide 2 artifact ids: incognia-api-client and incognia-api-client-shaded. incognia-api-client-shaded includes all of our dependencies shaded into a single jar, so you don't need to worry about dependency conflicts.

Maven

Add our maven repository

<repository> 
     <id>incognia</id>
     <url>https://repo.incognia.com/java</url>
</repository>

And then add the artifact incognia-api-client or incognia-api-client-shaded as a dependency:

<dependency>
  <groupId>com.incognia</groupId>
  <artifactId>incognia-api-client</artifactId>
  <version>2.8.0</version>
</dependency>

<dependency>
  <groupId>com.incognia</groupId>
  <artifactId>incognia-api-client-shaded</artifactId>
  <version>2.8.0</version>
</dependency>

Gradle

Add our maven repository

repositories {
    maven {
        url 'https://repo.incognia.com/java'
    }
}

And then add the dependency

dependencies {
     implementation 'com.incognia:incognia-api-client:2.8.0'
}

dependencies {
     implementation 'com.incognia:incognia-api-client-shaded:2.8.0'
}

We support Java 8+.

Usage

Configuration

Before calling the API methods, you need to create an instance of the IncogniaAPI class.

IncogniaAPI api = IncogniaAPI.init("your-client-id", "your-client-secret");

This will create a singleton instance of the IncogniaAPI class, which will handle token renewal automatically. You should reuse this instance throughout your application.

After calling init, you can get the singleton instance simply calling IncogniaAPI.instance().

Dependency Injection integration examples

If you use a dependency injection framework, you can create a singleton bean for the IncogniaAPI class. Below are some examples using common java frameworks:

Spring Boot:

@Configuration
public class IncogniaAPIConfig {
    @Value("${incognia.client-id}")// change this to your property name
    private String clientId;
    
    @Value("${incognia.client-secret}") //change this to your property name
    private String clientSecret;
    
    @Bean
    @Scope(value = ConfigurableBeanFactory.SCOPE_SINGLETON)
    public IncogniaAPI incogniaAPI() {
        return IncogniaAPI.init(clientId, clientSecret);
    }
}

Micronaut:

@Factory
public class IncogniaAPIFactory {
    @Singleton
    //change the @Value to your property name
    public IncogniaAPI incogniaAPI(@Value("${incognia.client-id}") String clientId,
        @Value("${incognia.client-secret}") String clientSecret) {
        return IncogniaAPI.init(clientId, clientSecret);
    }
}

Incognia API

The implementation is based on the Incognia API Reference.

Authentication

Authentication is done transparently, so you don't need to worry about it.

If you are curious about how we handle it, you can check the TokenAwareNetworkingClient class

Registering Signup

This method registers a new signup for the given installation and address, returning a SignupAssessment, containing the risk assessment and supporting evidence:

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
     Address address =
        Address.builder()
            .structuredAddress(
                StructuredAddress.builder()
                    .countryCode("US")
                    .countryName("United States of America")
                    .locale("en-US")
                    .state("NY")
                    .city("New York City")
                    .borough("Manhattan")
                    .neighborhood("Midtown")
                    .street("W 34th St.")
                    .number("20")
                    .complements("Floor 2")
                    .postalCode("10001")
                    .build())
            .coordinates(new Coordinates(40.74836007062138, -73.98509720487937))
            .build();
    RegisterSignupRequest signupRequest = RegisterSignupRequest.builder()
        .address(address)
        .installationId("installation id")
        .build();
     SignupAssessment assessment = api.registerSignup(signupRequest);
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

It's also possible to register a signup without an address:

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
    RegisterSignupRequest signupRequest = RegisterSignupRequest.builder()
        .installationId("installation id")
        .build();
     SignupAssessment assessment = api.registerSignup(signupRequest);
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

Registering Web Signup

This method registers a new web signup for the given session token, returning a SignupAssessment, containing the risk assessment and supporting evidence:

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
    RegisterWebSignupRequest webSignupRequest = RegisterWebSignupRequest.builder()
        .sessionToken("session token")
        .build();
     SignupAssessment assessment = api.registerWebSignup(webSignupRequest);
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

Registering Login

This method registers a new login for the given installation and account, returning a TransactionAssessment, containing the risk assessment and supporting evidence. This method also includes some overloads that do not require optional parameters, like externalId.

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
     RegisterLoginRequest registerLoginRequest =
        RegisterLoginRequest.builder()
          .installationId("installation id")
          .accountId("account id")
          .externalId("external id")
          .evaluateTransaction(true) // can be omitted as it uses true as the default value
          .customProperties(Map.of(
            "custom-property-key", "custom-property-value",
            "custom-double-property-key", 1.0))
          .build();
     TransactionAssessment assessment = api.registerLogin(registerLoginRequest);
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

Registering Web Login

This method registers a new web login for the given installation and account, returning a TransactionAssessment, containing the risk assessment and supporting evidence.

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
     RegisterWebLoginRequest webLoginRequest =
        RegisterWebLoginRequest.builder()
          .accountId("account id")
          .externalId("external id")
          .sessionToken("session-token")
          .evaluateTransaction(true) // can be omitted as it uses true as the default value
          .build();
     TransactionAssessment assessment = api.registerWebLogin(webLoginRequest);
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

Registering Payment

This method registers a new payment for the given installation and account, returning a TransactionAssessment, containing the risk assessment and supporting evidence. This method also includes some overloads that do not require optional parameters, like externalId and addresses.

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
     Address address = Address address =
        Address.builder()
            .structuredAddress(
                StructuredAddress.builder()
                    .countryCode("US")
                    .countryName("United States of America")
                    .locale("en-US")
                    .state("NY")
                    .city("New York City")
                    .borough("Manhattan")
                    .neighborhood("Midtown")
                    .street("W 34th St.")
                    .number("20")
                    .complements("Floor 2")
                    .postalCode("10001")
                    .build())
            .coordinates(new Coordinates(40.74836007062138, -73.98509720487937))
            .build();
     
     Map<AddressType, Address> addresses = Map.of(
         AddressType.SHIPPING, address
         AddressType.BILLING, address);
     
     List<PaymentMethod> paymentMethods = new ArrayList<>();
        paymentMethods.add(
            PaymentMethod.builder()
                .creditCardInfo(
                    CardInfo.builder()
                        .bin("123456")
                        .expiryMonth("10")
                        .expiryYear("2028")
                        .lastFourDigits("4321")
                        .build())
                .type(PaymentType.CREDIT_CARD)
                .build());
        
     RegisterPaymentRequest registerPaymentRequest =
         RegisterPaymentRequest.builder()
             .installationId( "installation-id")
             .accountId("account-id")
             .externalId("external-id")
             .addresses(addresses)
             .evaluateTransaction(true) // can be omitted as it uses true as the default value
             .paymentValue(PaymentValue.builder().currency("BRL").amount(10.0).build())
             .paymentMethods(paymentMethods)
             .build();
    
     TransactionAssessment assessment = api.registerPayment(registerPaymentRequest);
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

Registering Payment or Login without evaluating its risk assessment

Turning off the risk assessment evaluation allows you to register a new transaction (Login or Payment), but the response (TransactionAssessment) will be empty. For instance, if you're using the risk assessment only for some payment transactions, you should still register all the other ones: this will avoid any bias on the risk assessment computation.

To register a login or a payment without evaluating its risk assessment, you should use the evaluateTransaction boolean set to false

Example:

RegisterLoginRequest registerLoginRequest =
        RegisterLoginRequest.builder()
          .installationId("installation id")
          .accountId("account id")
          .externalId("external id")
          .evaluateTransaction(false)
          .build();

Would return an empty risk assessment response:

{}

Sending Feedback

This method registers a feedback event for the given identifiers (represented in FeedbackIdentifiers) related to a signup, login or payment.

IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
    Instant timestamp = Instant.now();
    client.registerFeedback(
       FeedbackEvent.ACCOUNT_TAKEOVER,
       timestamp,
       FeedbackIdentifiers.builder()
           .installationId("installation-id")
           .sessionToken("session-token")
           .accountId("account-id")
           .externalId("external-id")
           .signupId("c9ac2803-c868-4b7a-8323-8a6b96298ebe")
           .build();
} catch (IncogniaAPIException e) {
     //Some api error happened (invalid data, invalid credentials)
} catch (IncogniaException e) {
     //Something unexpected happened
}

Evidences

Every assessment response (TransactionAssessment and SignupAssessment) includes supporting evidence in a generic Map<String, Object>. You can find all available evidence here.

Exception handling

Every method call can throw IncogniaAPIException and IncogniaException.

IncogniaAPIException is thrown when the API returned an unexpected http status code. You can retrieve it by calling the getStatusCode method in the exception, along with the getPayload method, which returns the api response payload, which might include additional details.

IncogniaException represents unknown errors, like serialization/deserialization errors.

How to Contribute

If you have found a bug or if you have a feature request, please report them at this repository issues section.

What is Incognia?

Incognia is a location identity platform for mobile apps that enables:

Real-time address verification for onboarding
Frictionless authentication
Real-time transaction verification

inloco/incognia-api-java