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<EMAIL_ADDRESS>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<EMAIL_ADDRESS>we’d love to hear from you!
API Authentication
# How to build
Authorization: Basic BASE64(T00000111112222233333:)
# Result
Authorization: Basic VDAwMDAwMTExMTEyMjIyMjMzMzMzOg==
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":"<IP_ADDRESS>",
"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_ADDRESS>"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. |
| (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",
"expiration_date": "2025-12-25T15:41:53Z",
"departure":{
"origin_airport":"GRU",
"destination_airport":"SFO",
"date":"2018-12-25T18:00Z",
"company": "LATAM",
"number_of_connections":1,
"class":"economy",
"fare_basis":"Y"
},
"return":{
"origin_airport":"SFO",
"destination_airport":"GRU",
"date":"2018-12-30T18:00Z",
"company": "Avianca",
"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. |
| expiration_date | (optional) UTC date and time of PNR reservation expiration YYYY-MM-DDThh:mmZ format (ISO 8601) Exactly 17 chars, string. |
| 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. |
| company | (optional) Name of the airline or bus company. |
| 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>"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<EMAIL_ADDRESS>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<EMAIL_ADDRESS>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":"<IP_ADDRESS>",
"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":"<IP_ADDRESS>",
"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_ADDRESS>"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 | 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"<EMAIL_ADDRESS>"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"<EMAIL_ADDRESS>"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<EMAIL_ADDRESS>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 | APPROVE |
| *.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":<PHONE_NUMBER>000,
"status": "APPROVED",
"signature": "e1b27d01bc75780c791f057ce99615fcca07003cbc8029e1d8330bac7a273a57"
}
| 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 = "T00000111112222233333";
// Original JSON from the webhook
$webhook = '{
"order_id": "ORD1837213",
"timestamp":<PHONE_NUMBER>000,
"status": "APPROVED",
"signature": "e1b27d01bc75780c791f057ce99615fcca07003cbc8029e1d8330bac7a273a57"
}';
// 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);
// e1b27d01bc75780c791f057ce99615fcca07003cbc8029e1d8330bac7a273a57
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<EMAIL_ADDRESS>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 |


Dispatch API Documentation
The Dispatch API allows users to interact with a mathematical program that approximates Australia's National Electricity Market Dispatch Engine (NEMDE). The model is formulated as a single period economic dispatch problem that seeks to dispatch generators and loads such that demand is met at the lowest cost while respecting unit, network, and system constraints.
The API can be used to investigate relationships between system parameters and dispatch outcomes, with possible applications including ex-post scenario and sensitivity analyses, or the tool's integration within forecasting frameworks.
Features and known limitations
The model used to approximate the NEMDE includes the following components:
- generator and load bids (FCAS and energy market);
- market network service provider (MNSP) bids;
- interconnector loss models with SOS2 constraints;
- Basslink loss model;
- generic constraints;
- FCAS constraints;
- two pass solution algorithm and inflexibility profiles for fast-start units;
- tie-breaking model for price-tied energy offers.
The model validation section describes the data-driven approach used to assess the Dispatch API's ability to emulate NEMDE outputs. Excellent correspondence is observed between solutions reported by the Dispatch API and those reported by the NEMDE. However, users should note the Dispatch API is subject to some important limitations:
- FCAS prices are not reported;
- generic constraint right-hand side (RHS) values are obtained from historical NEMDE solutions rather than computed from SCADA values;
- intervention pricing runs are not supported;
- prices are not adjusted to the market price floor or cap if these thresholds are exceeded;
- constraint relaxation algorithms are not implemented.
The above list represents known material limitations associated with the model. Work is underway to address each of these points, with updates likely to be incorporated within future versions of the Dispatch API.
How it works
The Dispatch API allows users to interact with an online queue that coordinates the process of formulating and solving a model which approximates the NEMDE. Users first prepare parameters describing the National Electricity Market's state in the form of a case file. Parameters include:
- offers and bids made by generators and loads;
- initial conditions for units, interconnectors, and regions;
- interconnector loss model factors;
- generic constraint terms.
See the parameter reference page for more details regarding the data that can be submitted via the API.
Once a case file has been prepared, it can be submitted to an online queue via the Dispatch API. A pool of workers constantly monitor the queue for new case files. If a worker is idle when a case file enters the queue it will use the parameters submitted by the user to formulate and solve a model approximating the NEMDE. If all workers are occupied when the case file is submitted, the case file will 'wait' in the queue until a worker is available. Upon solving the model the worker posts its results back to queue, which can then be retrieved by the user. Results remain within the queue for a limited time (2 hours) at which point they are deleted.
The following diagram illustrates the workflow used when solving a model using the Dispatch API.
Multiple workers can monitor the queue simultaneously, allowing models to be solved in parallel. This capability allows large-scale scenario anlayses to be underaken.
Getting started
Tutorials
The tutorials section gives an overview of the Dispatch API's features and provides examples on how to setup scenario analyses and associated workflows. The Running a Model tutorial is the recommended starting point for new users.
Case file reference
The parameter reference page shows the parameters that can be meaningfully updated when modifying or constructing case files.
Model validation
See how the solution returned by the Dispatch API compares to results obtained from NEMDE in the model validation section.
Case studies
See potential applications of the Dispatch API via case studies.