Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/inloco/incognia-api-java
Java client library for Incognia's API
https://github.com/inloco/incognia-api-java
java
Last synced: 7 days ago
JSON representation
Java client library for Incognia's API
- Host: GitHub
- URL: https://github.com/inloco/incognia-api-java
- Owner: inloco
- License: mit
- Created: 2021-05-20T18:54:15.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-11-13T13:49:59.000Z (about 2 months ago)
- Last Synced: 2024-11-13T14:35:26.470Z (about 2 months ago)
- Topics: java
- Language: Java
- Homepage: https://www.incognia.com/
- Size: 446 KB
- Stars: 4
- Watchers: 8
- Forks: 2
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Incognia API Java Client
Java lightweight client library for [Incognia APIs](https://dash.incognia.com/api-reference).
## Installation
Incognia API Java Client is available on Incognia's Maven Repository. 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
```xml
incognia
https://repo.incognia.com/java
```
And then add the artifact `incognia-api-client` **or** `incognia-api-client-shaded` as a dependency:
```xml
com.incognia
incognia-api-client
3.1.0
```
```xml
com.incognia
incognia-api-client-shaded
3.1.0
```
### Gradle
Add our maven repository
```gradle
repositories {
maven {
url 'https://repo.incognia.com/java'
}
}
```
And then add the dependency
```gradle
dependencies {
implementation 'com.incognia:incognia-api-client:3.1.0'
}
```
OR
```gradle
dependencies {
implementation 'com.incognia:incognia-api-client-shaded:3.1.0'
}
```
We support Java 8+.
## Usage
### Configuration
Before calling the API methods, you need to create an instance of the `IncogniaAPI` class.
```java
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:
```java
@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:
```java
@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](https://dash.incognia.com/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 request token and address, returning a `SignupAssessment`, containing the risk assessment and supporting evidence:
```java
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)
.requestToken("request token")
.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:
```java
IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
RegisterSignupRequest signupRequest = RegisterSignupRequest.builder()
.requestToken("request token")
.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 request token, returning a `SignupAssessment`, containing the risk assessment and supporting evidence:
```java
IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
RegisterWebSignupRequest webSignupRequest = RegisterWebSignupRequest.builder()
.requestToken("request 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 request token 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`.
```java
IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
RegisterLoginRequest registerLoginRequest =
RegisterLoginRequest.builder()
.requestToken("request token")
.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 request token and account, returning a `TransactionAssessment`, containing the risk assessment and supporting evidence.
```java
IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
RegisterWebLoginRequest webLoginRequest =
RegisterWebLoginRequest.builder()
.accountId("account id")
.externalId("external id")
.requestToken("request-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 request token 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`.
```java
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 addresses = Map.of(
AddressType.SHIPPING, address
AddressType.BILLING, address);
List 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()
.requestToken( "request-token")
.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:
```java
RegisterLoginRequest registerLoginRequest =
RegisterLoginRequest.builder()
.requestToken("request token")
.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.
```java
IncogniaAPI api = IncogniaAPI.init("client-id", "client-secret");
try {
Instant timestamp = Instant.now();
client.registerFeedback(
FeedbackEvent.ACCOUNT_TAKEOVER,
timestamp,
FeedbackIdentifiers.builder()
.requestToken("request-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`.
You can find all available evidence [here](https://docs.incognia.com/apis/understanding-assessment-evidence#risk-assessment-evidence).
## 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
## License
[](https://opensource.org/licenses/MIT)