NAV

Introduction

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.

In this page you will find the technical specs for our REST API, as well as integration libraries for the most popular languages.

We are constantly improving this document and we appreciate any feedback you have. You can drop us a line at hi@konduto.com with questions and suggestions about how to improve it.

Helper libraries

php-sdk - PHP helper
java-sdk - Java helper
dotnet-sdk - .NET helper

We offer SDKs to help with the development effort as well as plugin integrations with common e-commerce platforms. Below you will find a list of the integrations available to date, which are hosted on our Github page.

If you don’t see your SDK or platform listed here please drop us a line at hi@konduto.com, we’d love to hear from you!

API Authentication

# How to build
Authorization: Basic BASE64(T738D516F09CAB3A2C1EE:)

# Result
Authorization: Basic VDczOEQ1MTZGMDlDQUIzQTJDMUVFOg==

We use the HTTP Basic Auth standard to authenticate access to our API.

In this type of authentication you must send an Authorization HTTP header that contains the word Basic followed by a Base64 of your private key.

If you use one of our helper libraries then this process is already covered and you just need to set your key.

Orders API

Orders API Endpoints

POST https://api.konduto.com/v1/orders
PUT  https://api.konduto.com/v1/orders/{order_id}
GET  https://api.konduto.com/v1/orders/{order_id}

When the customer places the order you must send us the purchase data to our REST API so we can analyze it. We respond in real time with a recommendation of what to do and a score, which is our confidence level.

While many parameters are optional we recommend that you send as much as possible, because each data point makes a difference in the analysis.

The billing address and credit card information are specially important, but we understand there are cases where you don’t have it available.

Send an order

You can send new transactions using the POST method and passing a JSON in the request’s body.

The request consists of a root object containing information related to the order as well as a customer, billing, shipping and travel objects and the payment and shopping_cart arrays.

Order

{
  "id":"10000000001",
  "visitor":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
  "total_amount":100.00,
  "shipping_amount":20.00,
  "tax_amount":3.45,
  "currency":"USD",
  "installments":2,
  "ip":"170.149.100.10",
  "first_message":"2018-12-20T15:59:01Z",
  "messages_exchanged":30,
  "purchased_at":"2018-12-25T12:00:25Z",
  "analyze":true,
  "customer":{ },
  "payment":[ ],
  "billing":{ },
  "shipping":{  },
  "shopping_cart":[ ],
  "travel":{ },
  "seller":{ }
}

The root of the Order object contains basic information about the purchase, such as order number, amount and currency.

Parameter Description
id (required)
Unique identifier for each order.
Max. 100 chars, alphanumeric.
visitor (optional)
Visitor identifier obtained from our JavaScript snippet.
Exactly 40 chars, alphanumeric.
total_amount (required)
Total order amount.
Max. 10 digits, number.
shipping_amount (optional)
Shipping and handling amount.
Max. 10 digits, number.
tax_amount (optional)
Taxes amount.
Max. 10 digits, number.
currency (optional)
Currency code with 3 letters (ISO-4712).
Exactly 3 chars, string.
installments (optional)
Number of installments in the payment plan.
Max. 3 digits, number.
ip (optional)
Customer’s IPv4 address.
Max. 15 chars, string.
first_message (optional)
In Marketplaces, it’s the date and time of the first message exchanged between buyer and seller. YYYY-MM-DDTHH:mm:ssZ format (ISO 8601)
Exactly 20 chars, string.
messages_exchanged (optional)
In Marketplaces, should contain the number of messages exchanged between buyer and seller up until the order was placed.
Number.
purchased_at (optional)
In Marketplaces, it’s the date and time the order was closed. YYYY-MM-DDTHH:mm:ssZ format (ISO 8601)
Exactly 20 chars, string.
analyze (optional)
If false we take the transaction into account in future analyses but we don’t reply with a recommendation and you are not billed.
Boolean, defaults to true.
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.
travel (optional)
Object containing the travel and passenger information.

Customer         customer

{
  "customer": {
    "id":"28372",
    "name":"Mary Jane",
    "tax_id":"6253407",
    "dob":"1970-12-25",
    "phone1":"212-555-1234",
    "phone2":"202-555-6789",
    "email":"mary.jane@example.com",
    "created_at":"2010-12-25",
    "new":false,
    "vip":false
  }
}

This object must be used to send information about the buyer, which in most cases is the person logged into your application.

To send data about the cardholder or the product recipient you must use the billing and shipping objects respectively.

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.
Max. 100 chars, string.
name (required)
Customer’s full name.
Max. 100 chars, string.
email (required)
Customer’s e-mail address
Max. 100 chars, string.
dob (optional)
Customer’s date of birth in YYYY-MM-DD format (ISO 8601).
Exactly 10 chars, string.
tax_id (optional)
Customer’s tax id.
Max. 100 chars, string.
phone1 (optional)
Customer’s primary phone number
Max. 100 chars, string.
phone2 (optional)
Customer’s secondary phone number
Max. 100 chars, string.
created_at (optional)
Customer account creation date, in YYYY-MM-DD format (ISO 8601).
Exactly 10 chars, string.
new (optional)
Flag indicating if the customer is using a newly created account for this purchase.
Boolean.
vip (optional)
Flag indicating if the customer is a VIP or frequent buyer.
Boolean.

Payment Methods         payment

{  
  "payment":[  
    {  
      "type":"credit",
      "bin":"490172",
      "last4":"0012",
      "expiration_date":"072015",
      "status":"approved"
    },
    {  
      "type":"credit",
      "bin":"514800",
      "last4":"3752",
      "expiration_date":"082016",
      "status":"approved"
    }
  ]
}

This object contains the payment methods used for the purchase. This is an array, so if the order was paid using multiple payment methods you can send the list over to analysis.

Parameter Description
type (required)
Payment type used by the customer. We support credit, boleto, debit, transfer and voucher.
Max. 8 chars, string.
status (required if ‘credit’)
The status of the transaction returned by the payment processor. Accepts approved, declined or pending if the payment wasn’t been processed yet.
Max. 8 chars, string.
bin (optional)
First six digits of the customer’s credit card. Used to identify the type of card being sent.
Exactly 6 chars, string.
last4 (optional)
Four last digits of the customer’s credit card number.
Exactly 4 chars, string.
expiration_date (optional)
Card’s expiration date under MMYYYY format.
Exactly 6 chars, string.

Billing Address         billing

{  
  "billing":{  
    "name":"Mary Jane",
    "address1":"123 Main St.",
    "address2":"Apartment 4",
    "city":"New York City",
    "state":"NY",
    "zip":"10460",
    "country":"US"
  }
}

This object must containg the cardholder information.

Parameter Description
name (optional)
Cardholder’s full name.
Max. 100 chars, string.
address1 (optional)
Cardholder’s billing address on file with the bank.
Max. 255 chars, string.
address2 (optional)
Additional cardholder address information.
Max. 255 chars, string.
city (optional)
Cardholder’s city.
Max. 100 chars, string.
state (optional)
Cardholder’s state.
Max. 100 chars, string.
zip (optional)
Cardholder’s ZIP code.
Max. 100 chars, string.
country (optional)
Cardholder’s country code (ISO 3166-2)
Exactly 2 chars, string.

Shipping Address         shipping

{  
  "shipping":{  
    "name":"Mary Jane",
    "address1":"123 Main St.",
    "address2":"Apartment 4",
    "city":"New York City",
    "state":"NY",
    "zip":"10460",
    "country":"US"
  }
}

This object must contain the shipping information of the purchase. There is no need to send it if this is a service or software download.

Parameter Description
name (optional)
Recipient’s full name.
Max. 100 chars, string.
address1 (optional)
Recipient’s shipping address.
Max. 255 chars, string.
address2 (optional)
Additional recipient address information.
Max. 255 chars, string.
city (optional)
Recipient’s city.
Max. 100 chars, string.
state (optional)
Recipient’s state.
Max. 100 chars, string.
zip (optional)
Recipient’s ZIP code.
Max. 100 chars, string.
country (optional)
Recipient’s country code (ISO 3166-2)
Exactly 2 chars, string.

Shopping Cart         shopping_cart

{  
  "shopping_cart":[  
    {  
      "sku":"9919023",
      "product_code":"123456789999",
      "category":201,
      "name":"Green T-Shirt",
      "description":"Male Green T-Shirt V Neck",
      "unit_cost":29.99,
      "quantity":1,
      "created_at":"2008-12-25"
    },
    {  
      "sku":"0017273",
      "category":202,
      "name":"Yellow Socks",
      "description":"Pair of Yellow Socks",
      "unit_cost":7.50,
      "quantity":2,
      "discount":1.00
    }
  ]
}

This list of objects contains the products added to the order and their details.

Parameter Description
sku (optional)
Product or service’s SKU or inventory id.
Max. 100 chars, string.
product_code (optional)
Product or service’s UPC, barcode or secondary id.
Max. 100 chars, string.
category (optional)
Category code for the item purchased.
See our category codes for more information .
Max. 4 digits, number.
name (optional)
Name of the product or service.
Max. 100 chars, string.
description (optional)
Detailed description of the item.
Max. 100 chars, string.
unit_cost (optional)
Cost of a single unit of this item.
Max. 10 digits, number.
quantity (optional)
Number of units purchased.
Max. 10 digits, number.
discount (optional)
Discounted amount for this item.
Max. 10 digits, number.
created_at (optional)
Date the product was first posted, in YYYY-MM-DD format (ISO 8601).
Exactly 10 chars, string.

Travel         travel

{  
  "travel":{  
    "type":"flight",
    "departure":{  
      "origin_airport":"GRU",
      "destination_airport":"SFO",
      "date":"2018-12-25T18:00Z",
      "number_of_connections":1,
      "class":"economy",
      "fare_basis":"Y"
    },
    "return":{  
      "origin_airport":"SFO",
      "destination_airport":"GRU",
      "date":"2018-12-30T18:00Z",
      "number_of_connections":1,
      "class":"business"
    },
    "passengers":[  
      {  
        "name":"Mary Jane",
        "document":"6253407",
        "document_type":"id",
        "dob":"1970-01-01",
        "nationality":"BR",
        "loyalty":{  
          "program":"smiles",
          "category":"gold"
        },
        "frequent_traveler":true,
        "special_needs":false
      },
      {  
        "name":"John Smith",
        "document":"XYZ1234",
        "document_type":"passport",
        "dob":"1970-12-01",
        "nationality":"US",
        "loyalty":{  
          "program":"multiplus",
          "category":"silver"
        },
        "frequent_traveler":false,
        "special_needs":true
      }
    ]
  }
}

Holds data about the transportation and passengers. Travel data is divided between departure and return legs. Passenger data goes into the passengers array.

Parameter Description
type (required)
Transportation type. Currently flight or bus are supported.
departure (required)
Object with the departure information.
return (optional)
Object with the return information.
passengers (required)
Array of objects with the passenger details.

Travel information

Parameter Description
origin_city (required if type=bus)
City of origin.
Max 100 chars, string.
destination_city (required if type=bus)
City of destination
Max 100 chars, string.
origin_airport (required if type=flight)
IATA code for airport of origin
Exactly 3 chars, string.
destination_airport (required if type=flight)
IATA code code for airport of destination
Exactly 3 chars, string.
date (required)
UTC date and time of departure in YYYY-MM-DDThh:mmZ format (ISO 8601)
Exactly 17 chars, string.
number_of_connections (optional)
Number of connections
class (optional)
Travel class name, like economy, business and first
Max. 8 chars, string.
fare_basis (optional)
Fase basis code.
Max 20 chars, string.

Passenger information

Parameter Description
name (required)
Passenger’s full name
Max 100 chars, string.
document (optional)
Document number
Max 100 chars, string.
document_type (optional)
Document type. Can be either passport or id.
Max 8 chars, string.
dob (optional)
Passenger’s date of birth in YYYY-MM-DD format (ISO 8601).
Exactly 10 chars, string.
nationality (optional)
Passenger’s country of birth (ISO 3166-2)
Exactly 2 chars, string.
frequent_traveler (optional)
Frequent flyer flag.
Boolean, defaults to false.
special_needs (optional)
Passenger with special needs.
Boolean, defaults to false.

Seller         seller

{ 
  "id":"37",
  "name":"Joe's Store",
  "created_at":"2009-11-25"
}

For Marketplaces, these fields are used to pass data about the Seller.

Parameter Description
id (required)
Seller unique identifier within the Marketplace.
Max. 100 chars, string.
name (optional)
Merchant or seller name
Max. 100 chars, string.
created_at (optional)
Seller creation date within the Marketplace, in YYYY-MM-DD format (ISO 8601)
Exatamente 10 chars, string.

Update fraud status

{  
  "status":"approved",
  "comments":"Shipping address confirmed by cardholder."
}

At any time you can update the status of an order using the PUT method and passing a new status and comments on the change.

The fraud status is not to be confused with the payment status. The fraud status inside Konduto has a direct influence on the algorithm and the risk analysis.

Parameter Description
status (required)
New status for this transaction. Either APPROVED, DECLINED, NOT_AUTHORIZED CANCELED or FRAUD, when you have identified a fraud or chargeback.
Max. 8 chars, string.
comments (required)
Reason or comments about the status update.
Max. 255 chars, string.

Query an order

GET https://api.konduto.com/v1/orders/ORD1837213

You can retrieve all the data for an order using the GET method. The response will include all transactional data about the order, including recommendation, score and current status.

Blacklist API

Email Blacklist URLs

POST    https://api.konduto.com/v1/blacklist/email
PUT     https://api.konduto.com/v1/blacklist/email/{email}
GET     https://api.konduto.com/v1/blacklist/email/{email}
DELETE  https://api.konduto.com/v1/blacklist/email/{email}

The Blacklist is a resource that allows you to block orders that contain certain data. Purchases made with this information will be declined automatically by our platform. You can add an entry to the Blacklist permanently or until a certain expiration date.

With the Blacklist API you can add, update, query and remove email addresses from the list.

Add an item

Example of adding an email to the Blacklist

{  
  "email_address":"mary.jane@example.com",
  "days_to_expire":180
}

To add an entry you must use the POST method. Once you add an entry, the next transaction will take the new data intro account.

Expiration date is optional. If set, the entry will be removed automatically once the deadline is reached. If not, the entry will remain in the Blacklist indefinitely.

Parameters to add an email

Parameter Description
email_address (required)
Customer’s e-mail address
Max. 100 chars, string.
days_to_expire (optional)
Days for this entry to be automatically removed from the Blacklist
Number.

Update an expiration date

Example of an update to the expiration date

{
  "days_to_expire": 360
}

Updating an item means changing it’s expiration date. You can move up or postpone the expiration date of an entry. It’s done through the PUT method.

Parameter Description
days_to_expire (required)
Days for this entry to be automatically removed from the Blacklist
Number.

Retrieve an item

GET https://api.konduto.com/v1/blacklist/email/mary.jane@example.com

You can query if an entry is already in the Blacklist. If it has an expiration date this value is also returned in the query.

Remove an item

DELETE https://api.konduto.com/v1/blacklist/email/mary.jane@example.com

To remove an entry from the Blacklist you must use the DELETE method.

Responses

HTTP Codes

200 OK # Success
201 Created # Item was created
400 Bad Request # Error in request
401 Unauthorized # Problem with key authentication
403 Forbidden # Problem with the account
404 Not Found # Not found
405 Method Not Allowed # Method does not exist
429 Too Many Requests # Request limit reached
444 No Response # No response
500 Server Error # Internal server error

Our API uses HTTP response codes to indicate the result of a request. Successful requests will be replied with a 200 OK code while failed requests will contain 400 or 5xx response codes.

There is also a status parameter is the response body indicating whether a request was successful or not.

Code Description
200 Request is valid and we have a response.
201 Item was added to the list.
400 There was a problem with request. The response body contains more information about the cause., most likely a syntax issue.
401 The API that was used is not valid. Please check the key format and it’s value in your dashboard.
403 There is a problem with your account. Please get in touch with us for more information.
404 The order was not found in our database.
405 The HTTP method used is not allowed for this resource.
429 You have reached the limit of permitted requests. Please get in touch with us for more information.
444 The address for the request is invalid and the server has closed the connection. Please check the URL you are using to send requests.
500 There was an internal error when processing your request. You should get in touch with us for more information.

Error responses

Our API’s error responses always show you the reason behind the error and, when possible, an indication of how to fix it.

The main reason for an API call to fail is a validation problem, meaning either syntax or the content of the values. If it’s an internal error within Konduto we will reply with a unique ID that can be sent to our support team for investigation.

Validation error response

Example where value was sent as a string

{  
  "status":"error",
  "message":{  
    "where":"/total_amount",
    "why":{  
      "expected":[  
        "integer",
        "number"
      ],
      "found":"string"
    }
  }
}
Parameter Description
where Field or object where the error ocurred.
why Causes of the validation error.
expected Expected data.
found Actual received data.
missing Required field missing.
unknown_field Unknown field.

Example of internal error

{  
  "status":"error",
  "message":{  
    "notification":"We've been notified about this error and will investigate it. Please keep this error identifier",
    "error_identifier":"09e1a98c-eada-4695-8864-bff8ba4707ba",
    "where":"/",
    "why":{  
      "expected":"ok",
      "found":"Internal error"
    }
  }
}

Internal error response

Parameter Description
notification Server error message
error_identifier Error unique ID, which can be sent to our support team for investigation.
where Field or object where the error ocurred.
why Causes of the validation error.
expected Expected data.
found Actual received data.

Orders API response

A successful response from the Orders API always returns two objects.

The status field indicates the success or failure of the request, and the order object contains the data of the order being handled. The contents of this object varies accoring to what request is being made.

Parameter Description
status Request status message. Responds ok for successful or error for failed requests.
order Object containing the analysis respose.

Analysis response

{  
  "status":"ok",
  "order":{  
    "id":"ORD1837213",
    "visitor":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "score":0.07,
    "recommendation":"review",
    "ip":"170.149.100.10",
    "device":{  
      "user_id": "405961fab293600daeed93ae561",
      "fingerprint": "e4f2c690951038a8f77aa583847",
      "platform": "MacIntel",
      "browser": "Chrome",
      "language": "en_US",
      "timezone": "GMT -1",
      "cookie": true,
      "javascript":  true,
      "flash": true
    },
    "geolocation":{  
      "city":"New York City",
      "state":"NY",
      "country":"US"
    },
    "navigation":{  
      "time_site_7d":15.0,
      "time_per_page_7d":2.0,
      "new_accounts_7d":0,
      "password_resets_7d":1,
      "checkout_count_7d":0,
      "sales_declined_7d":0,
      "sessions_7d":3,
      "time_site_1d":45.0,
      "new_accounts_1d":0,
      "password_resets_1d":0,
      "sales_declined_1d":0,
      "sessions_1d":1,
      "session_time":45.0,
      "time_since_last_sale":121.0,
      "referrer": "http://www.google.com/"
    }
  }
}

The response from our fraud engine returns the following fields inside the order object:

Object Parameter Description
- id Unique identifier sent in the request
- visitor Visitor identifier sent in the request
- score Transaction score between 0 and 1.

For transactions that were not analyzed the value -1 will be returned (see order.analyze parameter).
- recommendation Recommended action to be taken on the order. Can be APPROVE, REVIEW or DECLINE.

For transactions that were not analyzed the value NONE will be returned (see order.analyze parameter).
- status Current status for this transaction. Either APPROVED, PENDING, DECLINED, CANCELED, NOT_AUTHORIZED, NOT_ANALYZED or FRAUD
- device Object containing the device information collected
device user_id Unique user id for this visitor
device fingerprint Browser fingerprint
device platform Customer’s device type
device browser Customer’s browser
device language Customer’s browser language
device timezone Customer’s time zone in GMT
device cookie Flag indicating if customer has Cookies enabled
device javascript Flag indicating if customer has JavaScript enabled
device flash Flag indicating if customer has Java enabled
device ip Customer’s IP address
- geolocation Object containing the customer’s geolocation data
geolocation city Detected city
geolocation state Detected state
geolocation country Detected country
- navigation Object containing the customer’s navigation summary
navigation session_time Time of last session (in minutes)
navigation referrer Source of the visit
navigation time_site_1d Time user spent on the website in the past day (in minutes)
navigation new_accounts_1d Accounts created by the user in the past day
navigation password_resets_1d Password resets in the past day
navigation sales_declined_1d Orders declined linked to the user in the past day
navigation sessions_1d User visits (sessions) by the user in the past day
navigation time_since_last_sale Time since the last successul order (in minutes)
navigation time_site_7d Time user spent on the website in the past week (in minutes)
navigation time_per_page_7d Avg. time per page in the past week (in minutes)
navigation new_accounts_7d Accounts created by the user in the past week
navigation password_resets_7d Password resets in the past week
navigation checkout_count_7d Shopping cart views in the past week
navigation sales_declined_7d Orders declined linked to the user in the past week
navigation sessions_7d User visits (sessions) by the user in the past week

Update response

{
  "status": "ok",
  "order": {
    "old_status": "pending",
    "new_status": "approved"
  }
}

When you update the status of an order you get a response that contains the previous e current order status, i.e. what has just been changed. This happens even if the old and the new status are the same.

Parameter Description
old_status Old order status.
new_status New order status.

Query response

{  
  "status":"ok",
  "order":{  
    "id":"ORD1837213",
    "visitor":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "created_at":"2028-03-13T21:48:30Z",
    "updated_at":"2028-03-15T08:09:26Z",
    "score":0.07,
    "recommendation":"approve",
    "status":"approved",
    "ip":"170.149.100.10",
    "total_amount":159.61,
    "tax_amount":3.04,
    "shipping_amount":6.57,
    "currency":"USD",
    "first_message":"2018-12-20T15:59:01Z",
    "messages_exchanged":30,
    "purchased_at":"2018-12-25T12:00:25Z",
    "device":{  
      "user_id": "405961fab293600daeed93ae561",
      "fingerprint": "e4f2c690951038a8f77aa583847",
      "platform": "MacIntel",
      "browser": "Chrome",
      "language": "en_US",
      "timezone": "GMT -1",
      "cookie": true,
      "javascript":  true,
      "flash": true
    },
    "geolocation":{  
      "city":"New York City",
      "state":"NY",
      "country":"US"
    },
    "billing":{  
      "name":"Mary Jane",
      "address1":"123 Main St.",
      "address2":"Apartment 4",
      "city":"New York City",
      "state":"NY",
      "zip":"10460",
      "country":"US"
    },
    "shipping":{  
      "name":"Mary Jane",
      "address1":"123 Main St.",
      "address2":"Apartment 4",
      "city":"New York City",
      "state":"NY",
      "zip":"10460",
      "country":"US"
    },
    "customer":{  
      "id":"28372",
      "name":"Mary Jane",
      "tax_id":"6253407",
      "dob":"1970-12-25",
      "phone1":"212-555-1234",
      "phone2":"202-555-6789",
      "email":"mary.jane@example.com",
      "new":false,
      "vip":false
    },
    "navigation":{  
      "time_site_7d":15.0,
      "time_per_page_7d":2.0,
      "new_accounts_7d":0,
      "password_resets_7d":1,
      "checkout_count_7d":0,
      "sales_declined_7d":0,
      "sessions_7d":3,
      "time_site_1d":45.0,
      "new_accounts_1d":0,
      "password_resets_1d":0,
      "sales_declined_1d":0,
      "sessions_1d":1,
      "session_time":45.0,
      "time_since_last_sale":121.0,
      "referrer": "http://www.google.com/"
    },
    "payment":[  
      {  
        "type":"credit",
        "bin":"490172",
        "last4":"0012",
        "expiration_date":"072015",
        "status":"approved"
      },
      {  
        "type":"credit",
        "bin":"514800",
        "last4":"3752",
        "expiration_date":"082016",
        "status":"approved"
      }
    ],
    "shopping_cart":[  
      {  
        "sku":"9919023",
        "product_code":"123456789999",
        "category":201,
        "name":"Green T-Shirt",
        "description":"Male Green T-Shirt V Neck",
        "unit_cost":29.99,
        "quantity":1
      },
      {  
        "sku":"0017273",
        "category":202,
        "name":"Yellow Socks",
        "description":"Pair of Yellow Socks",
        "unit_cost":7.50,
        "quantity":2,
        "discount":1.00
      }
    ],
    "travel":{  
      "type":"flight",
      "departure":{  
        "origin_airport":"GRU",
        "destination_airport":"SFO",
        "date":"2018-12-25T18:00Z",
        "number_of_connections":1,
        "class":"economy",
        "fare_basis":"Y"
      },
      "return":{  
        "origin_airport":"SFO",
        "destination_airport":"GRU",
        "date":"2018-12-30T18:00Z",
        "number_of_connections":1,
        "class":"business"
      },
      "passengers":[  
        {  
          "name":"Mary Jane",
          "document":"6253407",
          "document_type":"id",
          "dob":"1970-01-01",
          "nationality":"BR",
          "loyalty":{  
            "program":"smiles",
            "category":"gold"
          },
          "frequent_traveler":true,
          "special_needs":false
        },
        {  
          "name":"John Smith",
          "document":"XYZ1234",
          "document_type":"passport",
          "dob":"1970-12-01",
          "nationality":"US",
          "loyalty":{  
            "program":"multiplus",
            "category":"silver"
          },
          "frequent_traveler":false,
          "special_needs":true
        }
      ]
    }
  }
}

When you query an order you get all the data related to that purchase, including data sent by the merchant and our analysis.

Object Parameter Description
- id Unique identifier sent in the request
- created_at Date and time of the transaction in YYYY-MM-DDThh:mmZ format (ISO 8601).
- updated_at Date and time of the last update on the transaction in YYYY-MM-DDThh:mmZ format (ISO 8601).
- visitor Visitor identifier sent in the request
- score Transaction score between 0 and 1.

For transactions that were not analyzed the value -1 will be returned (see order.analyze parameter).
- recommendation Recommended action to be taken on the order. Can be APPROVE, REVIEW or DECLINE.

For transactions that were not analyzed the value NONE will be returned (see order.analyze parameter).
- status Request status message. Responds ok for successful or error for failed requests.
- ip Customer’s IP address.
- total_amount Total order amount.
- tax_amount Taxes amount.
- shipping_amount Shipping and handling amount.
- installments Number of installments in the payment plan.
- currency Currency code.
- payment Array containing the payment methods.
payment type Array containing the payment methods.
payment bin Array containing the payment methods.
payment last4 Array containing the payment methods.
payment expiration_date Array containing the payment methods.
payment status Array containing the payment methods.
- customer Object containing the customer details.
customer id Unique identifier for each customer.
customer name Customer’s full name.
customer email Customer’s e-mail address
customer dob Customer’s date of birth in YYYY-MM-DD format.
customer tax_id Customer’s tax id.
customer phone1 Customer’s primary phone number.
customer phone2 Customer’s secondary phone number.
customer new Flag indicating if the customer is using a newly created account for this purchase.
customer vip Flag indicating if the customer is a VIP or frequent buyer.*
- billing Object containing the billing information.
billing name Cardholder’s full name.
billing address1 Cardholder’s billing address on file with the bank.
billing address2 Additional cardholder address information.
billing city Cardholder’s city.
billing state Cardholder’s state.
billing zip Cardholder’s ZIP code.
billing country Cardholder’s country code.
- shipping Object containing the shipping information.
shipping name Recipient’s full name.
shipping address1 Recipient’s shipping address.
shipping address2 Additional recipient address information.
shipping city Recipient’s city.
shipping state Recipient’s state.
shipping zip Recipient’s ZIP code.
shipping country Recipient’s country code.
- shopping_cart Array containing the items purchased.
shopping_cart sku Product or service’s SKU.
shopping_cart product_code Product or service’s UPC
shopping_cart category Category code for the item purchased.
shopping_cart name Name of the product or service.
shopping_cart description Detailed description of the item.
shopping_cart unit_cost Cost of a single unit of this item.
shopping_cart quantity Number of units purchased.
shopping_cart discount Discounted amount for this item.
- device Object containing the device information collected
device user_id Unique user id for this visitor
device fingerprint Browser fingerprint
device platform Customer’s device type
device browser Customer’s browser
device language Customer’s browser language
device timezone Customer’s time zone in GMT
device cookie Flag indicating if customer has Cookies enabled
device javascript Flag indicating if customer has JavaScript enabled
device flash Flag indicating if customer has Java enabled
device ip Customer’s IP address
- geolocation Object containing the customer’s geolocation data
geolocation city Detected city
geolocation state Detected state
geolocation country Detected country
- navigation Object containing the customer’s navigation summary
navigation session_time Time of last session (in minutes)
navigation referrer Source of the visit
navigation time_site_1d Time user spent on the website in the past day (in minutes)
navigation new_accounts_1d Accounts created by the user in the past day
navigation password_resets_1d Password resets in the past day
navigation sales_declined_1d Orders declined linked to the user in the past day
navigation sessions_1d User visits (sessions) by the user in the past day
navigation time_since_last_sale Time since the last successul order (in minutes)
navigation time_site_7d Time user spent on the website in the past week (in minutes)
navigation time_per_page_7d Avg. time per page in the past week (in minutes)
navigation new_accounts_7d Accounts created by the user in the past week
navigation password_resets_7d Password resets in the past week
navigation checkout_count_7d Shopping cart views in the past week
navigation sales_declined_7d Orders declined linked to the user in the past week
navigation sessions_7d User visits (sessions) by the user in the past week
- travel Object containing the travel and passenger information.
travel type Transportation type. Currently flight or bus are supported.
travel departure Object with the departure information.
travel return Object with the return information.
travel passengers Array of objects with the passenger details.
travel departure/return Object containing travel data (each leg)
departure
return
origin_city City of origin.
departure
return
destination_city City of destination
departure
return
origin_airport IATA code for airport of origin.
departure
return
destination_airport IATA code code for airport of destination.
departure
return
date UTC date and time of departure in YYYY-MM-DDThh:mmZ format (ISO 8601).
departure
return
number_of_connections Number of connections
departure
return
class Travel class name, like economy, business and first
departure
return
fare_basis Fase basis code.
travel passenger Object containing passenger data.
passengers name Passenger’s full name.
passengers document Document number.
passengers document_type Document type. Can be either passport or id.
passengers dob Passenger’s date of birth in YYYY-MM-DD format.
passengers nationality Passenger’s country of birth.
passengers frequent_traveler Frequent flyer flag.
passengers special_needs Passenger with special needs.

Blacklist API response

The Blacklist API response returns the confirmation of the operation made in that entry, be it an addition, update, query or removal. Below you will find the details of each response.

Addition response

{
  "status": "ok",
  "uri": "/v1/blacklist/email/tom@tom.com",
  "expires_at": "2015-11-21"
}
Parameter Description
status Request status. Either ok or error.
uri New resource’s address in the Blacklist, for future use.
expires_at Date when the entry will be automatically removed from the Blacklist.

Update response

{
  "status": "ok",
  "expires_at": "2015-11-22"
}
Parameter Description
status Request status. Either ok or error.
expires_at Date when the entry will be automatically removed from the Blacklist.

Query response

Email query response example

{
  "email_address": "tom@tom.com",
  "expires_at": "2015-11-21"
}
Parameter Description
status Request status. Either ok or error.
expires_at Date when the entry will be automatically removed from the Blacklist.
email_address Email address.

Removal response

{
  "status": "ok",
  "message": "deleted tom@tom.com from email blacklist"
}
Parameter Description
status Request status. Either ok or error.
message Removal confirmation message.

How to test

Our Sandbox environment allows you to get predictable responses from our API, so you are able to simulate all the scenarios of the integration.

In Sandbox, the recommendation changes according to the cents of the total_amount, following the table below. The score will be the cents value.

Notice: these rules apply only for our Test environment . In Production you should use our recommendation.

Value of the cents Simulated response
*.00 - *.29 APPROVED
*.30 - *.60 REVIEW
*.61 - *.99 DECLINE

Notifications (Webhooks)

Webhook notifications are an auxiliary service that allows you to automate workflows that depend on changes to the order status. Whenever an order changes status we will send a POST to a URL specified by the merchant.

From this notification the merchant can move on with their operational flow, without needing to query the status of each pending order.

This automation is meant to integrate our application with yours. Email notifications can be set up directly on the Dashboard.

Notification parameters

Our webhook contains a JSON with the order number, time of status change, new status and a validation signature.

{
  "order_id": "ORD1837213",
  "timestamp": 1608898332000,
  "status": "APPROVED",
  "signature": "6c136402b15492ca764f2687d009a4f6ebd44a2c24fabe13dc6183a6da2ceb30"
}
Parameter Description
order_id Unique identifier sent by the merchant.
timestamp Date and time of the notification in milliseconds (Unix time).
status New status for the order.
Either APPROVED, PENDING, DECLINED, CANCELED, NOT_AUTHORIZED or NOT_ANALYZED.
signature Webhook validation signature. An HMAC-SHA-256 of the fields in the notification.
Check how to calculate the signature below.

Webhook receipt

{
  "status":"ok"
}

We expect the webhook response to confirm that the event was received and processed. If a proper receipt is not detected we will try to deliver the webhook again.

You must print a JSON in the body of the HTTP 200 response that contains a single value: {"status":"ok"}.

When we see this response we understand that you have received the notification and will not try to deliver it again.

Calculating the signature

<?php 
// Defines the private key
$private_key = "T738D516F09CAB3A2C1EE";

// Original JSON from the webhook
$webhook = '{
  "order_id": "ORD1837213",
  "timestamp": 1608898332000,
  "status": "APPROVED",
  "signature": "6c136402b15492ca764f2687d009a4f6ebd44a2c24fabe13dc6183a6da2ceb30"
}';

// Transforms JSON into an array
$arr = json_decode($webhook, true);

// Stores the webhook signature into $signature
$signature = $arr["signature"];

// Removes signature from array
unset($arr["signature"]);

// Transforms array into a string concatenated by #
// ORD1837213#1608898332000#APPROVED
$to_hash = implode("#", $arr);

// Calculates HMAC with the webhook values
$my_hash = hash_hmac("sha256", $to_hash, $private_key);

// 6c136402b15492ca764f2687d009a4f6ebd44a2c24fabe13dc6183a6da2ceb30
echo $my_hash;

// true
echo ($my_hash === $signature) ? true : false;
?>

The webhook validation signature ensures the integrity of the message and prevents spoofing. It is highly recommended that you calculate and validate the signature of each webhook received.

The message contains a signature field with an HMAC-SHA-256 made by the concatenation of the other notification parameters, and using your API private key as secret.

The fields must be concatenated as such:
order_id + # + timestamp + # + status

Reference tables

Below you will find a list of supported currency codes and a list of product categories.

Common currencies

Full list of currency codes

There we have a list of the most common currencies used. You can find the full list of currency codes here.

Code Currency
USD United States Dollar ($)
BRL Brazilian Real (R$)
ARS Argentine Peso ($)
AUD Australian Dollar ($)
CAD Canadian Dollar ($)
CLP Chilean Peso ($)
EUR Euro (€)
GBP British pound (£)
JPY Japanese Yen (¥)
MXP Mexican Peso ($)

Product categories

What are categories?

Product categories are important because they tell us what type of items the customer is buying (shoes, jewelry or a GPS). Getting a TV is very different from getting a book, so categories matter for us.

These are loosely based on Google’s product taxonomy and they represent the main categories in which you can group items into.

If you think there is a category missing feel free to contact us at hi@konduto.com and let us know!

Description Code
Animals & Pet Supplies 100
Clothing & Accessories
Clothing 201
Clothing Accessories 202
Costumes & Accessories 203
Wallet Accessories 204
Handbags, Wallets & Cases 205
Jewelry 206
Shoe Accessories 207
Shoes 208
Others 299
Arts & Entertainment 300
Baby & Toddler 400
Business & Industrial
Advertising & Marketing 501
Agriculture 502
Construction 503
Film & Television 504
Finance & Insurance 505
Food Service 506
Forestry & Logging 507
Heavy Machinery 508
Hotel & Hospitality 509
Industrial Storage 510
Law Enforcement 511
Manufacturing 512
Material Handling 513
Medical 514
Mining & Quarrying 515
Piercing & Tattooing 516
Retail 517
Science & Laboratory 518
Signage 519
Work Safety Protective Gear 520
Others 599
Cameras & Optics
Cameras & Optics 601
Camera & Optic Accessories 602
Photography 603
Others 699
Electronics
3D Printers 701
Audio 702
Circuit Components 703
Communications 704
Components 705
Computers 706
Electronics Accessories 707
GPS 708
GPS Accessories 709
Networking 711
Print, Copy, Scan & Fax 712
Print, Copy, Scan & Fax Accessories 713
Video 715
Video Game Consoles 716
Video Game Consoles Accessories 717
Others 799
Food, Beverages & Tobacco 800
Furniture 900
Hardware 1000
Health & Beauty 1100
Home & Garden 1200
Luggage & Bags 1300
Adult 1400
Weapons 1500
Office Supplies 1600
Religious & Ceremonial 1700
Software
Computer Software 1801
Digital Goods & Currency 1802
Digital Services 1803
Video Game Software 1804
Others 1899
Sporting Goods 1900
Toys & Games 2000
Vehicles & Parts 2100
Books 2300
DVDs & Videos 2400
Magazines & Newspapers 2500
Music
CDs & Vynil 2601
Musical Instruments 2602
Digital Music 2603
Others 2699
Other categories not specified 9999