Quick Links

How to Integrate Kount 360 Payment Risk (Approve/Decline)

Payment Risk is an AI-driven digital fraud prevention solution that delivers accurate identity trust decisions in milliseconds, built on the Kount 360 platform. Integrate Payment Risk to gain access to the REST API endpoint, view your account in the portal, manage users, resolve transactions, and more.

Integration happens in two major stages: integration into the Sandbox environment and integration into the Production environment. Integration with Sandbox allows you to perform testing without affecting the production data. The steps are repeated for each stage, although the coding portions should only need to update the host-names and authentication credentials — the code can remain the same.

Note

You cannot send production transaction data to our sandbox environment. Only integrate into our sandbox environment if you are integrating a pre-production environment without production data.

Create an API Key

Sign in to Kount 360 to create your administrator password, retrieve your client ID, and create an API key. Set up your credentials before you authenticate or access the REST API.

  1. Open the Kount 360 Account Activation email sent to the administrator email address you provided Kount.

  2. Click Activate Account.

  3. From the welcome page, create your password, select a security image, and then click Create my Account to be redirected to the Kount 360 login page.

    If you are not redirected to the Kount 360 login page automatically, navigate to the appropriate environment:

    • Sandbox: https://app-sandbox.kount.com/login

    • Production: https://app.kount.com/login

  4. Sign in using your credentials.

  5. On the navigation menu, click Developer, and then Clients.

  6. Click New Client.

  7. Enter a name for the new client, and then click OK.

  8. In the New Client prompt, copy the API key and save it in a secure location.

    Note

    Use the copy button to copy the API key. If you close the window without copying the API key, you must create a new API key using the options menu. You are only allowed two active API keys per client

  9. Click OK.

  10. On the Clients screen, locate the client you created to view the Client ID.

    If desired, save the Client ID in a secure location. If you did not save the API key previously, click the arrow to preview and copy the API key.

Authenticating with Kount 360

After you have provisioned your client ID and credentials in the self-service portal, retrieve a temporary bearer token.

Provide the client credentials in an HTTP POST to a specific login.kount.com URL (referred to as the “ISSUER” URL, which you will receive from Kount). With a successful exchange, the returned JSON provides a special bearer token, as well as an expiration date (expires_in attribute, provided in seconds until expiration).

The API varies depending if you’re calling the Sandbox or Production system. The values are:

Environment

Auth Server URL

API URL

Sandbox

https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token

https://api-sandbox.kount.com

Production

https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token

https://api.kount.com

The following provides example posts in popular languages:

Python

"""sandbox"""
import requestsAUTH_SERVER_URL = "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token"
API_URL = "https://api-sandbox.kount.com"
API_KEY = "ENTER YOUR API KEY HERE"

r = requests.post(AUTH_SERVER_URL, params={"grant_type":
"client_credentials", "scope": "k1_integration_api"},
                  headers={"Authorization": "Basic" + API_KEY,
                           "Content-Type":
 "application/x-www-form-urlencoded"})

t = r.json()["access_token"]

r = requests.post(API_URL + "/commerce/v1/orders?riskInquiry=true",
                  headers={'Authorization': "Bearer " + t},
                  json={"merchantOrderId": "ABC123"})

print("Response:", r.json())

Bash

    #!/usr/bin/env bash
    
    API='https://api-sandbox.kount.com'
    ISSUER='https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
    CLIENT_ID='<Your client ID here!>'
    CREDS='<Your client credentials here!>'
    
    # Get our token (it is valid for 20 minutes)
    RESPONSE=$(curl -s -X POST "${ISSUER}/v1/token?grant_type=client_credentials&scope=k1_integration_api" -H "Authorization: Basic ${CREDS}" -H "Content-Type: application/x-www-form-urlencoded")
    TOKEN=$(echo $RESPONSE | jq -r .access_token)
    
    # Make our evaluation request
    RESPONSE=$(curl -s -X POST ${API}/commerce/v1/orders -H "Authorization: Bearer ${TOKEN}" \
    -d '{"clientId": "${CLIENT_ID}", "payment":{"paymentType": "CARD", "paymentToken": "4111111111111111", "bin": "414709"}}')
    echo $RESPONSE | jq
    

TypeScript

    const axios = require('axios')
    
    const API = 'https://api-sandbox.kount.com'
    const ISSUER = 'https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
    const CLIENT_ID = '<Your client ID here!>'
    const CREDS = '<Your client credentials here!>'
    
    async function getBearerToken() {
    
    const auth = await axios({
    url: `${ISSUER}/v1/token`,
    method: 'post',
    headers: {
    authorization: `Basic ${CREDS}`
    },
params: {
    grant_type: 'client_credentials',
    scope: 'k1_integration_api'
    }
    })
    
    return auth.data.access_token
    }
    
    async function evaluateIdentity(token: string) {
    
    const resp = await axios({
    url: `${API}/commerce/v1/orders`,
    method: 'post',
    headers: {
    authorization: `Bearer ${token}`,
    },
    data: {
    clientId: CLIENT_ID,
    payment: {
    paymentType: 'CARD',
    paymentToken: '4111111111111111',
    bin: '414709',
    },
    }
    })
    
    return resp.data
    }
    const main = async () => {
    const token = await getBearerToken();
    const resp = await evaluateIdentity(token);
    console.log(JSON.stringify(resp, null, 4))
    }
    
    main()
    

Go

    package main
    import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    )
    
    type config struct {
    API string
    Issuer string
    ClientId string
    Creds string
    }
    
    func getToken(c *http.Client, issuer, creds string) string {
    
    req, _ := http.NewRequest(http.MethodPost, issuer+"/v1/token", nil)
    
    req.Header.Add("Authorization", "Basic "+creds)
    
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
    
    q := req.URL.Query()
    q.Add("grant_type", "client_credentials")
    q.Add("scope", "k1_integration_api")
    req.URL.RawQuery = q.Encode()
    
    resp, _ := c.Do(req)
    defer resp.Body.Close()
    
    t := struct {
    TokenType string `json:"token_type"`
    ExpiresIn int `json:"expires_in"`
    AccessToken string `json:"access_token"`
    }{}
    
    json.NewDecoder(resp.Body).Decode(&t)
    return t.AccessToken
    }
    
    func evaluate(c *http.Client, api string, payload IdentityEvalReq, token string) string {
    
    j, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest(http.MethodPost, api+"/commerce/v1/orders", bytes.NewBuffer(j))
    
    req.Header.Add("Authorization", "Bearer "+token)
    
    resp, _ := c.Do(req)
    defer resp.Body.Close()
    
    b, _ := io.ReadAll(resp.Body)
    s := string(b)
    return s
    }
    
    type IdentityEvalReq struct {
    ClientId string `json:"clientId"`
    Payment IdentityEvalPaymentReq `json:"payment"`
    }
    
    type IdentityEvalPaymentReq struct {
    PaymentType string `json:"paymentType"`
    PaymentToken string `json:"paymentToken"`
    BIN string `json:"bin"`
    }
    
    func main() {
    config := config{
    API: "https://api-sandbox.kount.com",
    Issuer: "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357",
    ClientId: "<Your client ID here!>",
    Creds: "<Your client credentials here!>",
    }
    client := &http.Client{}
    token := getToken(client, config.Issuer, config.Creds)
    
    payload := IdentityEvalReq{
    ClientId: config.ClientId,
    Payment: IdentityEvalPaymentReq{
    PaymentType: "CARD",
    PaymentToken: "4111111111111111",
    BIN: "414709",
    },
    }
    
    resp := evaluate(client, config.API, payload, token)
    fmt.Printf( "%s", resp)
    }
    

Refresh the token before it expires. If it is not refreshed, the call to the API fails with 401 Unauthorized. Most tokens issued by login.kount.com expire after 20 minutes. Client credentials never expire unless they are explicitly revoked.

Device Data Collector Implementation

The Device Data Collector (DDC) gathers information from a customer’s device by running client-side scripts and sending the data to Kount. This passive analysis conceals the Kount interaction with the customer and does not affect the customer’s purchasing experience.

To ease DDC set up, use our guided DDC content generator or follow the steps below.

The DDC requires a two step process for mobile integration: Integration (Step 1) and Invocation (Step 2).

Payment Evaluation

The Orders API endpoint (/commerce/{VERSION}/orders) joins device data provided by the DDC with order data. Once the device data and order data are combined, the Orders endpoint can evaluate and score each transaction. After the evaluation, the endpoint returns a response so you can approve or decline the order.

Payment Risk Server-Side Integration Sequence

Typical integrations of the Payment Risk solution into your server-side payment workflow follow seven key steps:

PR_00.png
  1. Purchase initiated – An end user initiates the purchase, typically after they’ve entered their payment information and clicked on the button to perform the purchase.

  2. Process order – As the Kount customer/merchant server processes the order, either pre-credit-authorization or post-credit-authorization, they must determine if the payment is high risk.

  3. Call the Orders Risk Inquiry Endpoint – The customer/merchant calls the Kount 360 Orders endpoint with the risk inquiry parameter and passes the transaction details to determine the risk of the transaction.

  4. Evaluate Order – Kount 360 Payment Risk evaluates the data from the device collection and the details of the transaction against Kount’s Identity Trust Global Network, the machine learning models, and the customer/merchant defined policies to determine the risk.

  5. Orders Risk Inquiry Response – The Orders endpoint returns the final evaluation (Approve or Decline) for the transaction.

  6. Determine Order Result – The customer/merchant leverages the Kount 360 Order Risk Inquiry guidance and determines how it should influence the final result for the payment in their payment workflow.

  7. Payment Result Screen – Once the customer/merchant determines how to proceed with processing the payment, the final result is displayed to the end user.

Pre-authorization versus Post-authorization

There are numerous differences in engaging the Kount 360 Orders Risk Inquiry endpoint before or after payment authorization.

Pre-authorization

Querying the Kount 360 Orders Risk Inquiry endpoint before authorizing from the payment gateway:

  • Allows the merchant to avoid processing fees on transactions that result in declining a transaction.

  • Sends all credit card information to Kount.

  • Requires a call to the Transactions endpoint to update the status of the payment authorization or to provide other details provided by the payment gateway.

  • Requires a customer/merchant to pay for inquiries, including transactions that result in declining a transaction (orders that are declined by a business rule are not sent to the Payment Processor, alleviating extra payment processor fees).

Pre-authorization Workflow:

PR_01.png

Post-authorization

Querying the Kount 360 Orders Risk Inquiry endpoint after attempting an authorization from the payment gateway:

  • Allows all payment gateway information (Authorization, AVS, CVV) to be passed to Kount 360 Payment Risk, allowing rules to be created regarding AVS and CVV data.

  • Prevents linking on Payment Token across the Kount network. Some payment gateways do not pass credit card data once they receive it.

  • Does not require a call to the Transactions API to perform an update.

  • Requires a customer/merchant to pay for inquiries to the payment processor, including transactions that result in declining a transaction. Only transactions that result in an AUTH-A from the payment gateway results in calling the Kount 360 Orders Risk Inquiry API endpoint.

Post-authorization Workflow:

PR_02.png

Invoking the Kount 360 Orders Risk Inquiry Endpoint

Specifications

The Orders endpoint is a RESTful HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to Authentication to learn how to acquire the bearer token.

The session identifier created during the DDC process must be passed in as the session identifier in the Orders endpoint. This identifier must be unique for at least 30 days. If a single Session ID is used on multiple transactions, those transactions link together and erroneously affect the risk score.

Endpoints

  • Sandbox: https://api-sandbox.kount.com/commerce/v1/orders

  • Production: https://api.kount.com/commerce/v1/orders

Method:POST

Header Authorization:Bearer <token>

Header Content-Type:application/json

Body: Refer to the Body Property table below.

Request Parameters and Data Submission

When submitting data to the Kount 360 Orders endpoint, we recommend populating as many fields as possible to enable the most accurate risk scoring.

There are two main ways to use the endpoint:

  • To perform a risk inquiry to receive guidance on if an order should be approved or declined - this provides the data that powers the machine learning models.

    This is the primary value of the Payment Risk product, in which you are charged.

  • To send the order information without a risk inquiry. This approach provides data that powers the machine learning models.

    This call does not cost anything, and helps make sure you’re getting the most accurate risk score when you perform a risk inquiry call.

To perform the risk inquiry call, include the riskInquiry parameter and set its value to true. For example:

/commerce/v1/orders?riskInquiry=true

To perform the Orders endpoint call without performing a risk inquiry, set the riskInquiry to false, or omit the parameter entirely. For example:

/commerce/v1/orders

Orders Endpoint Request Properties

JSON Path

Field Name

Description

Type

Examples

Notes

merchantOrderId

Merchant's Order ID

The merchant-provided unique identifier for this order. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76".

String

"d121ea2210434ffc8a90daff9cc97e76"

 

channel

Customer's Transaction Channel

Unique identifier of the website or app from where the order originated. For example, "ACME_IOS_APP"

String

"ACME_IOS_APP"

(FKA: ‘website_ID’)

deviceSessionId

Device Session ID

Unique identifier for the customer’s end-user’s session on the site/app. Must be the same session ID used in the device data collection from the client-side Kount SDK. Uniqueness for this property is not enforced, but customers should provide unique values. Example: "d121ea2210434ffc8a90daff9cc97e76"

String

"d121ea2210434ffc8a90daff9cc97e76"

 

creationDateTime

Order Creation Date/Time

The date and time that the order was placed.

String

"2019-08-24T14:15:22Z"

 

userIp

User's IP Address

The customer/merchant’s end-user’s IPv4 address (in dotted decimal notation) as identified by the customer/merchant. For example, “192.168.1.27”

String

“192.168.1.27”

 

account

Account Properties Object

An object containing the properties of the account of the user that placed the order.

Object

   

account.id

User's Account ID

The merchant-provided unique account ID of the user that placed the order. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76"

String

"d121ea2210434ffc8a90daff9cc97e76"

 

account.type

User's Account Type

Merchant-provided categorization of the account.

String

"PRO_ACCOUNT"

 

account.creationDateTime

User's Account Creation Date/Time

The date and time that the user's account was created.

String

"2019-08-24T14:15:22Z"

 

account.username

User's Username

The username of the user's account.

String

"johndoe1983"

 

account.accountIsActive

User's Account Active Status

A boolean indicating whether the user's account is still active.

Boolean

TRUE

 

items

Items in the Order

Shopping cart data array of objects representing each item (separate SKU with quantity) in the order.

Array

   

items.id

Item ID

The merchant-provided unique item ID of the item in the order. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76"

String

"d121ea2210434ffc8a90daff9cc97e76"

 

items.price

Item Price

The price of the single item in the lowest currency factor. For example, The lowest currency in USD is pennies, so $1.00 would have the value of “100”. Must be a natural number including 0. For example, 100.

Integer

100

 

items.description

Item Description

The description of the item being purchased. For example, "Samsung 46' LCD HDTV".

String

"Samsung 46'' LCD HDTV"

 

items.name

Item Name

The name of the item being purchased, typically the SKU. For example, "LN46B610".

String

"LN46B610"

 

items.quantity

Item Quantity

The quantity of the item being purchased. For example, 1.

Integer

1

 

items.category

Item Category

A high level or generalized description of the item added to the shopping cart. For example, "TV".

String

"TV"

 

items.subCategory

Item Sub-Category

A lower-level or more specific description of the item added to the shopping cart. For example, "OLED TV".

String

"OLED TV"

 

items.isDigital

Item Digital Status

A boolean indicating whether the item being ordered is a physical item or a service (false), or whether it is a digital good or service (true).

Boolean

FALSE

 

items.sku

Item SKU

A string containing the item's SKU, when available. For example: "TSH-000-S"

String

"TSH-000-S"

 

items.upc

Item UPC

A string containing the item's UPC code, when available. For example: "03600029145"

String

"03600029145"

 

items.brand

Item's Brand

The item's brand name.

String

"LG"

 

items.url

Item's Page URL

The URL to the page that describes the item in the merchant's store. For example: "https://www.example.com/store/tsh-000-s"

String

"https://www.example.com/store/tsh-000-s"

 

items.image

Item's Image URL

The URL to the item's thumbnail image. For example: "https://www.example.com/store/tsh-000-s/thumbnail.png"

String

"https://www.example.com/store/tsh-000-s/thumbnail.png"

 

items.physicalAttributes

Item's Physical Properties Object

An object containing data on the physical attributes of a physical good.

Object

 

Shouldn't be provided for digital goods.

items.physicalAttributes.color

Item's Color

The color of the item, when there are different color options. For example: "Midnight Purple"

String

"Midnight Purple"

 

items.physicalAttributes.size

Item's Size

The size of the item, when there are different size options. For example: "XL"

String

"XL"

 

items.physicalAttributes.weight

Item's Weight

The item's weight and units. For example: "5 lbs."

String

"5 lbs."

 

items.physicalAttributes.height

Item's Height

The item's height and units. For example: "12 in."

String

"12 in."

 

items.physicalAttributes.width

Item's Width

The item's width and units. For example: "6 in."

String

"6 in."

 

items.physicalAttributes.depth

Item's Depth

The item's depth and units. For example: "36 cm"

String

"36 cm"

 

items.descriptors

Descriptors of the Item

An array of keywords associated with the item. For example: ["halloween", "mask"]

Array

["halloween", "mask"]

 

fulfillment

Order Fulfillment Properties Array

An array of data properties about the fulfillment of the order.

Array

 

Fulfillment is how the consumer acquires the order, which is an array of items (good or service)

fulfillment.type

Fulfillment Type

A string from an enumeration of types of fulfillment. For example: "DIGITAL"

String

“SHIPPED”

”DIGITAL”

”STORE_PICK_UP”

”LOCAL_DELIVERY”

”STORE_DRIVE_UP”

”IN_PERSON”

Fulfillment Classes: All

fulfillment.itemsIds

Fulfilled Item IDs Array

An array of string values made up of the merchant-provided item IDs that are being fulfilled in this fulfillment.

Array

["d121ea2210434ffc8a90daff9cc97e76", “23e69466888d11eda1eb0242ac120002”]

Fulfillment Classes: All

fulfillment.status

Fulfillment Status

A string of an enumeration of statuses of the current status of the fulfillment.

String

“PENDING”

”UNFULFILLED”

”ON_HOLD”

”FULFILLED”

”SCHEDULED”

”PARTIALLY_FULFILLED”

”DELAYED”

”CANCELED”

PENDING – Awaiting fulfillment info

UNFULFILLED – In progress, but not shipped

ON_HOLD – Waiting on upsell opportunities

FULFILLED – Shipped (formerly SUCCESSFUL)

SCHEDULED – Waiting for release (e.g.: prepaid subscriptions)

PARTIALLY_FULFILLED – Portion is shipped

DELAYED – Delayed

CANCELED – Canceled

fulfillment.accessUrl

Digital Access URL

A string containing the URL the customer needs to visit to retrieve the digital good. For example: "https://example.com/digitalgood/1213901281290"

String

"https://example.com/digitalgood/1213901281290"

Fulfillment Classes: DIGITAL

fulfillment.shipping

Shipping Properties Object

An object containing the shipping details properties.

Object

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

Should be included even for digital goods. Note that in the description.

fulfillment.shipping.amount

Shipping Amount

The total amount of the shipping cost in its lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

893

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.shipping.provider

Shipping Provider

The service used to deliver the order to the recipient. If the merchant fulfills the order itself, should have the value "FBM" (fulfilled by merchant).

String

"FEDEX"

"FBM"

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

FBM stands for "Fulfilled by Merchant" and would be applicable for digital goods.

fulfillment.shipping.trackingNumbers

Shipping Tracking Numbers

An array containing tracking numbers from the shipping provider for shipped goods. For example: ["TBA056059680404"]

Array

["TBA056059680404"]

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.shipping.method

Shipping Method & Class

A string from an enumeration of types of shipping methods used to deliver the goods to the recipient. Types: “STANDARD”, “EXPRESS”, “SAME_DAY”, “NEXT_DAY”, “SECOND_DAY”

String

“STANDARD”

"EXPRESS"

“SAME_DAY”

”NEXT_DAY”

”SECOND_DAY”

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient

Recipient Properties Object

The object containing the properties of the recipient of the order.

Object

 

Fulfillment Classes: All

fulfillment.recipient.sameAsBilling

Billing Duplicate Address

A boolean indicating whether the billing address is the same as the shipping address (true) or not (false). If true, person does not need to be provided and Transaction.billedPerson will be used. If person is provided, it will be used instead of Transaction.billedPerson, regardless of the value of this property.

Boolean

FALSE

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient.person

Recipient

An object containing the properties of the person receiving the goods.

Object

 

Fulfillment Classes: All

fulfillment.recipient.person.name

Recipient Name

An object containing the properties of the name of the person.

Object

 

Fulfillment Classes: All

fulfillment.recipient.person.name.first

Recipient First Name

The first name of the person the order is shipped to. For example, “John”.

String

"William"

Fulfillment Classes: All

fulfillment.recipient.person.name.last

Recipient Last Name

The last name of the person the order is shipped to. For example, “Doe”.

String

"Doe"

Fulfillment Classes: All

fulfillment.recipient.person.name.preferred

Recipient Preferred Name

The name the person the order is shipped to would like to be addressed by. For example: "Bill".

String

"Bill"

Fulfillment Classes: All

fulfillment.recipient.person.emailAddress

Recipient Email Address

The email address of the person the order is shipped to. For example, "john.doe@example.com".

String

"john.doe@example.com"

Fulfillment Classes: All

fulfillment.recipient.person.phoneNumber

Recipient Phone Number

The phone number of the person the order is being shipped to in the E.123 standard format. For example, "+12081234567".

String

"+12081234567"

Fulfillment Classes: All

fulfillment.recipient.person.shippingAddress

Shipping Address Properties Object

An object containing the properties of a physical or mailing address.

Object

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

Can be excluded for digital goods. Note that in description.

fulfillment.recipient.person.shippingAddress.addressType

Shipping Address Type

Indicates the kind of address. For this property, the value should be "SHIPPING".

String

"SHIPPING"

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

Although this is already clear from the structure, this is one of the properties that's part of the "address" schema.

fulfillment.recipient.person.shippingAddress.line1

Shipping Address Line 1

The first line of the shipping address. For example, "12345 MyStreet Ave".

String

"12345 MyStreet Ave"

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient.person.shippingAddress.line2

Shipping Address Line 2

The second line of the shipping address. For example, "Suite 256”.

String

"Suite 256”

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient.person.shippingAddress.city

Shipping Address City

The city of the shipping address. For example, "Poplar Bluff".

String

"Poplar Bluff"

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient.person.shippingAddress.region

Shipping Address Region

The state or province of the shipping address. For example, “CO”.

String

“CO”

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient.person.shippingAddress.countryCode

Shipping Address Country Code

The country code of the shipping address in the ISO-3166 format. For example, "US".

String

"US"

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.recipient.person.shippingAddress.postalCode

Shipping Address Postal Code

The postal code of the shipping address. For example, "63901-0000".

String

"63901-0000"

Fulfillment Classes: SHIPPED, LOCAL_DELIVERY

fulfillment.store

Fulfillment Store

An object containing the properties of the store where the order is being fulfilled.

Object

 

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.id

Store ID

A string containing the merchant-provided unique identifier for the store. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76"

String

"d121ea2210434ffc8a90daff9cc97e76"

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.name

Store Name

A string containing the human-readable name of the store. Example: “10th & Main Acme Inc.”

String

“10th & Main Acme Inc.”

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address

Store Address Location

An object containing the properties of a physical or mailing address.

Object

 

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.addressType

Store Address Type

Indicates the kind of address. For this property, the value should be “SHIPPING”, “BILLING” or “LOCATION”.

String

“LOCATION”

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.line1

Store Address Line 1

The first line of the address. For example, "12345 MyStreet Ave".

String

"12345 MyStreet Ave"

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.line2

Store Address Line 2

The second line of the address. For example, "Suite 256”.

String

"Suite 256”

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.city

Store Address City

The city of the address. For example, "Poplar Bluff".

String

"Poplar Bluff"

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.region

Store Address Region

The state or province of the address. For example, “CO”.

String

“CO”

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.countryCode

Store Address Country Code

The country code of the address in the ISO-3166 format. For example, "US".

String

"US"

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

fulfillment.store.address.postalCode

Store Address Postal Code

The postal code of the address. For example, "63901-0000".

String

"63901-0000"

Fulfillment Classes: STORE_PICK_UP, STORE_DRIVE_UP, IN_PERSON

transactions

Payment Transactions Array

An array containing the properties of the payment transactions made for the order.

Array

   

transactions.processor

Payment Transaction Processor

The name of the payment processor that processed the transaction. E.g.: "PayPal"

String

"ADYEN"

 

transactions.processorMerchantId

Payment Processor's Merchant ID

A unique identification number attached to a business that tells the payment processing systems involved in a transaction where to send which funds. Uniqueness for this property is not enforced. The format is processor specific, but is typically a 16-digit number. For example: "5206080947171696"

String

"5206080947171696"

 

transactions.payment

Payment Properties Object

An object containing the properties of the specific type of payment that was used for this transaction.

Object

   

transactions.payment.type

Payment Type

Payment Type submitted by merchant:

APAY - Apple Pay

CREDIT_CARD - Credit Card

DEBIT_CARD - Debit Card

PYPL - PayPal

CHEK - Check

NONE - None

TOKEN - Token provided from payment processor

GDMP - Green Dot Money Pack

GOOG - Google Checkout

BLML - Bill Me Later

GIFT - Gift Card

BPAY - BPAY

NETELLER - Neteller

GIROPAY - GiroPay

ELV - ELV

MERCADE_PAGO - Mercade Pago

SEPA - Single Euro Payments Area

INTERAC - Interac

CARTE_BLEUE - Carte Bleue

POLI - POLi

SKRILL - Skrill/Moneybookers

SOFORT - Sofort

AMZN - Amazon Pay

SAMPAY - Samsung Pay

ALIPAY - AliPay

WCPAY - WeChat Pay

CRYPTO - Crypto Payments

KLARNA - Klarna

AFTRPAY - Afterpay

AFFIRM - Affirm

SPLIT - Splitit

FBPAY - Facebook Pay

String

"CREDIT_CARD"

 

transactions.payment.paymentToken

Payment Token

The payment token submitted by the merchant for the order (credit card, payer ID, routing/transit, MICR, and account number).

The payment token is hashed with salted SHA256.

If paymentType is set to “NONE” then the paymentToken value should be left empty.

POST-AUTH CALLS ONLY – If the credit card information is not available and a tokenized value is returned from the payment processor, set paymentType=”TOKEN” and send the token returned from the payment processor in the paymentToken field.

String

   

transactions.payment.bin

Payment BIN

The Bank Identification Number. Made up of the first six or eight digits of a credit or debit card.

String

"483312"

 

transactions.payment.last4

Last 4 Digits of PAN

The last 4 digits of the payment token.

String

"1111"

 

transactions.subtotal

Order Subtotal

The total amount of the order without shipping and tax included in its lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

10000

 

transactions.orderTotal

Order Total Amount

The total amount of currency in the transaction in its lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

100

 

transactions.currency

Order Total Currency

The three-letter ISO-4217 code of the currency used in the transaction. If a code is not provided, it defaults to “USD”

String

"USD"

 

transactions.tax

Tax Properties Object

An object containing the tax details of the payment.

Object

   

transactions.tax.isTaxable

Order Taxable

A boolean indicating whether the order is taxable (true) or not (false).

Boolean

TRUE

 

transactions.tax.taxableCountryCode

Taxable Country Code

The country code of the taxable country in the ISO-3166 format. For example, "US".

String

"US"

 

transactions.tax.taxAmount

Tax Amount

The amount that was charged in taxes for this order in the currency's lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

327

 

transactions.tax.outOfStateTaxAmount

Out of State Tax Amount

The amount that was charged in out-of-state taxes for this order in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

 

Make this the subset of the taxAmount. I.e.: the total of taxAmount includes the outOfStateTax.

transactions.billedPerson

Person Properties Object

An object containing the properties of the person who placed the order.

Object

   

transactions.billedPerson.name

Name Properties Object

An object containing the properties of the person's name.

Object

   

transactions.billedPerson.name.first

Billed Person's First Name

The first name (forename) of the person/company billed for the order. For example, “William”.

String

"William"

 

transactions.billedPerson.name.last

Billed Person's Last Name

The last name (surname) of the person/company billed for the order. For example, “Doe”.

String

"Doe"

 

transactions.billedPerson.name.preferred

Billed Person's Preferred Name

The name the person/company billed for the order would like to be addressed by. For example: "Bill".

String

"Bill"

 

transactions.billedPerson.emailAddress

Billed Person's Email Address

The email address of the person/company billed for the order. For example, “john.doe@example.com”

String

"john.doe@example.com"

 

transactions.billedPerson.phoneNumber

Billed Person's Phone Number

The phone number of the person billed for the order in the E.123 standard format. For example, "+15551234567".

String

"+15551234567"

 

transactions.billedPerson.address

Billed Person's Address Properties Object

An object containing the properties of a physical or mailing address.

Object

   

transactions.billedPerson.address.addressType

Address Type

Indicates the kind of address. For this property, the value should be "BILLING".

String

"BILLING"

 

transactions.billedPerson.address.line1

Billing Address – Line 1

The first line of the billing address. For example, “12345 Mystreet Ave”.

String

"5813-5849 Quail Meadows Dr"

 

transactions.billedPerson.address.line2

Billing Address – Line 2

The optional second line of the billing address. For example, “Suite 123”.

String

“Suite 123”

 

transactions.billedPerson.address.city

Billing Address City

The city of the billing address. For example, "Poplar Bluff"

String

"Poplar Bluff"

 

transactions.billedPerson.address.region

Billing Address Region

The state or province of the billing address. For example, “CO”.

String

"CO"

 

transactions.billedPerson.address.postalCode

Billing Address Postal Code

The postal code of the billing address. For example, "63901-0000".

String

"63901-0000"

 

transactions.billedPerson.address.countryCode

Billing Address Country Code

The country code of the billing address in the ISO-3166 format. For example, "US".

String

"US"

 

transactions.transactionStatus

Payment Transaction Status

A string containing one of an enumeration of statuses the payment may be in as it is processed. For example: "PENDING"

String

"PENDING"

"AUTHORIZED"

"REFUSED"

"CAPTURED"

"ERROR"

"EXPIRED"

"CANCELLED"

"SENT_FOR_REFUND"

"REFUNDED"

"REFUND_FAILED"

"SETTLED"

"INFORMATION_REQUESTED"

"INFORMATION_SUPPLIED"

"CHARGED_BACK"

"CHARGEBACK_REVERSED"

"DISPUTE_EXPIRED"

"DISPUTE_RESERVE_RELEASED"

"DISPUTED_FUNDS_HELD"

"DISPUTED_FUNDS_RELEASED"

"CHARGEBACK_REVERSED"

 

transactions.authorizationStatus

Authorization Status Properties Object

An object containing the details of the authorization status. Everything in this object is expected only after payment authorization has occurred.

Object

 

The presence of the authorizationStatus property indicates that this was called as a post-authentication transaction.

transactions.authorizationStatus.authResult

Authorization Status

The authorization status returned to the merchant from the payment processor. Orders with a value of "Approved" will aggregate towards the order velocity of the persona while orders with a value of "Declined" will decrement the order velocity of the persona. Orders with a value of "Error" or "Unknown" will not change the velocity.

String

"Approved"

"Declined"

"Unknown"

"Error"

 

transactions.authorizationStatus.dateTime

Authorization Date/Time

The date/time when the transaction was performed. Supported date/time format is ISO 8601. For example, “2021-03-02T19:01:37Z”.

String

"2022-10-31T22:01:43Z"

 

transactions.authorizationStatus.verificationResponse

Verification Response Properties Object

An object containing the details of the verification responses.

Object

   

transactions.authorizationStatus.verificationResponse.addressStatus

Address Verification System Status

The street verification response returned to the customer/merchant from the payment processor as validated by the Address Verification System (AVST). One value of the following enumerated values: "Unknown", "Match" or "NoMatch".

String

"Match"

 

transactions.authorizationStatus.verificationResponse.postalCodeStatus

Zip Code AVS Status

The Zip Code verification response returned to the customer/merchant from the payment processor as validated by the Address Verification System (AVSZ). One value of the following enumerated values: "Unknown", "Match" or "NoMatch".

String

"NoMatch"

 

transactions.authorizationStatus.verificationResponse.cvvStatus

Card Verification Value Status

The Card Verification Value (CVV, CVS) response returned to the customer/merchant from the payment processor. One value of the following enumerated values: "Unknown", "Match" or "NoMatch".

String

"Unknown"

 

transactions.authorizationStatus.paymentCredentials

Payment Credentials Properties Object

An object containing the properties of the payment credentials, such as tokens used by digital payment methods.

Object

   

transactions.authorizationStatus.paymentCredentials.type

Payment Credentials Type

The type of payment used, such as specifying a digital payment method. For example, “SEPA”.

String

“SEPA”

 

transactions.authorizationStatus.paymentCredentials.token

Payment Credentials Token

The token used in the transaction as the credentials for the payment method. For example, “4pwmr0z2fh8qrt2isjdvkujow0”.

String

“4pwmr0z2fh8qrt2isjdvkujow0”

 

transactions.authorizationStatus.declineCode

Card Decline Code

The code returned by the payment provider for the reason a card was declined.

String

"01"

 

transactions.authorizationStatus.processorAuthCode

Processor Auth Code

The payment processor-provided authorization code. For example: "741256"

String

"741256"

 

transactions.authorizationStatus.processorTransactionId

Processor Transaction ID

The unique ID the payment processor or gateway uses for the order. This field isn’t required, but it is highly recommended. Uniqueness for this property is not enforced. Example: "NMI0983"

String

"NMI0983"

 

transactions.authorizationStatus.acquirerReferenceNumber

Acquirer Reference Number

A unique number for a credit or debit card transaction created during the transfer from the merchant’s bank through the payment processor. Enables identifying the transaction when errors occur. The format is an 11-digit number. For example: "40614857370"

String

"40614857370"

 

promotions

Promotions Properties Array

An array containing all of the promotions applied to this order.

Array

   

promotions.id

Promotion ID

The merchant-provided identifier for the promotion. Uniqueness for this property is not enforced. Example: "BOGO10"

String

"BOGO10"

 

promotions.description

Promotion Description

The merchant-provided promotion description. For example: "Buy one, get one 10% off"

String

"Buy one, get one 10% off"

 

promotions.status

Promotion Status

The merchant-provided promotion status. For example: "accepted".

String

"accepted"

 

promotions.statusReason

Promotion Status Reason

The merchant-provided promotion status reason. For example: "Promotion cannot be combined."

String

"Promotion cannot be combined."

 

promotions.discount

Promotion Discount Properties Object

The object containing the details of the discount.

Object

   

promotions.discount.percentage

Discount Percentage

The percentage of the total amount that was reduced due to the promotion being applied, represented as a floating point number. For example: 0.1 means 10% discounted.

Float

0.1

 

promotions.discount.amount

Discount Amount

The amount that the total was reduced by due to the promotion being applied in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

100

 

promotions.credit

Credit Properties Object

An object containing the details of the amount of credit that was applied to this order.

Object

   

promotions.credit.creditType

Credit Type

A merchant-defined identifier for the type of credit that was applied. For example: "GIFT_CARD"

String

"GIFT_CARD"

 

promotions.credit.amount

Credit Amount

The amount of the total order that was paid for through a credit in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

100

 

loyalty

Loyalty Properties Object

An object containing the details of a credit that was applied from a loyalty account.

Array

   

loyalty.id

Loyalty ID

The unique identifier for the loyalty transaction. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76"

String

"d121ea2210434ffc8a90daff9cc97e76"

 

loyalty.description

Loyalty Description

A description of the loyalty program being applied. For example: "Pizza Points"

String

"Pizza Points"

 

loyalty.credit

Loyalty Credit Properties Object

An object containing the details of the loyalty credit that was applied to the order.

Object

   

loyalty.creditType

Loyalty Credit Type

A merchant-defined identifier for the type of credit that was applied. For example: "PIZZA_POINTS"

String

"PIZZA_POINTS"

 

loyalty.amount

Loyalty Credit Amount

The amount of the total order that was paid for through a loyalty credit in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

Integer

150

 

customFields

Custom Fields Array

An object that allows passing in Custom Fields. Each key is the custom field’s name as a string (max length: 32 characters). Each value is the custom field’s value as a date, boolean, string (max length: 256 characters), or number. Supported date format is RFC 3339 (ex: 2023-03-30T15:41:58Z). No object or array values are allowed.

Object

{

"keyNumber": 42,

"keyBoolean": true,

"keyString": "value",

"keyDate": "2023-03-30T15:41:58Z"

}

 

In the Orders endpoint example, all data is false. It includes all properties, which would not be the case in a real request (For example: several properties would not be present for digital goods or for digital fulfillment, etc).

Orders endpoint example

{
    "merchantOrderId": "d121ea2210434ffc8a90daff9cc97e76",
    "channel": "DEFAULT",
    "deviceSessionId": "d121ea2210434ffc8a90daff9cc97e76",
    "creationDateTime": "2019-08-24T14:15:22Z",
    "userIp": "192.168.0.1",
    "account": {
        "id": "d121ea2210434ffc8a90daff9cc97e76",
        "type": "BASIC",
        "creationDateTime": "2019-08-24T14:15:22Z",
        "username": "jsmith1",
        "accountIsActive": true
    },
    "items": [
        {
            "id": "d121ea2210434ffc8a90daff9cc97e76",
            "price": 100,
            "description": "Samsung 46'' LCD HDTV",
            "name": "LN46B610",
            "quantity": 1,
            "category": "TV",
            "subCategory": "LCD",
            "isDigital": false,
            "sku": "TSH-000-S",
            "upc": "03600029145",
            "brand": "LG",
            "url": "https://www.example.com/store/tsh-000-s",
            "image": "https://www.example.com/store/tsh-000-s/thumbnail.png",
            "physicalAttributes": {
                "color": "Midnight Purple",
                "size": "XL",
                "weight": "5 lbs.",
                "height": "12 in.",
                "width": "6 in.",
                "depth": "36 cm"
            },
            "descriptors": ["halloween", "mask"]
        }
    ],
    "fulfillment": [
        {
            "type": "SHIPPED",
            "itemIds": ["d121ea2210434ffc8a90daff9cc97e76", "23e69466888d11eda1eb0242ac120002"],
            "accessUrl": "https://example.com/digitalgood/1213901281290",
            "shipping": {
                "amount": 893,
                "provider": "FEDEX",
                "trackingNumbers": ["TBA056059680404"],
                "method": "EXPRESS"
            },
            "recipient": {
                "sameAsBilling": false,
                "person": {
                    "name": {
                        "first": "William",
                        "last": "Doe",
                        "preferred": "Bill"
                    },
                    "emailAddress": "john.doe@example.com",
                    "phoneNumber": "+12081234567",
                    "address": {
                        "addressType": "SHIPPING",
                        "line1": "12345 MyStreet Ave",
                        "line2": "Suite 256",
                        "city": "Poplar Bluff",
                        "region": "CO",
                        "countryCode": "US",
                        "postalCode": "63901-0000"
                    }
                }
            },
            "store": {
                "id": "d121ea2210434ffc8a90daff9cc97e76",
                "name": "10th & Main Acme Inc.",
                "address": {
                    "addressType": "LOCATION",
                    "line1": "12345 MyStreet Ave",
                    "line2": "Suite 256",
                    "city": "Poplar Bluff",
                    "region": "CO",
                    "countryCode": "US",
                    "postalCode": "63901-0000"
                }
            }
        }
    ],
    "transactions": [
        {
            "processor": "ADYEN",
            "processorMerchantId": "5206080947171696",
            "payment": {
                "type": "CREDIT_CARD",
                "paymentToken": "insertlongtokenhere",
                "bin": "483312",
                "last4": "1111"
            },
            "subtotal": 10000,
            "orderTotal": 100,
            "currency": "USD",
            "tax": {
                "isTaxable": true,
                "taxableCountryCode": "US",
                "taxAmount": 400,
                "outOfStateTaxAmount": 43
            },
            "billedPerson": {
                "name": {
                    "first": "William",
                    "last": "Doe",
                    "preferred": "Bill"
                },
                "emailAddress": "john.doe@example.com",
                "phoneNumber": "+15551234567",
                "address": {
                    "addressType": "BILLING",
                    "line1": "5813-5849 Quail Meadows Dr",
                    "line2": "string",
                    "city": "Poplar Bluff",
                    "region": "CO",
                    "postalCode": "63901-0000",
                    "countryCode": "US"
                }
            },
            "transactionStatus": "CAPTURED",
            "authorizationStatus": {
                "authResult": "Approved",
                "dateTime": "2022-10-31T22:01:43Z",
                "verificationResponse": {
                   "addressStatus": "Match",
                   "postalCodeStatus": "NoMatch",
                   "cvvStatus": "Unknown"
                },
                "paymentCredentials": {
                    "type": "SEPA",
                    "token": "4pwmr0z2fh8qrt2isjdvkujow0"
                },
                "declineCode": "01",
                "processorAuthCode": "741256",
                "processorTransactionId": "NMI0983",
                "acquirerReferenceNumber": "40614857370"
            }
        }
    ],
    "promotions": [
        {
            "id": "BOGO10",
            "description": "Buy one, get one 10% off",
            "status": "accepted",
            "statusReason": "Promotion cannot be combined.",
            "discount": {
                "percentage": 0.1,
                "amount": 100
            },
            "credit": {
                "creditType": "GIFT_CARD",
                "amount": 0
            }
        }
    ],
    "loyalty":{
            "id": "d121ea2210434ffc8a90daff9cc97e76",
            "description": "Pizza Points",
            "credit": {
                "creditType": "PIZZA_POINTS",
                "amount": 150
            }
    },
    "customFields": [
        {
            "key": "UDF1",
            "value": "value"
        }
    ]
}

Response

The response from the Kount 360 Orders endpoint is a JSON object in the response body. The response will look different if you performed a risk inquiry in the request:

  • Both requests: most of the data that is included is echoed back from the request, although it also returns a order.kountOrderId that will be the unique identifier for the order that will later be used to look up or update the order you just created.

  • No risk inquiry: the response will not include an order.riskInquiry property, which includes all of the risk inquiry data.

  • Including a risk inquiry: the response will include an order.riskInquiry property, which includes many data points that provide insights and guidance on the risk profile of the order.

The primary field to observe is the order.riskInquiry[0].guidance property. It is the property that indicates the final outcome of the policies configured in the Policy Engine. It will provide one of the following responses as the guidance/suggestion for how to proceed according to the Kount 360 Payments Risk solution:

  • Approve – Proceed with the transaction

  • Decline – Do not proceed with the transaction

Automate the order management process by keying off these responses and then utilize any of the additional data returned for internal processing.

You can verify the Device Data Collector (DDC) process was successful through the response. If the order.riskInquiry[0].device.id contains an ID, then the DDC process was successful. If the value is an empty string or null, then the DDC process was unsuccessful.

Payment Risk response properties table

Proposed JSON Path

Field Name

Description

Type

Examples

version

Response Version

The version of the Payment Risk endpoint response contract used for this response, as a string containing a three-digit semantic version number. For example, “1.0.0”.

String

"1.0.0"

order

Order Properties Object

An object containing the details of the order that was performed.

Object

 

order.kountOrderId

Kount Order ID

Unique identifier of the order so the order can be queried and referenced in other contexts. For example, "d121ea2210434ffc8a90daff9cc97e76".

String

"d121ea2210434ffc8a90daff9cc97e76"

order.merchantOrderId

Merchant Order ID

The merchant-provided unique identifier for this order. Uniqueness for this property is not enforced. Example, "d121ea2210434ffc8a90daff9cc97e76".

String

"d121ea2210434ffc8a90daff9cc97e76"

order.channel

Order Channel

Unique identifier of the website or app from where the order originated. For example, "ACME_IOS_APP"

String

"ACME_IOS_APP"

order.deviceSessionId

Device Session ID

Unique identifier for the customer’s end-user’s session on the site/app. Must be the same session ID used in the device data collection from the client-side Kount SDK. Uniqueness for this property is not enforced, but customers should provide unique values. Example: "d121ea2210434ffc8a90daff9cc97e76"

String

"d121ea2210434ffc8a90daff9cc97e76"

order.creationDateTime

Order Creation Date/Time

The date and time that the order was placed.

String

"2019-08-24T14:15:22Z"

order.riskInquiry

Order Risk Inquiry Array

An array of objects containing the details of the risk inquiry evaluation performed on the payment.

Array

 

order.riskInquiry.guidance

Payment Guidance

The final outcome of the policies configured in the Policy Engine. One of the following enumeration values determining the guidance/suggestion for how to proceed:

"Approve" – Proceed with the transaction.

"Review" – More evaluation is needed to determine whether to approve or decline.

"Decline" – Do not proceed with the transaction.

String

"Approve"

order.riskInquiry.omniscore

Payment Omniscore

A number between 0 and 100 indicating the machine-learning model’s evaluation of the transaction risk. The higher the score, the safer the transaction was evaluated to be. For example, “99.9”.

Float

99.9

order.riskInquiry.persona

Payment Persona

Properties of the person the machine learning model has associated with this transaction.

Object

 

order.riskInquiry.persona.uniqueCards

Persona Unique Cards

Number of unique payment tokens (payment methods/cards) associated with the persona. For example, "3".

Integer

3

order.riskInquiry.persona.uniqueDevices

Persona Unique Devices

Number of unique device IDs (browsers/phones) associated with the persona. For example, "5".

Integer

5

order.riskInquiry.persona.uniqueEmails

Persona Unique Emails

Number of unique email addresses associated with the persona.

Integer

2

order.riskInquiry.device

Device Properties Object

The properties collected from the device (browser, phone/app) that the end user used to place the order.

Object

 

order.riskInquiry.device.id

Device ID

The unique identifier that was generated by Kount for the device. Example: "7363b8ae6b2247b99f5d56fc81102254"

String

"7363b8ae6b2247b99f5d56fc81102254"

order.riskInquiry.device.collectionDateTime

Device Collection Date/Time

The date/time when the device collection began. Supported date/time format is ISO 8601. For example, “2021-03-02T19:01:37Z”.

String

 

order.riskInquiry.device.browser

Device Browser Name

The name and the version number of the browser that was used (if any) that the end user used to place the order. For example, "Chrome 106.0.0.0".

String

"Chrome 106.0.0.0"

order.riskInquiry.device.deviceAttributes

Device Attributes

The properties of the device hardware/software that the end user used to place the order.

Object

 

order.riskInquiry.device.deviceAttributes.os

Device Operating System

The operating system that was running on the device when the order was placed. For example, "Android 9.0.0".

String

"Android 9.0.0"

order.riskInquiry.device.deviceAttributes.firstSeenDateTime

Device First Seen Date/Time

The date/time when this device was first seen in the Kount 360 network. Useful to understand whether this is a device with a long history. Supported date/time format is ISO 8601. For example, “2021-03-02T19:01:37Z”.

String

“2021-03-02T19:01:37Z”

order.riskInquiry.device.deviceAttributes.language

Device Language

The language that the operating system or app had set at the time the order was placed. For example, "en-US".

String

"en-US"

order.riskInquiry.device.deviceAttributes.timezoneOffset

Device Timezone Offset

The offset for the device local time zone when compared to GMT (in minutes). For example, "60".

Integer

60

order.riskInquiry.device.deviceAttributes.mobileSdkType

Mobile SDK Type

Which Kount SDK was used during the collection process, either iOS or Android. For example, "Android App SDK".

String

"Android App SDK"

order.riskInquiry.device.location

Device Location Properties Object

An object containing the location properties that the device collector reported the device was located when the order was placed.

Object

 

order.riskInquiry.device.location.areaCode

Location Area Code

A string containing the three-digit US Area Code of the device during collection (based on an IP address match from Neustar). For example, "555".

String

"555"

order.riskInquiry.device.location.city

Location City

The name of the city where the device was reportedly located when the order was placed. For example, "Boise".

String

"Boise"

order.riskInquiry.device.location.country

Location Country

The name of the country where the device was reportedly located when the order was placed. For example, "United States of America".

String

"United States of America"

order.riskInquiry.device.location.countryCode

Location Country Code

The country code where the device was reportedly located when the order was placed in the ISO-3166 format. For example, "US".

String

"US"

order.riskInquiry.device.location.latitude

Location Latitude

A floating point number of the latitude where the device was reportedly located when the order was placed. For example, "44.8729"

Float

44.8729

order.riskInquiry.device.location.longitude

Location Longitude

A floating point number of the longitude where the device was reportedly located when the order was placed. For example, "-120.3456".

Float

-120.3456

order.riskInquiry.device.location.postalCode

Location Postal Code

A string containing the postal code where the device was reportedly located when the order was placed. For example, "90210".

String

"90210"

order.riskInquiry.device.location.region

Location Region

The name of the state or province where the device was reportedly located when the order was placed. For example, "Oregon".

String

"Oregon"

order.riskInquiry.device.location.regionCode

Location Region Code

The short code for the state or province where the device was reportedly located when the order was placed. For example, “ID”.

String

“ID”

order.riskInquiry.device.tor

Device on TOR Network

A boolean indicating whether the IP address is listed as a Tor node.

Boolean

TRUE

order.riskInquiry.policySetExecuted

Policy Set Executed Properties Object

The properties of all of the policies and triggers that were evaluated and passed during the evaluation of the transaction.

Object

 

order.riskInquiry.policySetExecuted.policySet

Policy Set Properties Object

An object containing the properties of the policy set.

Object

 

order.riskInquiry.policySetExecuted.policySet.id

Policy Set ID

The unique ID of the policy set that was executed during transaction evaluation. For example, "62dcb41e-3be6-4c20-a3a1-614837a870a3".

String

"12345678-1234-1234-1234-123456789012"

order.riskInquiry.policySetExecuted.policySet.name

Policy Set Name

The name of the policy set that was executed during transaction evaluation.

String

"Policy Set for Catching Fraud"

order.riskInquiry.policySetExecuted.trigger

Trigger

An object containing the properties of the trigger that was fired as part of the executed policy set.

Object

 

order.riskInquiry.policySetExecuted.trigger.id

Trigger ID

The unique ID of the trigger that was executed during transaction evaluation. For example, "f28eb8fc-3e71-41ae-a02f-a095046aa682".

String

"12345678-1234-1234-1234-123456789012"

order.riskInquiry.policySetExecuted.trigger.name

Trigger Name

The name of the trigger that was executed during transaction evaluation. For example, "iOS Acme App Trigger"

String

"Trigger for Catching Fraud"

order.riskInquiry.policySetExecuted.trigger.priority

Trigger Priority

An integer representing the priority of the trigger in the policy set that was executed during transaction evaluation, where 1 is the top priority trigger.

Integer

1

order.riskInquiry.policySetExecuted.policiesExecuted

Executed Policies

An array containing the policies that were executed during the transaction evaluation.

Array

 

order.riskInquiry.policySetExecuted.policiesExecuted.id

Policy ID

The unique ID of the policy. For example, "f4ce5e65-a7c7-4cbb-a7bc-c104df90cbea".

String

"12345678-1234-1234-1234-123456789012"

order.riskInquiry.policySetExecuted.policiesExecuted.name

Policy Name

The name of the policy. For example, "Disallowed Countries".

String

"Policy for Catching Fraud"

order.riskInquiry.policySetExecuted.policiesExecuted.outcome

Policy Outcome Properties Object

An object containing the type of an outcome that occurred on a policy and the value of the outcome for that type of outcome.

Object

 

order.riskInquiry.policySetExecuted.policiesExecuted.outcome.type

Policy Outcome Type

The type of the outcome. For example, "guidance".

String

"guidance"

order.riskInquiry.policySetExecuted.policiesExecuted.outcome.value

Policy Outcome Value

The value of the outcome. For example, "decline".

String

"Approve"

Below is an example response body for the Orders endpoint. Note that the data is all false, and this example includes all properties, which would not be the case in a real response.

JSON

{
    "version": 0,
    "order": {
        "kountOrderId": "d121ea2210434ffc8a90daff9cc97e76",
        "merchantOrderId": "d121ea2210434ffc8a90daff9cc97e76"
        "channel": "DEFAULT",
        "deviceSessionId": "d121ea2210434ffc8a90daff9cc97e76",
        "creationDateTime": "2019-08-24T14:15:22Z"
        "riskInquiry": [
            {
                "guidance": "Approve",
                "omniscore": 99.9,
                "persona": {
                    "uniqueCards": 0,
                    "uniqueDevices": 0,
                    "uniqueEmails": 0
                },
                "device": {
                    "id": "7363b8ae6b2247b99f5d56fc81102254",
                    "collectionDateTime": "2019-08-24T14:15:22Z",
                    "browser": "Chrome 106.0.0.0",
                    "deviceAttributes": {
                        "os": "Android 9.0.0",
                        "firstSeenDateTime": "2021-03-02T19:01:37Z",
                        "language": "en-US",
                        "timezoneOffset": "60",
                        "mobileSdkType": "Android App SDK"
                    },
                    "location": {
                        "areaCode": "555",
                        "city": "Boise",
                        "country": "United States of America",
                        "countryCode": "US",
                        "latitude": 44.8729,
                        "longitude": -120.3456,
                        "postalCode": "90210",
                        "region": "Oregon",
                        "regionCode": "ID"
                    },
                    "tor": true
                },
                "policySetExecuted": {
                    "policySet": {
                        "id": "12345678-1234-1234-1234-123456789012",
                        "name": "Policy Set for Catching Fraud"
                    },
                    "trigger": {
                        "id": "12345678-1234-1234-1234-123456789012",
                        "name": "Trigger for Catching Fraud",
                        "priority": 1
                    },
                    "policiesExecuted": [
                        {
                            "id": "12345678-1234-1234-1234-123456789012",
                            "name": "Policy for Catching Fraud",
                            "outcome": {
                                "type": "guidance",
                                "value": "Approve"
                            }
                        }
                    ]
                }
            }
        ]
    }
}
Was this article helpful?
6 out of 6 found this helpful