konduto / dotnet-sdk

Konduto .NET SDK

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

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.

Payment information

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.

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.

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!

dotnet-sdk's Issues

Missing status field on KondutoOrderResponse

Hi, my name is Bruno, I have a problem

The status field is not found in the KondutoOrderResponse class, therefore when the analysis is performed in the response this value is lost.

Thank you i wait for your answer.

Support for events field

SDK does not support newer events fields in orders API yet.

Example

Here's an example of an order with the events field that can be provided using POST /v1/orders.

{
    "id": "Pedido000005",
    "total_amount": 123.45,
    "shipping_amount": 10.01,
    "tax_amount": 0.01,
    "installments": 2,
    "ip": "123.123.123.123",
    "currency": "BRL",
    "payment": [
        {
            "type": "credit",
            "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
            "bin": "490172",
            "last4": "1234",
            "expiration_date": "92017",
            "cvv_result": "A",
            "avs_result": "X",
            "status": "approved",
            "number_of_retries": 1,
            "amount": 123.45,
            "description": "pagamento via cartão de crédito"
        }
    ],
    "customer": {
        "id": "2937293",
        "name": "Fulano's de Tal",
        "tax_id": "283938282893",
        "phone1": "[phone]",
        "email": "[email protected]",
        "dob": "1970-02-02"
    },
    "events": [
        {
            "name": "Safadão no Maracanã",
            "date": "2021-01-01T03:00:00Z",
            "type": "show",
            "subtype": "sertanejo",
            "venue": {
                "name": "Estádio do Maracanã",
                "capacity": 80000,
                "address": "Av. Maracanã s/n",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "country": "BR"
            },
            "tickets": [
                {
                    "category": "regular",
                    "premium": true,
                    "section": "Pista Premium",
                    "attendee": {
                        "document": "12345678900",
                        "document_type": "cpf",
                        "dob": "1990-10-28"
                    }
                },
                {
                    "category": "student",
                    "premium": false
                }
            ]
        },
        {
            "name": "Heat @ Knicks",
            "date": "2020-11-21T01:00:00Z",
            "type": "sports",
            "subtype": "NBA",
            "tickets": [
                {
                    "category": "regular",
                    "premium": true,
                    "section": "general"
                },
                {
                    "category": "regular",
                    "section": "general",
                    "premium": true
                }
            ]
        }
    ]
}

Support for vehicle field

SDK does not support newer vehicle fields in orders API yet.

Example

Here's an example of an order with the vehicle field that can be provided by POST /v1/orders.

{
    "id": "Pedido000001",
    "visitor": "1234567890123456789012345678901234567890",
    "total_amount": 123.45,
    "shipping_amount": 10.01,
    "tax_amount": 0.01,
    "installments": 2,
    "ip": "123.123.123.123",
    "currency": "BRL",
    "customer": {
        "id": "2937593",
        "name": "Fulano's de Tal",
        "tax_id": "283938282893",
        "phone1": "[phone]",
        "email": "[email protected]",
        "dob": "1970-02-02"
    },
    "payment": [
        {
            "type": "credit",
            "bin": "490172",
            "last4": "1234",
            "expiration_date": "92017"
        }
    ],
    "vehicle": {
        "make": "Fiat",
        "model": "Palio",
        "renavam": "12593696135",
        "registration": "ABC1234",
        "owner": {
            "name": "Alfredo",
            "tax_id": "12345678900"
        },
        "type": "car"
    }
}

Passenger DOB must be optional

According to http://docs.konduto.com/pt/#enviar-um-pedido, the "dob" of the passenger is optional, but the library use the property [JsonProperty("dob", Required = Required.Always)].