Intro

Welcome! This document will explain how to integrate with Konduto's anti-fraud service so you can begin to spot fraud on your e-commerce website.

Our service uses the visitor's behavior to analyze browsing patterns and detect fraud. You will need to add a JavaScript snippet to your website and tag your pages, so we can see your visitors, and call our REST API to send purchases, so we can analyze them.

This document refers to the Java SDK used for our API.

Requirements

• Java 8

Installation

To get started add our SDK as a dependency in your pom.xml:

<dependency>
	<groupId>com.konduto.sdk</groupId>
	<artifactId>java-sdk</artifactId>
	<version>2.17.4</version>
</dependency>

Getting Started

When a customer makes a purchase you must send the order information to us so we can analyze it. We perform a real-time analysis and return you a recommendation of what to do next and a score, a numeric confidence level about that order.

While many of the parameters we accept are optional we recommend you send all you can, because every data point matters for the analysis. The billing address and credit card information are specially important, though we understand there are cases where you don't have that information.

Set your API key

You will need an API key to authenticate the requests. Luckily for you the examples below have been populated with a working key, so you can just copy and paste to see how it works.

// creates a Konduto instance, which is a class that communicates with our API by using HTTP methods.
Konduto konduto = new Konduto("T738D516F09CAB3A2C1EE"); // T738D516F09CAB3A2C1EE is the API key

Creating an order

KondutoOrder is a class that models the attributes and behavior of an order.

All entities involved in Konduto's analysis process (e.g customer, shopping cart, payment, etc.) inherit from KondutoModel and are under the models package.

KondutoOrder order = new KondutoOrder()
		.with("id","123")
		.with("totalAmount", 123.4)
		.with("customer", customer); // customer is an instance of KondutoCustomer

One can also use the more conventional set-based approach as seen below.

KondutoOrder order = new KondutoOrder();
order.setId("123");
order.setTotalAmount(123.4);
order.setCustomer(customer);

Another way of initializing an instance of KondutoModel is to call KondutoModel's fromMap method and pass a Map and the instance class as arguments.

Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("id", "123"); 
attributes.put("totalAmount", 123.4);
attributes.put("customer", customer);

KondutoOrder order = (KondutoOrder) KondutoModel.fromMap(attributes, KondutoOrder.class);

NOTICE: the order created above is really, really simple. The more detail you provide, more accurate Konduto's analysis will be.

Intro

Welcome! This document will explain how to integrate with Konduto's anti-fraud service so you can begin to spot fraud on your e-commerce website.

Our service uses the visitor's behavior to analyze browsing patterns and detect fraud. You will need to add a JavaScript snippet to your website and tag your pages, so we can see your visitors, and call our REST API to send purchases, so we can analyze them.

This document refers to the Java SDK used for our API.

Requirements

• Java 8

Installation

To get started add our SDK as a dependency in your pom.xml:

<dependency>
	<groupId>com.konduto.sdk</groupId>
	<artifactId>java-sdk</artifactId>
	<version>2.17.4</version>
</dependency>

Getting Started

When a customer makes a purchase you must send the order information to us so we can analyze it. We perform a real-time analysis and return you a recommendation of what to do next and a score, a numeric confidence level about that order.

While many of the parameters we accept are optional we recommend you send all you can, because every data point matters for the analysis. The billing address and credit card information are specially important, though we understand there are cases where you don't have that information.

Set your API key

You will need an API key to authenticate the requests. Luckily for you the examples below have been populated with a working key, so you can just copy and paste to see how it works.

// creates a Konduto instance, which is a class that communicates with our API by using HTTP methods.
Konduto konduto = new Konduto("T738D516F09CAB3A2C1EE"); // T738D516F09CAB3A2C1EE is the API key

Creating an order

KondutoOrder is a class that models the attributes and behavior of an order.

All entities involved in Konduto's analysis process (e.g customer, shopping cart, payment, etc.) inherit from KondutoModel and are under the models package.

KondutoOrder order = new KondutoOrder()
		.with("id","123")
		.with("totalAmount", 123.4)
		.with("customer", customer); // customer is an instance of KondutoCustomer

One can also use the more conventional set-based approach as seen below.

KondutoOrder order = new KondutoOrder();
order.setId("123");
order.setTotalAmount(123.4);
order.setCustomer(customer);

Another way of initializing an instance of KondutoModel is to call KondutoModel's fromMap method and pass a Map and the instance class as arguments.

Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("id", "123"); 
attributes.put("totalAmount", 123.4);
attributes.put("customer", customer);

KondutoOrder order = (KondutoOrder) KondutoModel.fromMap(attributes, KondutoOrder.class);

NOTICE: the order created above is really, really simple. The more detail you provide, more accurate Konduto's analysis will be.

Order parameters

Parameter	Description
id	(required) Unique identifier for each order.
visitor	(required) Visitor identifier obtained from our JavaScript snippet.
total_amount	(required) Total order amount.
shipping_amount	(optional) Shipping and handling amount.
tax_amount	(optional) Taxes amount.
currency	(optional) Currency code with 3 letters (ISO-4712).
installments	(optional) Number of installments in the payment plan.
ip	(optional) Customer's IPv4 or IPV6 address.
customer	(required) Object containing the customer details.
payment	(optional) Array containing the payment methods.
billing	(optional) Object containing the billing information.
shipping	(optional) Object containing the shipping information.
shopping_cart	(optional) Array containing the items purchased.
analyze	(optional) A boolean indicating if the order should be analyzed. Defaults to true.
first_message	(optional) Time when the first message was exchanged between customer and seller.
messages_exchanged	(optional) Number of messages exchanged between customer and seller.
purchased_at	(optional) Time when the customer purchased from the seller.
vehicle	(optional) Object containing information regarding vehicles.

Customer information

Parameter	Description
id	(required) Unique identifier for each customer. Can be anything you like (counter, id, e-mail address) as long as it's consistent in future orders.
name	(required) Customer's full name.
email	(required) Customer's e-mail address
tax_id	(optional) Customer's tax id.
phone1	(optional) Customer's primary phone number
phone 2	(optional) Customer's secondary phone number
new	(optional) Boolean indicating if the customer is using a newly created account for this purchase.
vip	(optional) Boolean indicating if the customer is a VIP or frequent buyer.
created_at	(optional) Date when customer was created.
type	(optional) Identifier of the customer type.
risk_level	(optional) Level of risk identifier. Currently we support low, medium, high.
risk_score	(optional) Customer risk score identifier.
mother_name	(optional) Full name of the client’s mother.

Payment information

Payments may contain a description and a amount field. The former is a description of the payment, for example: "Thanksgiving discount voucher". The latter is the amount that was charged in that specific payment type. For example, a transaction total amount could be 100.00, of which 10.00 are paid via a discount voucher and 90.00 via credit card.

Credit card

Parameter	Description
status	(required) The status of the transaction returned by the payment processor. Accepts approved, declined or pending if the payment wasn't been processed yet.
bin	(optional) First six digits of the customer's credit card. Used to identify the type of card being sent.
last4	(optional) Four last digits of the customer's credit card number.
expiration_date	(optional) Card's expiration date under MMYYYY format.
cvv_result	(optional) Result code from CVV verification.
avs_result	(optional) Result code from AVS verification.
sha1	(optional) Integrity payment code.

Boleto

Parameter	Description
expiration_date	(optional) Boleto's expiration date (yyyy-MM-dd).

Other payment types available

• DEBIT
• TRANSFER
• VOUCHER
• TED

Billing address

Parameter	Description
name	(optional) Cardholder's full name.
address1	(optional) Cardholder's billing address on file with the bank.
address2	(optional) Additional cardholder address information.
city	(optional) Cardholder's city.
state	(optional) Cardholder's state.
zip	(optional) Cardholder's ZIP code.
country	(optional) Cardholder's country code (ISO 3166-2)

Shipping address

Parameter	Description
name	(optional) Recipient's full name.
address1	(optional) Recipient's shipping address.
address2	(optional) Additional recipient address information.
city	(optional) Recipient's city.
state	(optional) Recipient's state.
zip	(optional) Recipient's ZIP code.
country	(optional) Recipient's country code (ISO 3166-2)

Shopping cart

Parameter	Description
sku	(optional) Product or service's SKU or inventory id.
product_code	(optional) Product or service's UPC, barcode or secondary id.
category	(optional) Category code for the item purchased. See here for the list.
name	(optional) Name of the product or service.
description	(optional) Detailed description of the item.
unit_cost	(optional) Cost of a single unit of this item.
quantity	(optional) Number of units purchased.
discount	(optional) Discounted amount for this item.
created_at	(optional) Date when this item was created.

Seller

Parameter	Description
id	(required) Seller's id
name	(optional) Sellers's name
created_at	(optional) Date when the seller was created

Travel

Parameter	Description
type	(required) The travel type (flight or bus).
departure_leg	(required) An instance of either KondutoBusTravelLeg (if type is bus) or KondutoFlightTravelLeg (if type is flight)
return_leg	(optional) An instance of either KondutoBusTravelLeg or KondutoFlightTravelLeg.
passengers	(optional) A list of KondutoPassenger

Common travel leg attributes

Parameter	Description
date	(required) The travel date
number_of_connections	(optional) The number of connections
class	(optional) see KondutoTravelClass
fare_basis	(optional)

Bus travel leg specifics

Parameter	Description
origin_city	(required) The leg origin city
destination_city	(required) The leg destination city

Flight travel leg specifics

Parameter	Description
origin_airport	(required) The leg origin airport IATA code (e.g: GRU, LAX)
destination_airport	(required) The leg destination airport IATA code
origin_city	(optional) The leg origin city
destination_city	(optional) The leg destination city

Passenger

Parameter	Description
name	(required) The travel type (flight or bus)
document	(required) The passenger's document
document_type	(required) The passenger's document type (e.g passport). See KondutoDocumentType
frequent_traveler	(optional) A boolean. Is this passenger a frequent traveler?
special_needs	(optional) A boolean. Does the passenger have special needs?

Events

Parameter	Description
name	(required) The name of the event
date	(required) When the event is going to happen
type	(required) The type of the event (e.g., show, sports, theater, etc). For the complete list, see KondutoEventType enum.
subtype	(optional)
venue	(optional) The event's location address. See Event Venue bellow.
tickets	(optional) A list of tickets for the given event. See Event Ticket below.

Event Venue

Parameter	Description
name	(optional) The name of the place (e.g. Wembley Stadium, World Trade Center).
capacity	(optional) The total amount of available tickets for sale.
address	(optional) The specific location.
city	(optional)
state	(optional)
country	(optional) The country abbreviation code (e.g., BR, US, AU, etc)

Event Ticket

Parameter	Description
id	(optional) A unique identifier for the ticket.
category	(required) The ticket type, such as senior, student or regular. For the complete list, see KondutoEventTicketCategory enum.
section	(optional) The location of the ticket (e.g., lower seats, upper seats, unseated, etc).
premium	(required) Boolean that indicates if the ticket is a premium one.
attendee	(optional) Information about the ticket owner. See KondutoEventTicketAttendee bellow.

Event Ticket Attendee

Parameter	Description
name	(optional) The attendee's name.
document	(required) The attendee document value.
documentType	(optional) The type of document informed, such as CPF, CNPJ, passport, etc. For the complete list, see KondutoEventTicketAttendeeDocumentType enum.
dateOfBirth	(optional) A string with the attendee's date of birth.
=======

Vehicle

Parameter	Description
vid	(optional) Vehicle's ISO unique identifier.
renavam	(optional) Brazilian RENAVAM identifier.
registration	(optional) License plate for cars, registration for aircraft or boats.
make	(required) Name of the vehicle manufacturer company (e.g. Fiat).
model	(required) Name of the vehicle model (e.g. Camaro).
type	(optional) Enum containing several vehicle types such as CAR, AIRCRAFT, BUS, etc. See KondutoVehicleType.
usage	(optional) Enum containing several usage scenarios for vehicles such as PRIVATE, GOVERNMENT, etc. See KondutoVehicleUsage.
owner	(required) Object containing information regarding the owner of the vehicle. See Vehicle Owner below.

Vehicle Owner

Parameter	Description
tax_id	(required) Vehicle owner's tax id.
name	(optional) Vehicle owner's name.

Delivery

Parameter	Description
delivery_company	(optional) Adds the name of the company that will deliver the product to the customer.
delivery_method	(optional) Details the type of withdrawal type, if applicable.
estimated_shipping_date	(optional) Informs the shipping date of the product.
estimated_delivery_date	(optional) Informs the delivery date of the product.

Physical store (point_of_sale)

Parameter	Description
id	(required) A Unique identifier of the physical store.
name	(required) Full name of the physical store.
lat	(optional) Latitude of the physical store. We currently use maximum: -90, maximum: 90.
long	(optional) Length of the physical store. We currently use maximum: -180, maximum: 180.
address	(optional) Physical store address.
city	(optional) Physical store city.
state	(optional) State of the physical store.
zip	(optional) Physical store zip code.
contry	(optional) Country code of holder (ISO 3166-2).

Agent (Seller)

Parameter	Description
id	(required) A Seller's unique identifier.
login	(optional) Seller login.
name	(required) Seller's full name.
tax_id	(optional) Seller's tax document number (CPF, etc).
dob	(optional) Seller's date of birth in YYYY-MM-DD format (ISO 8601).
category	(optional) Category code of the product sold.
created_at	(optional) Date of creation of the account or registration of the seller on the website, in YYYY-MM-DD format (ISO 8601).

Safe Banking at Konduto

Safebank spans multiple nodes, the first node origin_account, which represents the source account in the balance and pix packets. The destination_accounts node brings a list that represents the destination accounts in payments of type amount and pix. The tenant node represents the platform (or marketplace) on which the pix transaction is taking place which can be declared within this tenant node.

Origin Account

Parameter	Description
id	(optional) Unique account identifier.
key_type	(optional) Key type used to identify the account. We currently support pix_cpf, pix_cnpj, pix_phone, pix_email, pix_evp, p2p and none.
key_value	(optional) Key value used to identify the account.
holder_name	(optional) Name of the account holder.
holder_tax_id	(optional) CPF/CNPJ of the account holder.
bank_code	(optional) Code of the bank to which the account is linked.
bank_name	(optional) Name of the bank to which the account is linked.
bank_branch	(optional) Branch of the bank to which the account is linked.
bank_account	(optional) Account number.
balance	(optional) Current account balance.

Destination Accounts

Parameter	Description
id	(optional) Unique account identifier.
key_type	(optional) Key type used to identify the account. We currently support pix_cpf, pix_cnpj, pix_phone, pix_email, pix_evp, p2p and none.
key_value	(optional) Key value used to identify the account.
holder_name	(optional) Name of the account holder.
holder_tax_id	(optional) CPF/CNPJ of the account holder.
bank_code	(optional) Code of the bank to which the account is linked.
bank_name	(optional) Name of the bank to which the account is linked.
bank_branch	(optional) Branch of the bank to which the account is linked.
bank_account	(optional) Account number.
amount	(optional) Amount sent to account.

Tenant

Parameter	Description
id	(required) unique platform identifier.
name	(optional) Platform name.
created_at	(optional) Platform creation date, in YYYY-MM-DD format (ISO 8601).

External Device

Parameter	Description
user_id	(optional) Unique account identifier.
fingerprint	(optional) Browser identification.
provider	(optional) supplier type ex: VTEX
category	(optional) device type ex: mobile, desktop.
model	(optional) device model ex: iphone 8, S10.
platform	(optional) Type of device by the customer.
manufacturer	(optional) manufacturer type ex: Samsung.
os	(optional) operational system ex: Android 11.
browser	(optional) Customer browser ex: Chrome.
language	(optional) local language ex: pt-br.

Sending an order for analysis.

After creating the order, sending it to Konduto's analysis is very simple.

if(order.isValid()){
	try {
		konduto.analyze(order);
		System.out.println("Konduto recommendation is to: " + order.getRecommendation());

	// A KondutoException will be thrown if the response is anything other than 200 OK.
	// You can catch more specific exceptions if you want to (e.g KondutoHTTPBadRequestException).
	catch(KondutoException e) {
		// Put any exception handling here.
		e.printStackTrace();
		persistAsNotAnalyzed(order, e.getMessage());
	}
} else {
    LOGGER.debug(order.getErrors());
}

Notice that if the analysis fails, a KondutoException will be thrown. Handle it as you wish.

Querying an order from our servers.

In order to do that use the Konduto class in the following way:

try {
	KondutoOrder order = konduto.getOrder(orderId); // orderId is a String
} catch (KondutoException e) {
	// Exception handling code
}

Updating an order status

try {
	// the order status will be set to newStatus if the request succeeds.
	konduto.updateOrderStatus(order, newStatus, "some comments"); 
} catch (KondutoException e) {
	// Exception handling code
}

Parameter	Description
status	(required) New status for this transaction. Either approved, declined or fraud, when you have identified a fraud or chargeback.
comments	(required) Reason or comments about the status update.

Sending requests through a proxy

To send requests through a proxy just build a new Konduto instance and set the proxy host passing both hostname and port as parameters of setProxyHost method. If the proxy requires username and password, set these credentials using the setProxyCredentials method.

String proxyHostname = "proxy.hostname";
int proxyPort = 1234;
Konduto konduto = new Konduto(API_KEY);
konduto.setProxyHost(proxyHostname, proxyPort);
// any object of kind org.apache.commons.httpclient.Credentials works 
// (as an example we use an instance of UsernamePasswordCredentials)
konduto.setProxyCredentials(new UsernamePasswordCredentials("username", "password")); 
// use Konduto's API as usual
konduto.getOrder(ORDER_ID);

Reference Tables

Please click here for the Currency and Category reference tables.

Troubleshooting

If you experience problems sending orders for analysis, querying orders or updating order status, it might be a good idea to call konduto.debug(). This will print out the API Key, the endpoint, the request body and the response body.

Support

Feel free to contact our support team if you have any questions or suggestions!

Physical store (point_of_sale)

Parameter	Description
id	(required) A Unique identifier of the physical store.
name	(required) Full name of the physical store.
lat	(optional) Latitude of the physical store. We currently use maximum: -90, maximum: 90.
long	(optional) Length of the physical store. We currently use maximum: -180, maximum: 180.
address	(optional) Physical store address.
city	(optional) Physical store city.
state	(optional) State of the physical store.
zip	(optional) Physical store zip code.
contry	(optional) Country code of holder (ISO 3166-2).

Agent (Seller)

Parameter	Description
id	(required) A Seller's unique identifier.
login	(optional) Seller login.
name	(required) Seller's full name.
tax_id	(optional) Seller's tax document number (CPF, etc).
dob	(optional) Seller's date of birth in YYYY-MM-DD format (ISO 8601).
category	(optional) Category code of the product sold.
created_at	(optional) Date of creation of the account or registration of the seller on the website, in YYYY-MM-DD format (ISO 8601).

Safe Banking at Konduto

Safebank spans multiple nodes, the first node origin_account, which represents the source account in the balance and pix packets. The destination_accounts node brings a list that represents the destination accounts in payments of type amount and pix. The tenant node represents the platform (or marketplace) on which the pix transaction is taking place which can be declared within this tenant node.

Origin Account

Parameter	Description
id	(optional) Unique account identifier.
key_type	(optional) Key type used to identify the account. We currently support pix_cpf, pix_cnpj, pix_phone, pix_email, pix_evp, p2p and none.
key_value	(optional) Key value used to identify the account.
holder_name	(optional) Name of the account holder.
holder_tax_id	(optional) CPF/CNPJ of the account holder.
bank_code	(optional) Code of the bank to which the account is linked.
bank_name	(optional) Name of the bank to which the account is linked.
bank_branch	(optional) Branch of the bank to which the account is linked.
bank_account	(optional) Account number.
balance	(optional) Current account balance.

Destination Accounts

Parameter	Description
id	(optional) Unique account identifier.
key_type	(optional) Key type used to identify the account. We currently support pix_cpf, pix_cnpj, pix_phone, pix_email, pix_evp, p2p and none.
key_value	(optional) Key value used to identify the account.
holder_name	(optional) Name of the account holder.
holder_tax_id	(optional) CPF/CNPJ of the account holder.
bank_code	(optional) Code of the bank to which the account is linked.
bank_name	(optional) Name of the bank to which the account is linked.
bank_branch	(optional) Branch of the bank to which the account is linked.
bank_account	(optional) Account number.
amount	(optional) Amount sent to account.

Tenant

Parameter	Description
id	(required) unique platform identifier.
name	(optional) Platform name.
created_at	(optional) Platform creation date, in YYYY-MM-DD format (ISO 8601).

External Device

Parameter	Description
fingerprint	(optional) Browser identification.
provider	(optional) supplier type ex: VTEX
category	(optional) device type ex: mobile, desktop.
model	(optional) device model ex: iphone 8, S10.
platform	(optional) Type of device by the customer.
manufacturer	(optional) manufacturer type ex: samsung.
os	(optional) operational system ex: android 11.
browser	(optional) Customer browser ex: chrome.
language	(optional) local language ex: pt-br.

Sending an order for analysis.

After creating the order, sending it to Konduto's analysis is very simple.

if(order.isValid()){
	try {
		konduto.analyze(order);
		System.out.println("Konduto recommendation is to: " + order.getRecommendation());

	// A KondutoException will be thrown if the response is anything other than 200 OK.
	// You can catch more specific exceptions if you want to (e.g KondutoHTTPBadRequestException).
	catch(KondutoException e) {
		// Put any exception handling here.
		e.printStackTrace();
		persistAsNotAnalyzed(order, e.getMessage());
	}
} else {
    LOGGER.debug(order.getErrors());
}

Notice that if the analysis fails, a KondutoException will be thrown. Handle it as you wish.

Querying an order from our servers.

In order to do that use the Konduto class in the following way:

try {
	KondutoOrder order = konduto.getOrder(orderId); // orderId is a String
} catch (KondutoException e) {
	// Exception handling code
}

Updating an order status

try {
	// the order status will be set to newStatus if the request succeeds.
	konduto.updateOrderStatus(order, newStatus, "some comments"); 
} catch (KondutoException e) {
	// Exception handling code
}

Parameter	Description
status	(required) New status for this transaction. Either approved, declined or fraud, when you have identified a fraud or chargeback.
comments	(required) Reason or comments about the status update.

Sending requests through a proxy

To send requests through a proxy just build a new Konduto instance and set the proxy host passing both hostname and port as parameters of setProxyHost method. If the proxy requires username and password, set these credentials using the setProxyCredentials method.

String proxyHostname = "proxy.hostname";
int proxyPort = 1234;
Konduto konduto = new Konduto(API_KEY);
konduto.setProxyHost(proxyHostname, proxyPort);
// any object of kind org.apache.commons.httpclient.Credentials works 
// (as an example we use an instance of UsernamePasswordCredentials)
konduto.setProxyCredentials(new UsernamePasswordCredentials("username", "password")); 
// use Konduto's API as usual
konduto.getOrder(ORDER_ID);

Reference Tables

Please click here for the Currency and Category reference tables.

Troubleshooting

If you experience problems sending orders for analysis, querying orders or updating order status, it might be a good idea to call konduto.debug(). This will print out the API Key, the endpoint, the request body and the response body.

Support

Feel free to contact our support team if you have any questions or suggestions!