README

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.

This document covers Konduto PHP SDK integration library that facilitates the integration with the Orders API in your PHP application. For more information about the service, other APIs and other integration details check out Konduto documentation.

Minimum requirements

PHP 5.4 or later
cURL extension

Local development without host PHP

If your machine does not have php installed, you can run everything with Docker.

docker run --rm -v "$PWD:/app" -w /app composer:2 install --ignore-platform-reqs
docker run --rm -v "$PWD:/app" -w /app php:7.4-cli php vendor/bin/phpunit tests/unit

Notes:

The library itself has no runtime dependencies and keeps supporting PHP 5.4+.
Tests run on phpunit/phpunit:^9.6, which requires PHP 7.3 or later. That requirement applies to the test suite only, not to applications using this SDK.

Installation with Composer

{
    "require": {
        "konduto/sdk": "v2.4.1"
    }
}

For older versions of this library check the releases section. We strongly recommend using the latest version possible.

Getting started

When a customer makes a purchase on your e-commerce you should input the order information into Konduto's Orders API so it can be analyzed for fraud risk. The analysis happens in real-time and will return you a recommendation of what to do next and a score, a numeric confidence level about that order's risk.

While most of the parameters are optional we recommend you send most 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.

Import Namespaces

Import the following Namespaces:

use Konduto\Core\Konduto;
use Konduto\Models;

Konduto provides methods for using Konduto services, such as sending an order for analysis (POST), querying (GET) or updating an existent order (PUT):

// Send order for analysis
$analyzedOrder = Konduto::analyze($order);

// Query a previously analyzed order
$order = Konduto::getOrder($orderId);

// Update the status of a previously analyzed order
Konduto::updateOrderStatus($orderId, $status, $comments);

Set your API key

Before using Konduto methods you need first to set your Konduto API key using the setApiKey() method. Check the official Konduto docs for how to obtain your API key:

Konduto::setApiKey("...YOUR_KONDUTO_PRIVATE_API_KEY...");

Send an order for analysis

Sending an order for analysis is as easy as calling the analyze method from Konduto core class for an Order object, as the snippet below shows. Use $order->getRecommendention() to see the recommendation for this order and $order->getScore() to know the score representing the order's risk that Konduto calculated for it.

try {
    $order = Konduto::analyze($order);
    echo "\nKonduto recommends you to {$order->getRecommendation()} this order.\n";
}
catch (Exception $e) {
    echo "\nKonduto wasn't able to return a recommendation: {$e->getMessage()}";
}

Every call performed with Konduto can throw an exception in case something goes wrong. Check the exception's message to see what went wrong. An example of what can go wrong is that a mandatory field wasn't provided, or a field was provided in the wrong format. Example:

{
    "status": "error",
    "message": {
        "where": "\/",
        "why": {
            "expected": "Authorized credentials",
            "found": "Missing or unauthorized credentials"
        }
    }
}

Building an Order

You can create an Order object (or any other model from Konduto SDK) in two ways: by providing an associative array with the allowed fields to the model's constructor or using the methods such as setters and getters.

Check the official Konduto documentation for reference to all fields accepted in the Konduto Orders API. Some fields are mandatory, like the order id and total amount, but most are optional.

You can provide order informatino using an associative array, like this:

$order = new Models\Order(array(
    "id" => uniqid(),
    "visitor" => "4738d516f09cab3a2c1ee973bec88a5a367a59e4",
    "total_amount" => 100.10,
    "shipping_amount" => 20.00,
    "tax_amount" => 3.45,
    "currency" => "USD",
    "installments" => 1,
    "ip" => "170.149.100.10",
    "purchased_at" => "2015-04-25T22:29:14Z",
    "customer" => array(
        "id" => "28372",
        "name" => "Júlia da Silva",
        "tax_id" => "12345678909",
        "dob" => "1970-12-25",
        "phone1" => "11-1234-5678",
        "phone2" => "21-2143-6578",
        "email" => "jsilva@exemplo.com.br",
        "created_at" => "2010-12-25",
        "new" => false,
        "vip" => false
    )
)));

Or using the methods provided by each model, like this:

$order = new Models\Order();
$order->setId(uniqid());
$order->setVisitor("4738d516f09cab3a2c1ee973bec88a5a367a59e4");
$order->setTotalAmount(100.10);
$order->setShippingAmount(20.00);
$order->setCurrency("USD");

$customer = new Models\Customer();
$customer->setName("Júlia da Silva");
$customer->setTaxId("12345678909");
$customer->setEmail("jsilva@exemplo.com.br");

$order->setCustomer($customer);

You can check all the possible models in src/Models/ folder.

Using dates and DateTime

This library automatically converts dates to the required API format. If it is convenient for you, you can directly provide a DateTime object to the fields that require dates.

$now = new \DateTime();
$customer->setCreatedAt($now);

Updating order status

After you decide what to do with the order you asked for analysis (e.g. approve, decline, fraud, cancel, not authorized) it is very important that you inform Konduto service about it. So the machine learning algorithm can learn better about your orders and improve itself. For this, you have to use the Konduto::updateOrderStatus() method.

Konduto::updateOrderStatus("ORD1237163", "approved", "Comments about this order");

Konduto::updateOrderStatus($orderId, $status, $comments);

Parameter	Description
orderId	(required) The id for the order
status	(required) String of one of the possible order status, check the available status.
comments	(required) Reason or comments about the status update.

Querying orders

$orderId = "ORD1237163";
$order = Konduto::getOrder($orderId);

Reference Tables

Please click here for the Currency and Category reference tables.

Payload field alignment (docs compatibility)

Recent updates aligned model fields with the documentation at https://docs.konduto.com/reference/enviar-um-pedido and its child pages.

Breaking naming changes

The SDK now serializes only documented names for these objects:

Object	Legacy field(s)	Official field(s)
Order	`agentSeller`	`agent`
Order	`pointOfSale`	`point_of_sale`
Order	`bankOriginAccount`	`origin_account`
Order	`bankDestinationAccount`	`destination_accounts`
Delivery	`deliveryCompany`	`delivery_company`
Delivery	`deliveryMethod`	`delivery_method`
Delivery	`estimatedShippingDate`	`estimated_shipping_date`
Delivery	`estimatedDeliveryDate`	`estimated_delivery_date`
Agent	`taxId`	`tax_id`

If your integration still sends legacy names, update your payload builder to the official fields above.

Order payload fields by object

Reference source: https://docs.konduto.com/reference/enviar-um-pedido and child pages. Tables follow the same format as the official docs: each row's Description starts with an italic tag — (required), (recommended) or (optional) — followed by the field's format/pattern (data type, enum values or date format) and its purpose.

Obligation for Order parameters was confirmed against the official docs page. Obligation for nested objects (Customer, Payment, Address, Travel, Hotel, etc.) was not shown on the page yet, so it was estimated conservatively as (optional) except where the SDK enforces a field to work at all (e.g. payment.type, travel.type, used to pick the right subclass). Please confirm with Konduto's docs/support for any nested field before relying on this SDK for validation.

Order parameters

Parameter	Description
id	(required) string. Unique identifier for each order.
visitor	(optional) string. Visitor identifier obtained from our JavaScript snippet.
total_amount	(required) decimal (e.g. `100.10`). Total order amount.
shipping_amount	(optional) decimal. Shipping and handling amount.
tax_amount	(optional) decimal. Taxes amount.
currency	(optional) string, 3 letters (ISO-4217, e.g. `USD`, `BRL`). Currency code.
installments	(required) integer (min: 1, max: 999). Number of installments in the payment plan.
ip	(recommended) string, IPv4 or IPv6. Customer's IP address.
customer	(required) `Customer` object. Object containing the customer details.
payment	(optional) array of `Payment` objects. Array containing the payment methods.
billing	(optional) `Address` object. Object containing the billing information.
shipping	(optional) `Address` object. Object containing the shipping information.
shopping_cart	(optional) array of `Item` objects. Shopping cart items.
first_message	(optional) `YYYY-MM-DDThh:mmZ`. Marketplace first message datetime.
messages_exchanged	(optional) integer. Marketplace messages count.
purchased_at	(optional) `YYYY-MM-DDTHH:mm:ssZ`. Order purchase datetime.
recurring	(optional) boolean. Recurring transaction flag.
risk_level	(optional) string. Order risk level.
analyze	(optional) boolean. Analyze flag.
sales_channel	(optional) string. Sales channel.
hotel	(optional) `Hotel` object. Hotel object.
travel	(optional) `Travel` object. Travel object.
seller	(optional) `Seller` object. Seller object.
events	(optional) array of `Event` objects. Event list.
scheduled	(optional) boolean. Scheduled transaction flag.
origin_account	(optional) `BankOriginAccount` object. Origin account object.
destination_accounts	(optional) array of `BankDestinationAccount` objects. Destination account list.
tenant	(optional) `Tenant` object. Tenant object.
point_of_sale	(optional) `PointOfSale` object. Point-of-sale object.
agent	(optional) `AgentSeller` object. Agent object.

Customer information

Parameter	Description
id	(optional) string. Customer unique identifier.
name	(optional) string. Customer full name.
email	(optional) string, email format. Customer email.
dob	(optional) `YYYY-MM-DD`. Date of birth.
tax_id	(optional) string (CPF/CNPJ/SSN, etc.). Customer tax document.
phone1	(optional) string. Primary phone number.
phone2	(optional) string. Secondary phone number.
created_at	(optional) `YYYY-MM-DD`. Customer creation date.
new	(optional) boolean. New customer flag.
vip	(optional) boolean. VIP customer flag.
type	(optional) string. Customer type.
risk_level	(optional) string. Customer risk level.
risk_score	(optional) numeric. Customer risk score.
mother_name	(optional) string. Customer mother name.

Payment information

Parameter	Description
type	(required) enum: `credit`, `boleto`, `debit`, `transfer`, `voucher`, `balance`, `pix`. Payment method type (defines the SDK subclass: `CreditCard`/`Boleto`/`Payment`).
status	(optional) enum: `approved`, `declined`, `pending`. Payment status.
bin	(optional) string, 6 digits (`credit` only). Card BIN.
last4	(optional) string, 4 digits (`credit` only). Last 4 card digits.
amount	(optional) decimal. Amount paid in this method.
expiration_date	(optional) `MMYYYY` for credit card or `YYYY-MM-DD` for boleto. Card expiration or boleto expiration date.
description	(optional) string. Payment description.
tax_id	(optional) string. Cardholder tax document.
cvv_result	(optional) string. CVV verification result.
avs_result	(optional) string. AVS verification result.
sha1	(optional) string, SHA1 hash. Encrypted card hash.
name	(optional) string. Buyer name.
holder	(optional) string. Card holder name.
mcc	(optional) string. Merchant category code.
mid	(optional) string. Merchant identifier.
3ds_id	(optional) string. 3DS transaction identifier.
merchant_tax_id	(optional) string. Merchant tax document.
voucher_type	(optional) string (`voucher` only). Voucher type.

Billing address

Parameter	Description
name	(optional) string. Billing recipient name.
address1	(optional) string. Billing address line 1.
address2	(optional) string. Billing address line 2.
city	(optional) string. Billing city.
state	(optional) string. Billing state.
zip	(optional) string. Billing ZIP code.
country	(optional) string, ISO-3166 alpha-2 (e.g. `BR`, `US`). Billing country code.

Shipping address

Parameter	Description
name	(optional) string. Shipping recipient name.
address1	(optional) string. Shipping address line 1.
address2	(optional) string. Shipping address line 2.
city	(optional) string. Shipping city.
state	(optional) string. Shipping state.
zip	(optional) string. Shipping ZIP code.
country	(optional) string, ISO-3166 alpha-2. Shipping country code.
estimatedDate	(optional) date. Estimated delivery date.
value	(optional) decimal. Shipping value.
lat	(optional) float. Destination latitude.
lon	(optional) float. Destination longitude.

Delivery and logistics

Parameter	Description
delivery_company	(optional) string. Delivery company.
delivery_method	(optional) string. Delivery method.
estimated_shipping_date	(optional) date/string. Estimated shipping date.
estimated_delivery_date	(optional) date/string. Estimated delivery date.

Device information

Parameter	Description
fingerprint	(optional) string. Device fingerprint.
provider	(optional) string. Device provider.
category	(optional) string. Device category.
model	(optional) string. Device model.
platform	(optional) string. Device platform.
manufacturer	(optional) string. Device manufacturer.
os	(optional) string. Device operating system.
browser	(optional) string. Device browser.
language	(optional) string. Device language.
flash	(optional) boolean. Flash enabled flag.
cookie	(optional) boolean. Cookie enabled flag.
javascript	(optional) boolean. JavaScript enabled flag.
timezone	(optional) string/integer. Device timezone.
user_id	(optional) string. Device user identifier.

Shopping cart

Parameter	Description
sku	(optional) string. Product SKU.
product_code	(optional) string. Product code.
category	(optional) string. Product category.
name	(optional) string. Product name.
description	(optional) string. Product description.
unit_cost	(optional) decimal. Item unit cost.
quantity	(optional) integer. Item quantity.
discount	(optional) decimal. Item discount.
created_at	(optional) `YYYY-MM-DD`. Item creation date.
deliveryType	(optional) string. Item delivery type.
deliverySlaInMinutes	(optional) integer. Delivery SLA in minutes.
sellerId	(optional) string. Marketplace seller identifier.
image	(optional) string, URL. Product image URL.

Travel

Parameter	Description
type	(required) enum: `flight`, `bus`. Travel type. Decides whether `departure`/`return` are parsed as `FlightLeg` or `BusTravelLeg`.
expiration_date	(optional) `YYYY-MM-DDTHH:mm:ssZ`. Travel expiration date.
departure	(optional) `TravelLeg` object (`FlightLeg`/`BusTravelLeg`). Outbound segment object.
return	(optional) `TravelLeg` object (`FlightLeg`/`BusTravelLeg`). Return segment object.
passengers	(optional) array of `Passenger` objects. Passenger list.

Travel leg (`departure` and `return`)

Parameter	Description
origin_city	(optional) string (only when `travel.type = bus`). Origin city.
destination_city	(optional) string (only when `travel.type = bus`). Destination city.
origin_airport	(optional) string, 3-letter IATA code (only when `travel.type = flight`). Origin airport code.
destination_airport	(optional) string, 3-letter IATA code (only when `travel.type = flight`). Destination airport code.
date	(optional) `YYYY-MM-DDTHH:mmZ` (no seconds). Departure datetime.
number_of_connections	(optional) integer. Number of connections.
class	(optional) string. Travel class.
fare_basis	(optional) string. Fare basis code.
company	(optional) string. Travel company.

Passenger

Parameter	Description
name	(optional) string. Passenger name.
document	(optional) string. Passenger document.
document_type	(optional) string. Passenger document type.
dob	(optional) `YYYY-MM-DD`. Passenger date of birth.
nationality	(optional) string, ISO-3166 alpha-2. Passenger nationality.
frequent_traveler	(optional) boolean. Frequent traveler flag.
special_needs	(optional) boolean. Special needs flag.
loyalty	(optional) `Loyalty` object. Loyalty object.

Loyalty

Parameter	Description
program	(optional) string. Loyalty program.
category	(optional) string. Loyalty category.

Hotel

Parameter	Description
name	(optional) string. Hotel name.
address1	(optional) string. Hotel address line 1.
address2	(optional) string. Hotel address line 2.
city	(optional) string. Hotel city.
state	(optional) string. Hotel state.
zip	(optional) string. Hotel ZIP code.
country	(optional) string, ISO-3166 alpha-2. Hotel country code.
category	(optional) string. Hotel category.
rooms	(optional) array of `HotelRoom` objects. Room list.

Hotel room

Parameter	Description
number	(optional) string. Room number.
code	(optional) string. Room code.
type	(optional) string. Room type.
check_in_date	(optional) `YYYY-MM-DD`. Check-in date.
check_out_date	(optional) `YYYY-MM-DD`. Check-out date.
number_of_guests	(optional) integer. Number of guests.
board_basis	(optional) string. Board basis.
guests	(optional) array of `HotelRoomGuest` objects. Guest list.

Hotel room guest

Parameter	Description
name	(optional) string. Guest name.
document	(optional) string. Guest document.
document_type	(optional) string. Guest document type.
dob	(optional) `YYYY-MM-DD`. Guest date of birth.
nationality	(optional) string, ISO-3166 alpha-2. Guest nationality.

Event

Parameter	Description
name	(optional) string. Event name.
date	(optional) `YYYY-MM-DDTHH:mm:ssZ`. Event datetime.
type	(optional) string. Event type.
subtype	(optional) string. Event subtype.
venue	(optional) `Venue` object. Venue object.
tickets	(optional) array of `Ticket` objects. Ticket list.

Venue

Parameter	Description
name	(optional) string. Venue name.
address	(optional) string. Venue address.
city	(optional) string. Venue city.
state	(optional) string. Venue state.
country	(optional) string, ISO-3166 alpha-2. Venue country.
capacity	(optional) integer. Venue capacity.

Ticket

Parameter	Description
id	(optional) string. Ticket identifier.
category	(optional) string. Ticket category.
section	(optional) string. Ticket section.
premium	(optional) boolean. Premium ticket flag.
attendee	(optional) `Attendee` object. Attendee object.

Attendee

Parameter	Description
name	(optional) string. Attendee name.
document	(optional) string. Attendee document.
document_type	(optional) string. Attendee document type.
dob	(optional) `YYYY-MM-DD`. Attendee date of birth.

Seller

Parameter	Description
id	(optional) string. Seller identifier.
name	(optional) string. Seller name.
created_at	(optional) `YYYY-MM-DD`. Seller creation date.

Agent

Parameter	Description
id	(optional) string. Agent identifier.
login	(optional) string. Agent login.
name	(optional) string. Agent name.
tax_id	(optional) string. Agent tax document.
dob	(optional) `YYYY-MM-DD`. Agent date of birth.
category	(optional) string. Agent category.
created_at	(optional) `YYYY-MM-DD`. Agent creation date.

Point of sale

Parameter	Description
id	(optional) string. Point-of-sale identifier.
name	(optional) string. Point-of-sale name.
lat	(optional) float. Latitude.
lon	(optional) float. Longitude.
address	(optional) string. Address.
city	(optional) string. City.
state	(optional) string. State.
zip	(optional) string. ZIP code.
country	(optional) string, ISO-3166 alpha-2. Country code.

Tenant

Parameter	Description
id	(optional) string. Tenant identifier.
name	(optional) string. Tenant name.
created_at	(optional) `YYYY-MM-DD`. Tenant creation date.

Origin account

Parameter	Description
id	(optional) string. Origin account identifier.
key_type	(optional) string. Origin account key type.
key_value	(optional) string. Origin account key value.
holder_name	(optional) string. Origin account holder name.
holder_tax_id	(optional) string. Origin account holder tax document.
bank_code	(optional) string. Origin account bank code.
bank_name	(optional) string. Origin account bank name.
bank_branch	(optional) string. Origin account bank branch.
bank_account	(optional) string. Origin account number.
balance	(optional) decimal. Origin account balance.

Destination account

Parameter	Description
id	(optional) string. Destination account identifier.
key_type	(optional) string. Destination account key type.
key_value	(optional) string. Destination account key value.
holder_name	(optional) string. Destination account holder name.
holder_tax_id	(optional) string. Destination account holder tax document.
bank_code	(optional) string. Destination account bank code.
bank_name	(optional) string. Destination account bank name.
bank_branch	(optional) string. Destination account bank branch.
bank_account	(optional) string. Destination account number.
amount	(optional) decimal. Destination transfer amount.

Support

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

Contributing

Found a bug or missing feature? This is an open-source project, so a Pull Request will be more than welcome. Just make sure following the guidelines:

Respect the established naming conventions.
Don't introduce external dependencies.
Always add tests for covering new pieces of code.
Respect the minimum requirements. I.e. avoid using PHP libs and features that might require changing them. We want to provide this library to the broadest audience possible.

Testing

This project uses PHPUnit as its testing framework. Before running any test, make sure you install it. To install all project's dependencies using Composer run a composer install first:

// This command might change depending on your Composer installation.
composer install

With Docker (no host PHP required):

docker run --rm -v "$PWD:/app" -w /app composer:2 install --ignore-platform-reqs

There are two types of test:

Unit tests: Just test the logic of the code. They are located at tests/unit/.

You can run the unit tests with the command:

vendor/bin/phpunit tests/unit

Docker equivalent:

docker run --rm -v "$PWD:/app" -w /app php:7.4-cli php vendor/bin/phpunit tests/unit

Integration tests: Make actual calls to Konduto's sandbox API to check the integration. They are located at tests/integration/.

Before running the integration tests you will need to provide a working sandbox API key as an environment variable KONDUTO_SANDBOX_API_KEY. If you don't do this all integration tests will fail.

export KONDUTO_SANDBOX_API_KEY=your_api_key

Now you can run the integration tests:

vendor/bin/phpunit tests/integration