dotnet-sdk

Konduto .NET SDK https://www.konduto.com

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 .NET SDK used for our API.

Requirements

• .NET Framework 4.0 or 4.5

Installation

Install our package avaiable at Nuget: https://www.nuget.org/packages/KdtSdk/

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
{
  Id = "123",
  TotalAmount = 123.4,
  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.Id = "123";
order.TotalAmount = 123.4;
order.Customer = 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.

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	(optional) 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-4217).
installments	(required) Number of installments in the payment plan (min: 1, max: 999).
ip	(recommended) 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) Timestamp (ISO 8601) of the first message exchanged between buyer and seller (for marketplace).
messages_exchanged	(optional) Total number of messages exchanged up to the transaction (for marketplace).
purchased_at	(optional) Date and time when the order was completed in the store (ISO 8601: YYYY-MM-DDTHH:mm:ssZ).
recurring	(optional) Boolean indicating if the transaction is a recurring subscription.
risk_level	(optional) Internal risk level assigned to the order (low, medium, high).
sales_channel	(optional) Sales channel used (e.g. e-commerce, mobile, pos, telemarketing).
scheduled	(optional) Boolean indicating if the transaction is scheduled (e.g. PIX / Safe Banking).
travel	(optional) Object containing travel and passenger details (flights / buses).
hotel	(optional) Object containing lodging and hotel reservation details.
events	(optional) Array containing ticket and event information.
vehicles	(optional) Object containing vehicle information.
seller	(optional) Object containing marketplace seller details.
point_of_sale	(optional) Object containing physical point-of-sale store details.
agent	(optional) Object containing physical attendant / sales agent details.
delivery	(optional) Object containing delivery and logistics tracking details.
device	(optional) Object containing external mobile/browser device telemetry and fingerprint.
tenant	(optional) Object identifying the sub-account or white-label tenant.
event_type	(optional) Type of banking event (Safe Banking / PIX).
event_details	(optional) Banking event details / subtype (Safe Banking / PIX).
origin_account	(optional) Object containing origin bank account details (Safe Banking / PIX).
destination_accounts	(optional) Array of destination bank accounts (Safe Banking / PIX).

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	(required) Customer's tax id (CPF or CNPJ).
phone1	(required) Customer's primary phone number.
phone2	(optional) Customer's secondary phone number.
dob	(optional) Customer's date of birth in YYYY-MM-DD format.
created_at	(optional) Customer registration date in store in YYYY-MM-DD format.
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.
type	(optional) Customer person type (PF for individual, PJ for legal entity).
risk_level	(optional) Internal risk level for customer (low, medium, high).
risk_score	(optional) Pre-calculated customer risk score.
mother_name	(optional) Customer's mother's full name.

Payment information

Parameter	Description
type	(required) Payment method type. Accepts: credit, boleto, debit, transfer, voucher, balance, pix.
status	(conditional required) The status of the transaction returned by the payment processor (required for credit and debit). Accepts approved, declined or pending.
bin	(conditional required) First 6 to 10 digits of the customer's card (required for credit and debit).
last4	(conditional required) Last 4 digits of the customer's card number (required for credit and debit).
expiration_date	(conditional required) Card's expiration date in MMYYYY format (required for credit and debit).
amount	(optional) Amount paid with this specific payment method.
currency	(optional) Currency code with 3 letters (ISO-4217).
description	(optional) Additional payment notes or discount details.
tax_id	(optional) Cardholder's tax ID (CPF).
cvv_result	(optional) CVV validation result (M for match, N for no match, P for not processed).
avs_result	(optional) Address verification service result.
sha1	(optional) Encrypted SHA-1 hash of the card number.
name	(optional) Buyer's name.
holder	(optional) Cardholder's name printed on card.
mcc	(optional) Merchant Category Code.
mid	(optional) Merchant ID in gateway / processor.
3ds_id	(optional) 3D Secure transaction ID.
merchant_tax_id	(optional) Merchant tax ID (CNPJ).
voucher_type	(optional) Voucher type (for voucher payments).

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).
estimatedDate	(optional) Estimated delivery date (ISO 8601: YYYY-MM-DDTHH:mm:ssZ).
value	(optional) Shipping value for this delivery.
lat	(optional) Latitude for the shipping destination.
lon	(optional) Longitude for the shipping destination.

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) Timestamp when the item was added to the cart (ISO 8601: YYYY-MM-DD).
deliveryType	(optional) Delivery type (e.g. express, standard).
deliverySlaInMinutes	(optional) Delivery SLA in minutes.
sellerId	(optional) Seller / merchant ID for marketplace orders.
image	(optional) URL of the product image.

Delivery and Logistics

Parameter	Description
delivery_company	(optional) Shipping company or courier name.
delivery_method	(optional) Delivery modality or method.
estimated_shipping_date	(required) Estimated shipping date (ISO 8601: YYYY-MM-DDTHH:mm:ssZ).
estimated_delivery_date	(required) Estimated delivery date (ISO 8601: YYYY-MM-DDTHH:mm:ssZ).

Travel (Flights & Buses)

Parameter	Description
type	(required) Travel type: flight or bus.
expiration_date	(optional) Expiration date (ISO 8601).
passengers	(required) Array of passenger objects: name (required), document (required), document_type (required), dob, nationality, frequent_traveler, special_needs, loyalty (program, category).
departure	(required) Departure segment object: origin_city, destination_city, origin_airport, destination_airport, date (required), number_of_connections, class, fare_basis, company.
return	(recommended) Return segment object: same fields as departure.

Hotel & Lodging

Parameter	Description
name	(required) Hotel or establishment name.
address1	(optional) Street address of the hotel.
address2	(optional) Additional hotel address information.
city	(optional) City where hotel is located.
state	(optional) State / province of the hotel.
zip	(optional) ZIP / postal code of the hotel.
country	(optional) Country code (ISO 3166-2).
category	(optional) Hotel category.
rooms	(required) Array of reserved room objects: number, code, type, check_in_date (required), check_out_date, number_of_guests, board_basis, guests (required).
guests (inside room)	(required) Array of guest objects: name (required), document, document_type, dob, nationality.

Events & Tickets

Parameter	Description
name	(required) Name of the event, show or concert.
date	(required) Event date and time (ISO 8601: YYYY-MM-DDTHH:mm:ssZ).
type	(required) Type of event.
subtype	(optional) Subtype of event.
venue	(optional) Venue object containing name, address, city, state, country, capacity.
tickets	(optional) Array of ticket objects: id, category (required), section, premium (required), attendee (required).
attendee (inside ticket)	(required) Array of attendee objects: name, document (required), document_type, dob.

Vehicles

Parameter	Description
vid	(optional) Vehicle Identification Number (17 characters).
renavam	(optional) Brazilian vehicle registration code (RENAVAM).
registration	(optional) Vehicle registration / plate code.
make	(required) Vehicle manufacturer / brand (e.g. Toyota, Volkswagen).
model	(required) Vehicle model (e.g. Corolla, Gol).
type	(optional) Vehicle type.
usage	(optional) Vehicle usage.
owner	(required) Array of owner objects: name, tax_id (required).

Marketplace Seller

Parameter	Description
id	(required) Unique partner store or seller identifier in marketplace.
name	(optional) Seller / store name.
created_at	(optional) Seller registration date in marketplace (YYYY-MM-DD).

Physical Point of Sale & Agent

Parameter	Description
point_of_sale	(optional) Physical POS object: id (required), name (required), lat, long, address, city, state, zip, country.
agent	(optional) Physical attendant / sales agent object: id (required), login, name (required), tax_id, dob, category, created_at (required).

Device Telemetry & External Device

Parameter	Description
fingerprint	(required) Device fingerprint hash generated by SDK.
provider	(optional) Fingerprint provider.
category	(optional) Device category.
model	(optional) Device model.
platform	(optional) Client operating system / platform.
manufacturer	(optional) Device manufacturer.
os	(optional) Operating system.
browser	(optional) Browser name.
language	(optional) Device system language.
flash	(optional) Flash support boolean.
cookie	(optional) Cookie support boolean.
javascript	(optional) JavaScript support boolean.
timezone	(optional) Timezone string.
user_id	(optional) User identifier.
ip	(optional) Public IP address observed on device.

Multi-tenant

Parameter	Description
id	(required) Sub-account or partner tenant identifier.
name	(required) Sub-account / tenant brand name.
created_at	(required) Sub-account creation timestamp (ISO 8601: YYYY-MM-DDTHH:mm:ssZ).

Safe Banking & PIX

Parameter	Description
event_type	(optional) Type of banking event (e.g. transfer, pix, pix_cashin, bill_payment).
event_details	(optional) Banking event details / subtype.
origin_account	(optional) Origin bank account object: id, key_type, key_value, holder_name, holder_tax_id, bank_code, bank_name, bank_branch, bank_account, balance.
destination_accounts	(optional) Array of destination bank account objects: id, key_type, key_value, holder_name, holder_tax_id, bank_code, bank_name, bank_branch, bank_account, amount.

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

After the analysis, some order attributes will be filled. For example the recommendation.

// The command below should print something like "Konduto recommendation is to APPROVE".
Console.WriteLine("Konduto recommendation is to: " + order.Recommendation);

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(orderId, 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.

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!

Publish in nuget

How to publish in Nuget

Deploy Local

docker build -t gerador-sdk .

docker run --rm -v "$(pwd)/pacotes:/output" gerador-sdk
<!-- Output file local KdtSdk.version.X.X.nupkg -->