Sending Data for Dispute and Chargeback Management

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/kff/uploads

Production

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

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

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}]},{"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"}

Standard Transaction Data Elements

Table 1. Include these fields in the transaction data

Field

Type

Size

Recommendation

Additional Info

authStatus

string

50

Recommended

D (decline) or A (authorized)

customerID

string

250

Recommended

Customer ID used by the merchant

paymentInformation

json object

     

avsMatch

string

10

Optional

Boolean string as "True" or "False"

cardBin

string

6

Recommended

First 6 of card used for purchase

last4

string

100

Recommended

Last 4 on card used for purchase

authCode

string

 

Recommended

Authorization code provided to authorize the purchase

arn

string

 

Recommended

Acquirer reference number

billingName

string

50

Recommended

Name on card used for purchase

billingAddress1

string

50

Recommended

Street address for card used for purchase

billingAddress2

string

50

Optional

Address line 2 for card used for purchase

billingCity

string

50

Optional

City for card used for purchase

billingState

string

50

Optional

Billing state for card used for purchase

postalCode

string

150

Optional

Zip or postal code for card used for purchase

billingCountry

string

50

Optional

Country for card used for purchase

additionalTransactionData

json object

     

deviceType

string

50

Optional

PC, iPhone, Android Phone, etc

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

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

ipAddress

string

50

Recommended

IP Address

orderCurrency

string

10

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.

invoiceNumber

string

50

Optional

A reference number by which the customer can identify the transaction.

orderTotal

int

11

Required

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

shoppingCart

json array of objects

     

itemID

string

50

Recommended

ID that identifies the product to the merchant, like a SKU.

itemType

string

200

Recommended

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

itemName

string

100

Recommended

What the item is known as in the merchant store

itemDescription

string

250

Recommended

Item description

quantity

int

 

Recommended

Quantity of item purchased

price

int

 

Recommended

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


Was this article helpful?
1 out of 3 found this helpful