1. Kount Developer
  2. Dispute and Chargeback Management
  3. Integration

Sending Data for Dispute and Chargeback Management

You can send transaction data to us through our API endpoints.

API Authentication

  1. Kount provides you an API secret through an encrypted email.

  2. Send an HTTP POST with the API secret to the Sandbox or Production Auth Server URL.

  3. You then receive a returned JSON payload that includes a special bearer token, as well as an expiration date provided — within a few seconds — in the form of an expires_in attribute.

    Note

    If you do not refresh the special bearer token before it expires, the call to the API fails and a 401 Unauthorized message displays. Most tokens issued by https://login.kount.com expire after 20 minutes. Avoid unnecessary calls to the /token endpoint by writing customer applications to factor token expiration. Make sure to check whether a token is expired before requesting a new one. Excessive calls to the /token endpoint might result in rate limiting.

The API varies depending on if you call 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

Sample HTTP POST

Python

"""sandbox"""
TOKEN_ENDPOINT = "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token"
API_URL = "https://api-sandbox.kount.com"
API_KEY = ""

r = requests.post(TOKEN_ENDPOINT,
                  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 + "/kff/uploads",
                  headers={'Authorization': "Bearer " + t},
                  json={
                     "transactions": "[{\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L7\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410045\",\"last4\":\"3847\",\"authCode\":\"3845737\",\"billingName\":\"JOHN DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"browserOrAppDesc\":\"Chrome 88.0.4324.182\",\"deviceType\":\"\"},\"customerEmailAddress\":\"john.doe@kount.com\",\"customerName\":\"JOHN DOE\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7150\",\"ipAddress\":\"81.233.22.53\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T12:22:13.000Z\",\"orderNumber\":\"ABC123\",\"orderTotal\":4783,\"shoppingCart\":[{\"itemDescription\":\"BLACK MAC KEYBOARD\",\"itemName\":\"MAC KEYBOARD\",\"quantity\":1,\"itemType\":\"ACCESSORIES\",\"itemID\":\"225\",\"price\":4783}]},{\"kountClientID\":\"999666\",\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L8\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410394\",\"last4\":\"3948\",\"billingName\":\"JANE DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"deviceType\":\"iPhone 12\"},\"customerEmailAddress\":\"jane.doe@kount.com\",\"customerName\":\"Jane Doe\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7151\",\"ipAddress\":\"72.17.122.212\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T11:25:29.000Z\",\"orderNumber\":\"ABC124\",\"orderTotal\":1812,\"shoppingCart\":[{\"itemDescription\":\"MACHINE LEARNING FOR DUMMIES\",\"itemName\":\"MACHINE LEARNING\",\"quantity\":2,\"itemType\":\"BOOK (PRINTED)\",\"itemID\":\"A34322\",\"price\":906}]}]"                
                })
print("Response:", r.json())

TypeScript

const axios = require('axios')

const API = 'https://api-sandbox.kount.com'
const ISSUER = 'https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
const API_KEY = ''

async function getBearerToken() {

    const auth = await axios({
        url: `${ISSUER}/v1/token`,
        method: 'post',
        headers: {
            authorization: `Basic ${API_KEY}`
        },
        params: {
            grant_type: 'client_credentials',
            scope: 'k1_integration_api'
        }
    })

    return auth.data.access_token
}

async function evaluateLogin(token: string) {

    const resp = await axios({
        url: `${API}/kff/uploads`,
        method: 'post',
        headers: {
            authorization: `Bearer ${token}`,
        },
        data: {
            transactions: "[{\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L7\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410045\",\"last4\":\"3847\",\"authCode\":\"3845737\",\"billingName\":\"JOHN DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"browserOrAppDesc\":\"Chrome 88.0.4324.182\",\"deviceType\":\"\"},\"customerEmailAddress\":\"john.doe@kount.com\",\"customerName\":\"JOHN DOE\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7150\",\"ipAddress\":\"81.233.22.53\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T12:22:13.000Z\",\"orderNumber\":\"ABC123\",\"orderTotal\":4783,\"shoppingCart\":[{\"itemDescription\":\"BLACK MAC KEYBOARD\",\"itemName\":\"MAC KEYBOARD\",\"quantity\":1,\"itemType\":\"ACCESSORIES\",\"itemID\":\"225\",\"price\":4783}]},{\"kountClientID\":\"999666\",\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L8\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410394\",\"last4\":\"3948\",\"billingName\":\"JANE DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"deviceType\":\"iPhone 12\"},\"customerEmailAddress\":\"jane.doe@kount.com\",\"customerName\":\"Jane Doe\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7151\",\"ipAddress\":\"72.17.122.212\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T11:25:29.000Z\",\"orderNumber\":\"ABC124\",\"orderTotal\":1812,\"shoppingCart\":[{\"itemDescription\":\"MACHINE LEARNING FOR DUMMIES\",\"itemName\":\"MACHINE LEARNING\",\"quantity\":2,\"itemType\":\"BOOK (PRINTED)\",\"itemID\":\"A34322\",\"price\":906}]}]",
        }
    })

    return resp.data
}
const main = async () => {
    const token = await getBearerToken()
    const resp = await evaluateLogin(token)
    console.log(JSON.stringify(resp, null, 4))
}

main()

GoLang

package main

import (
        "bytes"
        "encoding/json"
        "fmt"
        "io"
        "net/http"
)

type config struct {
        API      string
        Issuer   string
        ClientId string
        APIKey   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 TransactionsRequest, token string) string {

        j, _ := json.Marshal(payload)

        req, _ := http.NewRequest(http.MethodPost, api+"/kff/uploads", 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 TransactionsRequest struct {
        Transactions string `json:"transactions"`
}

func main() {
        config := config{
                API:    "https://api-sandbox.kount.com",
                Issuer: "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357",
                APIKey: "",
        }
        client := &http.Client{}
        token := getToken(client, config.Issuer, config.APIKey)

        payload := TransactionsRequest{
                Transactions: "[{\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L7\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410045\",\"last4\":\"3847\",\"authCode\":\"3845737\",\"billingName\":\"JOHN DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"browserOrAppDesc\":\"Chrome 88.0.4324.182\",\"deviceType\":\"\"},\"customerEmailAddress\":\"john.doe@kount.com\",\"customerName\":\"JOHN DOE\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7150\",\"ipAddress\":\"81.233.22.53\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T12:22:13.000Z\",\"orderNumber\":\"ABC123\",\"orderTotal\":4783,\"shoppingCart\":[{\"itemDescription\":\"BLACK MAC KEYBOARD\",\"itemName\":\"MAC KEYBOARD\",\"quantity\":1,\"itemType\":\"ACCESSORIES\",\"itemID\":\"225\",\"price\":4783}]},{\"kountClientID\":\"999666\",\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L8\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410394\",\"last4\":\"3948\",\"billingName\":\"JANE DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"deviceType\":\"iPhone 12\"},\"customerEmailAddress\":\"jane.doe@kount.com\",\"customerName\":\"Jane Doe\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7151\",\"ipAddress\":\"72.17.122.212\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T11:25:29.000Z\",\"orderNumber\":\"ABC124\",\"orderTotal\":1812,\"shoppingCart\":[{\"itemDescription\":\"MACHINE LEARNING FOR DUMMIES\",\"itemName\":\"MACHINE LEARNING\",\"quantity\":2,\"itemType\":\"BOOK (PRINTED)\",\"itemID\":\"A34322\",\"price\":906}]}]",
        }

        resp := evaluate(client, config.API, payload, token)
        fmt.Printf("%s\n", resp)
}

Bash

#!/usr/bin/env bash

API='https://api-sandbox.kount.com'
TOKEN_ENDPOINT="https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token"
API_KEY=''

# Get our token (it is valid for 20 minutes)
RESPONSE=$(curl -s -X POST "${TOKEN_ENDPOINT}?grant_type=client_credentials&scope=k1_integration_api" -H "Authorization: Basic ${API_KEY}" -H "Content-Type: application/x-www-form-urlencoded")
TOKEN=$(echo $RESPONSE | jq -r .access_token)

# Make our request
REQUEST_DATA="{\"transactions\":\"{}\"}"
RESPONSE=$(curl -s -X POST ${API}/kff/uploads -H "Authorization: Bearer ${TOKEN}" -d "$REQUEST_DATA")
echo "$RESPONSE" | jq

Upload API Specifications

Endpoints:

  • Sandbox: https://api-sandbox.kount.com/kff/uploads

  • Production: https://api.kount.com/kff/uploads

Method: POST

Header Authorization: Bearer <token>

Header Content-Type: application/json

Body: {"transactions": {“type” : “string”}}

Send your data in a JSON string format that is capable of parsing back to JSON. See Standard Transaction Data Elements for the elements to include.

Example JSON string for Upload API

{ "transactions": "[{\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L7\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410045\",\"last4\":\"3847\",\"authCode\":\"3845737\",\"billingName\":\"JOHN DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"browserOrAppDesc\":\"Chrome 88.0.4324.182\",\"deviceType\":\"\"},\"customerEmailAddress\":\"john.doe@kount.com\",\"customerName\":\"JOHN DOE\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7150\",\"ipAddress\":\"81.233.22.53\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T12:22:13.000Z\",\"orderNumber\":\"ABC123\",\"orderTotal\":4783,\"shoppingCart\":[{\"itemDescription\":\"BLACK MAC KEYBOARD\",\"itemName\":\"MAC KEYBOARD\",\"quantity\":1,\"itemType\":\"ACCESSORIES\",\"itemID\":\"225\",\"price\":4783}]},{\"kountClientID\":\"999666\",\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L8\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410394\",\"last4\":\"3948\",\"billingName\":\"JANE DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"deviceType\":\"iPhone 12\"},\"customerEmailAddress\":\"jane.doe@kount.com\",\"customerName\":\"Jane Doe\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7151\",\"ipAddress\":\"72.17.122.212\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T11:25:29.000Z\",\"orderNumber\":\"ABC124\",\"orderTotal\":1812,\"shoppingCart\":[{\"itemDescription\":\"MACHINE LEARNING FOR DUMMIES\",\"itemName\":\"MACHINE LEARNING\",\"quantity\":2,\"itemType\":\"BOOK (PRINTED)\",\"itemID\":\"A34322\",\"price\":906}]}]"
}

Example JSON for Upload API

[
    {
        "authStatus": "A",
        "kountOrderNumber": "DVVN1ZZYU2L7",
        "paymentInformation": {
            "avsMatch": "False",
            "cardBin": "410045",
            "last4": "3847",
            "authCode": "3845737",
            "billingName": "JOHN DOE",
            "billingAddress1": "1005 W Main St",
            "billingAddress2": "",
            "billingCity": "Boise",
            "billingState": "ID",
            "postalCode": "83702",
            "billingCountry": "USA"
        },
        "additionalTransactionData": {
            "browserOrAppDesc": "Chrome 88.0.4324.182",
            "deviceType": ""
        },
        "customerEmailAddress": "john.doe@kount.com",
        "customerName": "JOHN DOE",
        "cvvValidatedAtPurchase": "False",
        "deviceID": "358680B39D5240A8C382A11F2EBC7150",
        "ipAddress": "81.233.22.53",
        "orderCurrency": "USD",
        "orderDateTime": "2021-02-21T12:22:13.000Z",
        "orderNumber": "ABC123",
        "orderTotal": 4783,
        "shoppingCart": [
            {
                "itemDescription": "BLACK MAC KEYBOARD",
                "itemName": "MAC KEYBOARD",
                "quantity": 1,
                "itemType": "ACCESSORIES",
                "itemID": "225",
                "price": 4783
            }
        ],
        "campaignId": "314",
        "campaignName": "Divine Fit ACV (Gummies) -- CS",
        "other":{
            "merchantStoreName":"Divine Fit Mulberry Stand",
            "merchantName":"Divine Fit Keto",
            "contactUs":"Contact Information",
            "websiteLink":"http://www.divinefitketo4you.com5"
        }
    },    {
        "authStatus": "A",
        "kountOrderNumber": "DVVN1ZZYU2L7",
...
    }
]

Standard Transaction Data Elements

Table 3. Include these fields in the transaction data

Field

Type

Size

Recommendation

Additional Info

additionalTransactionData

JSON object

arn

string

Recommended

Acquirer reference number

authCode

string

Recommended

Authorization code provided to authorize the purchase

authStatus

string

50

Recommended

D (decline) or A (authorized)

avsMatch

string

10

Optional

Boolean string as True or False

billingAddress1

string

50

Recommended

Street address for the card used for the purchase

billingAddress2

string

50

Optional

Address line 2 for the card used for the purchase

billingCity

string

50

Optional

City for the card used for the purchase

billingCountry

string

50

Optional

Country for the card used for the purchase

billingName

string

50

Recommended

Name on card used for purchase

billingState

string

50

Optional

Billing state for tjhe card used for the purchase

browserOrAppDesc

string

50

Optional

For a web browser use IE, Chrome, Firefox etc or for other methods such as video game clients use XYZ Game Client or other description consumer will recognize

cardBin

string

6

Recommended

First six numbers of the card used for the purchase

contactUs

string

50

Recommended

child of the other field

customerID

string

250

Recommended

Customer ID used by the merchant

customerEmailAddress

string

50

Recommended

Customer email address

customerName

string

100

Recommended

Customer name

cvvValidatedAtPurchase

string

10

Optional

True or False

deviceID

string

50

Optional

Device ID

deviceType

string

50

Optional

PC, iPhone, Android Phone, etc

invoiceNumber

string

50

Optional

A reference number by which the customer can identify the transaction

ipAddress

string

50

Recommended

IP Address

itemDescription

string

250

Recommended

Item description

itemID

string

50

Recommended

ID that identifies the product to the customer, like an SKU

itemName

string

100

Recommended

What the item is known as in the customer store

itemType

string

200

Recommended

Type of item such as ebook, virtual currency, season pass, etc.

last4

string

100

Recommended

Last four numberts on the card used for the purchase

merchantName

string

50

Recommended

Child of the other field

merchantStoreName

string

50

Recommended

Child of the other field

orderCurrency

string

Recommended

ISO 4217Alpha 3 ( “USD” )

orderDateTime

string

Required

ISO 8601 format in UTC time zone: YYYY-MM-DDThh:mm:ssZ

orderNumber

string

50

Required

A reference number by which the merchant can identify the transaction. This should be the ID that is sent to the acquirer.

orderTotal

int

11

Required

(Total amount of the order)*100 - Example $44.09 would be 4409

other

JSON object

Used for merchantStoreName, merchantName, contactUs, websiteLink

paymentInformation

JSON object

postalCode

string

150

Optional

Zip or postal code for card used for purchase

price

int

Recommended

(Price of item in order currency) * 100. Example $44.09 would be 4409

shoppingCart

JSON array of objects

quantity

int

Recommended

Quantity of item purchased

websiteLink

string

1000

Recommended

Child of the other field

Was this article helpful?
1 out of 4 found this helpful
Integration
Receiving and Responding to Alerts in Dispute and Chargeback Management
Sending Data for Dispute and Chargeback Management