This guide details the integration process for Kount Near Real-Time Chargeback Prevention (NRTCP) APIs. During the integration process, Kount’s Solution Engineers provide direct support for your development staff to facilitate quick, accurate responses to any integration questions that might arise.
Integration Guide Overview:
To begin using NRTCP, you must provide the following:
- 6 months of previous transaction data, minimum (The more data provided, the better)
- Merchant Identification Numbers (MIDs)
- Acquirer BIN
- Order number
- Transaction date and time
- Transaction amount
- Basic description
Since the data you provide is used to match records with Visa, sending more than the minimum data set allows us to better match the Visa data. If customer cart information is available, it can provide additional data points to better match your records to help prevent chargebacks.
Typical data points to provide along with the minimum data set include:
- All items purchased during a transaction
- Item IDs
- Taxes paid
- Amounts
- Customer emails
- Customer names
- A link to the item
- Shipping information
Additional data points to consider specifically when working with video games or online memberships include:
- Account username
- Last log in
- Download times
- Play times
The goal is to attain enough information that can be used to trigger a memory in the consumer that confirms the purchase - or confirms that a family member might have completed the transaction.
Send Data to Kount
Send transaction data to Kount through the Kount API or through a SSH File Transfer Protocol (SFTP) connection. The credentials for both connection types require a unique login specific to your company. The login information is provided to you by your Kount Customer Service Manager during your initial integration. If you would like to use the API or SFTP and do not have your company credentials, contact your Kount representative.
Specifications for the Kount API
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”}}
NOTE: All data sent to Kount via the upload API must be in a JSON string format that is capable of parsing back to JSON. See the table under Standard Transaction Data Elements for additional support.
Specifications for uploading data via SFTP
SFTP Production Hostname: ff.sftp.kount.com
SFTP Sandbox Hostname: ff.sftp.sandbox13.kount.com
Transaction and refund data can be uploaded to Kount via SFTP in either CSV or JSON form. Your Kount provided credentials for the SFTP are the same for the sandbox and production environments. All data element types sent via SFTP MUST follow the naming convention defined in the Standard Transaction Data Elements table below. If there is not a verbatim match for an element name during transmission, the data stops loading and the upload fails.
Standard Transaction Data Elements (include in the transaction data):
Field | Type | Size | Recommendation | Additional Info |
authStatus | string | 50 | Optional | D (decline) or A (authorized) |
customerID | string | 250 | Optional | 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 | Optional | 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 | 4 | 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 | Optional | 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 | Optional | 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 | Optional | Quantity of item purchased | |
price | int | Optional | (Price of item in order currency) * 100. Example $44.09 would be 4409 |
Receive Data from Kount
Receive NRTCP data from Kount via the API or an SFTP connection. The table below details the data elements provided in these reports.
Name | Definition |
requestID | Unique Kount identifier for each inquiry/alert |
issuerTrxID | Transaction ID from the issuer |
requestDateTime | Date request was received |
MerchantOrderNumber | Merchant order number provided in the request |
orderTotal | Total amount of the order received in the request |
currency | The currency of the transaction received in the request in ISO 3 |
billingType | In the Inquiry Report, it is used to determine if the request has been deflected or not (1=deflection, 3=Chargeback occurred and is not a deflection) |
transactionAmount | Transaction amount referenced by the case |
Outbound API/Webhook:
To get webhook push notifications for events, you must provide the following to Kount:
- API URL
- Required header key value pairs. Authentication (API key, etc.) is covered in the headers.
- A list of the event type data the customer wants to receive. The JSON element eventType is included in the response, and can be one of the following.
Verifi Events (ORDER_INQUIRY, DISPUTE, DISPUTE_NOTICE, CANCEL, FRAUD_NOTICE)
Ethoca Events (ETHOCA_FRAUD, ETHOCA_DISPUTE)
The POST JSON body contains:
Element |
Type |
Description |
arn |
string |
Acquirer Reference Number (ARN) associated with the request |
cardAcceptorID |
string |
Card Acceptor ID (Not currently available, will add when available) |
merchantOrderID |
string |
Merchant's Order ID associated with the request |
transactionAmount |
number |
Transaction Amount referenced in the request |
transactionCurrency |
string |
The currency of the transaction received in the request in ISO 3 |
transactionDateTime |
string |
Date of the transaction |
transactionID |
string |
Transaction ID from the Issuer |
accountNumber |
string |
Masked Payment Account Number in the following format: NNNNNNxxxxxxNNNN |
descriptor |
string |
Billing Descriptor associated with the transaction |
|
|
|
eventType |
string |
Type of Request |
eventDateTime |
string |
Date the request was received |
disputeCode |
string |
Case Reason Code |
requestID |
string |
Unique identifier for the transaction. This can be used to respond to Alerts via API |
Any fields in the JSON payload that are empty or null are not included for that transaction. For example, the arn field will not be included when the ARN is not available.
Additional fields can be included at any time.
Below is a sample payload from a DISPUTE eventType:
{
"transactionCurrency": "USD",
"transactionDateTime": "2021-02-01T00:00:00Z",
"transactionAmount": 707.25,
"descriptor": "FraudPVP *",
"merchantOrderID": "1826003090",
"arn": "66231111111111111122292",
"accountNumber": "422602xxxxxx1234",
"transactionID": "1612231599281",
"events": [
{
"disputeCode": "41",
"eventDateTime": "2021-02-02T02:07:33Z",
"requestID": "93a360ca-4612-4fb1-9267-a9bba46c8ce1",
"eventType": "DISPUTE"
}
]
}
Below is a sample payload from a ETHOCA_DISPUTE eventType:
{
"transactionCurrency": "USD",
"transactionDateTime": "2020-12-01T12:30:00Z",
"transactionAmount": 300.55,
"descriptor": "KOUNTQA06MERCHANT",
"accountNumber": "928292******1111",
"transactionID": "12345678",
"events": [
{
"eventDateTime": "2021-02-02T21:50:01Z",
"requestID": "6e801087-e408-4048-ab48-f10e7bc44e6a",
"eventType": "ETHOCA_DISPUTE"
}
]
}
Below is a sample payload from a Verifi INQUIRY eventType:
{
"transactionCurrency": "USD",
"transactionDateTime": "2020-01-29T20:10:00Z",
"transactionAmount": 12345,
"descriptor": "THE_ELECTRONICS_STORE",
"merchantOrderID": "ORDER_1000",
"arn": "9862277678",
"accountNumber": "435600xxxxxx1234",
"transactionID": "11111111111111111111",
"events": [
{
"eventDateTime": "2021-02-05T20:40:59Z",
"requestID": "b35fcd48-f185-43bd-8719-044d64a4cfcb",
"eventType": "ORDER_INQUIRY"
}
]
}
Outbound SFTP Files:
By using Kount's outbound SFTP, you can receive event reports for Inquiries (OI), Fraud Notifications (CDRN), Dispute Notifications (CDRN), Dispute Alerts (CDRN), Cancel Alerts (CDRN).
NOTE: To receive event reports via SFTP, you must provide Kount with your site credentials.
Event Report Example Data:
Inquiry Report (OI Inquiries)
requestID |
issuerTrxID |
requestDateTime |
merchantOrderNumber |
orderTotal |
currencyISO3 |
billingType |
transactionAmount_USD |
198 |
300071263573808 |
9/30/2020 10:32:00 |
ORDER_1000 |
123.45 |
959 |
1 |
123.45 |
NOTE: BillingType 1 indicates a notification, billingType 3 indicates a deflection.
Fraud Report (Fraud Notifications)
requestID |
issuerTrxID |
requestDateTime |
merchantOrderNumber |
orderTotal |
currencyISO3 |
reasonCode |
transactionAmount_USD |
197 |
300071263573808 |
9/30/20 22:24:00 |
ORDER_1000 |
39.99 |
959 |
10 |
39.99 |
Chargeback Report (Dispute Notifications)
requestID |
issuerTrxID |
requestDateTime |
merchantOrderNumber |
orderTotal |
currencyISO3 |
reasonCode |
transactionAmount_USD |
196 |
300071263573808 |
9/30/20 12:38:00 |
ORDER_1000 |
39.99 |
959 |
10 |
39.99 |
CDRN Cancel Report (CDRN Cancel Alerts)
requestID |
issuerTrxID |
requestDateTime |
merchantOrderNumber |
orderTotal |
currencyISO3 |
reasonCode |
transactionAmount_USD |
195 |
300071263573808 |
9/30/20 10:02:00 |
eba066b4c7f478f6943dc2026363c4a4 |
39.99 |
840 |
75 |
39.99 |
CDRN Dispute Report (CDRN Dispute Alerts)
requestID |
issuerTrxID |
requestDateTime |
merchantOrderNumber |
orderTotal |
currencyISO3 |
reasonCode |
transactionAmount_USD |
194 |
300071263573808 |
9/30/20 10:02:00 |
eba066b4c7f478f6943dc2026363c4a4 |
39.99 |
840 |
75 |
39.99 |
CDRN Actions via API
Through the NRTCP portal, you can receive and respond to the CDRN Actions, receive email notifications when an Alert is received, or receive and respond via API. Contact your Kount Customer Success Manager to set up the queue
.
Receive CDRN Alerts from Kount
You can receive email notifications when a CDRN Alert is received. This allows you to timely respond to the alerts in the Kount NRTCP portal.
As described in the webhook section of this document, you can receive a webhook push of the data in the alert, and then respond to the alert.
Respond to the Alert to Kount (POST)
Response payload:
{
“actions”: array of CDRNAction objects
}
CDRNAction object:
{
“id”: string, required
“action”: string, required
“amount”: string, optional
“currency”: string, optional
“date”: string, optional
“statusCode”: string, required
}
- ID is the Request ID from the Alert
- Action is one of: resolved, declined or cancelled (resolved or declined for a Dispute Alert, cancelled or declined for a Cancel Alert)
- Amount is the amount refunded
- Currency is the three-character code of the currency in ISO 3
- Date is the date of the refund or cancelation in the format YYYY-MM-DD.
- Status Code is the status code to return with the Action (See table for Codes)
Status Code |
Outcome |
Description* |
100 |
RESOLVED |
Case Resolved, Credit & Cancellation processed |
101 |
RESOLVED |
Case Resolved, Partial Credit & Cancellation processed |
102 |
RESOLVED |
Case Resolved, Authorization Cancelled |
951 |
RESOLVED |
Transaction Previously credited for Case Amount, no balance remaining |
130 |
CANCELLED |
Cancellation processed |
900 |
DECLINED |
Unmatched Case - General/Other |
901 |
DECLINED |
Unmatched Case - Merchant not Participating |
902 |
DECLINED |
Unmatched Case - Unable to locate Original Transaction |
940 |
DECLINED |
Duplicate Request |
950 |
DECLINED |
Merchant account closed, unable to process Credit |
952 |
DECLINED |
Transaction Previously received a Chargeback, no balance remaining |
953 |
DECLINED |
Request is outside of eligibility timeframe |
954 |
DECLINED |
Transaction 3D Secure authenticated successfully (Verified by Visa/MasterCard SecureCode) |
955 |
DECLINED |
Could not honor cancel request |
956 |
DECLINED |
Matched, unable to stop order fulfillment |
957 |
DECLINED |
Matched, Proceed with Chargeback for resolution |
Sample Alert and Response payloads:
Dispute Alert sent to merchant endpoint
{
"arn": {"1346791346789"},
"cardAcceptorID": "1346789",
"merchantOrderID": "20000000",
"transactionAmount": "10.00",
"transactionCurrency": "USD",
"transactionDataTime": "2020-09-05T12:00:00Z",
"transactionID": "13465798123456789",
"acquirerBin": "423456",
"events": [
{
"requestId": "6989a395-c2df-40f4-8021-4aa0a3a15fbd ",
"eventType": "Dispute",
"eventDateTime": "2020-12-12T12:00:00Z",
"disputeCode": "10.4"
}
]
}
Dispute Alert response sent to Kount
{
"actions": [
{
"id": "6989a395-c2df-40f4-8021-4aa0a3a15fbd",
"amount": "10.00",
"currency": "USD",
"date": "2020-12-13",
"statusCode": "100",
"action": "resolved"
}
]
}