Payments Fraud is an AI-driven digital fraud prevention solution, operating on the Kount 360 platform, that swiftly delivers accurate identity trust decisions. It provides a REST API endpoint and a user-friendly portal for managing orders, resolving transactions, and more.
Payments Fraud collects and assesses data from two main sources: the Device Data Collector (DDC) and the Orders API.
The DDC captures information about the end-user's device during an online purchase and discreetly transmits it to Kount 360 without disrupting the end-user experience.
The Orders API analyzes order data along with the DDC information and incorporates Kount's Digital Identity Global Network to generate a fraud score. Additionally, you can enforce your own fraud and business policies during the evaluation process.
After evaluating an order, a response containing a score, device fingerprint, and guidance on handling the order is sent back to you. With this response data, you can manage orders according to its systems and policies.
The Device Data Collector gathers information from a customer’s device by running client-side scripts and then sends that data to Kount. This passive analysis conceals the Kount 360 interaction with the customer and does not affect the customer’s experience.
The flow for device data collection follows this pattern:
-
Generate Session ID: Generates a session ID and provides it to the Device Data Collector SDK.
-
Device Data Collector SDK collects and sends device data: The Device Data Collector sends the collected device data to Kount 360.
-
Submit event data with session ID to your server: When the event data (the order, login, or new account opening data) gets submitted to your server, include the session ID that was passed to the Device Data Collector.
-
Send event data with session ID to Kount 360: Pass the session ID in the call to Kount 360, along with the rest of the event data.
-
Associate device data and event data by matching the session ID: Kount 360 associates the device data and the event data by using the session ID that was passed to Kount 360.
For detailed instructions, use our guided Device Data Collector Content generator or follow the steps in the Native iOS and Android SDKs article.
Sign in to Kount 360 to authenticate for API access.
-
Sign in to Kount 360. There are two integration environments: sandbox and production. Only integrate into our sandbox environment if you are integrating a pre-production environment without production data.
-
Select Admin, and then Product Configuration.
-
Select Options for the organization in which you want to create an API key, and then select Create API Key.
-
Select Create.
-
Expand the organization.
-
Copy the API key and save it in a secure location. You will need the API key to create a bearer token.
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 allowed two active API keys per customer.
After you have provisioned your API credentials in the portal, retrieve a temporary bearer token to authenticate calls to the Kount 360 API. Provide the API Key and Client ID in an HTTP POST to a specific login.kount.com URL.
With a successful exchange, the returned JSON provides a special bearer token, which is the access_token property. The exchange also provides an expiration date, the expires_in property, provided in seconds until expiration. The API to retrieve the bearer token depends on if you are calling the sandbox or production environment.
The values are:
Sandbox
Auth Server URL:
https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token
API Service Host:
https://api-sandbox.kount.com
Production
Auth Server URL:
https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token
API Service Host:
https://api.kount.com
After obtaining the bearer token, use it to authenticate requests to the Kount 360 API. Include the token in the Authorization header of your HTTP API request, prefixed with Bearer {bearer token}.
To prevent authentication issues, refresh the token before it expires. Tokens issued by login.kount.com expire after 20 minutes, but client credentials remain valid unless revoked. Minimize calls to the /token endpoint by implementing token expiration handling in your customer applications. Always check if a token has expired before requesting a new one, as excessive calls to the /token endpoint could result in rate limiting.
Examples of retrieving and using the bearer token in popular programming languages:
The Orders API (/commerce/{VERSION}/orders) merges device data obtained from the Device Data Collector (DDC) with order data. Once these datasets are merged, the Orders API assesses and assigns a score to each order. Following the evaluation, the endpoint provides a response, allowing you to approve, decline, or flag the order for further review.
Typical integrations of the Payments Fraud solution into your server-side payment workflow follow seven steps:
-
Purchase Initiation: When an end user starts the purchase process, usually by entering payment information and clicking the purchase button, the Device Session ID must be transmitted from the browser to the server if it has not been generated and associated on the server side.
-
Order Processing: Your server processes the order, either pre-payment authorization or post-payment authorization.
-
Orders API Call: Call the Kount 360 Orders API and provide transaction details to assess the risk of the transaction. The Device Session ID is required to link the Device Data Collector (DDC) with the order.
-
Order Evaluation: Kount 360 Payments Fraud evaluates data from the device collection and transaction details against the Kount machine learning models, and your defined policies to determine the transaction's risk level.
-
Orders Risk Inquiry Response: The Orders API sends back the final decision (Approve, Decline, or Review) for the transaction.
-
Determining Order Outcome: Utilize the decision provided by Kount 360 Order Risk Inquiry to decide how it should affect the final payment outcome in their payment workflow.
-
Payment Result Screen: Once you determine how to proceed with payment processing, the final result displays on the end user's payment result screen.
There are differences between engaging the Kount 360 Orders Risk Inquiry endpoint before payment authorization or after payment authorization.
Querying the Kount 360 Orders Risk Inquiry Service before authorizing from the payment gateway:
-
Allows you 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 from the payment gateway.
-
Requires you to pay for inquiries, including transactions that result in declining a transaction. Orders that are declined by a business or fraud rule are not sent to the Payment Processor, preventing extra payment processor fees.
Pre-authorization workflow:
Querying the Kount 360 Orders Risk Inquiry Service after attempting an authorization from the payment gateway:
-
Allows all payment gateway information (Authorization, AVS, CVV) to be passed to the Orders API, allowing rules to be created regarding AVS and CVV data.
-
Prevents linking on payment tokens across the Kount network. Some payment gateways do not pass credit card data once they receive it.
-
Does not require a call to the Orders API to perform an update.
-
Requires you 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 calls the Kount 360 Orders Risk Inquiry Service endpoint.
Post-authorization workflow:
The Orders API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication.
The device data collection process creates a session identifier that must be passed in as the session identifier in the Orders API. This identifier must be unique for at least 30 days. If you use a single session ID on multiple transactions, those transactions link together and affect the risk score.
Sandbox Endpoint
https://api-sandbox.kount.com/commerce/v1/orders
Production Endpoint
https://api.kount.com/commerce/v1/orders
Method: POST
Header Authorization: Bearer token
Header Content-Type: application/json
Body: Refer to the Orders Endpoint Request Properties.
When you submit data to the Kount 360 Orders Service, we recommend populating as many fields as possible to enable the most accurate risk scoring. This provides the data that powers the machine learning models.
There are two methods for endpoint use:
-
Perform a risk inquiry that you want to receive guidance on to know if an order should be approved, declined, or reviewed. This is the primary value of the Payments Fraud product, in which you are charged.
-
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 that you get the most accurate risk score when you perform a risk inquiry call.
We encourage you to submit all of your orders by using one of the two methods above. Sending us orders with no risk inquiry improves the accuracy of the orders you send us with a risk inquiry. To perform the risk inquiry call, include the riskInquiry parameter and set its value to true.
/commerce/v2/orders?riskInquiry=true
To perform the Orders Service call without performing a risk inquiry, set the riskInquiry to false, or omit the parameter entirely.
/commerce/v2/orders
When you call the Orders API, you can include or exclude the collected device data. Device data is included by default, and it should be included for most use cases. Device data should only be excluded when you cannot collect the data from the actual end user's device. For example, phone orders, kiosk orders, or in-house orders placed by a customer on behalf of their end-user should exclude device data. Including device data that is not from the actual end user's device can mislead the policy engine and machine learning, especially at high volumes.
To exclude device data from the Orders API, include the excludeDevice parameter and set its value to true.
/commerce/v2/orders?excludeDevice=true
Go to Orders API Reference for the full endpoint documentation.
In order to protect credit or debit card numbers, also known as the Primary Account Number (PAN), we provide you with a tokenization algorithm to create a hash value. This serves as a one-way cryptographic representation of the sensitive payment information.
By tokenizing the payment information, it enables us to utilize the data in our machine learning models and other fraud-prevention systems while ensuring anonymity and complying with the Payment Card Industry Data Security Standards (PCI-DSS).
During the Payments Fraud integration process, your assigned Solutions Engineer or Integration Engineer provides you with an algorithm and salt to generate a hash value from the Primary Account Number (PAN).
In the Orders Service example, the data is not coherent. All of the IDs are identical (in reality, they are different), and it includes all properties. This would not be the case in a real request. For example, several properties that are in the example would not be present for a digital fulfillment.
The response from the Orders API is a JSON object that is delivered in the response body. The response looks different if you perform a risk inquiry in the request than sending the request without a risk inquiry:
-
Both request types: Most of the data that is included is echoed back from the request, although it also returns an
order.OrderIdproperty that is the unique identifier for the order that enables you to update the order. -
No risk inquiry: The response does not include an
order.riskInquiryproperty, which includes all of the risk inquiry data. -
Including a risk inquiry: The response includes an
order.riskInquiryproperty, which includes many data points that provide insights and guidance on the risk profile of the order.
The order.riskInquiry[0].guidance property provides guidance on a transaction based on the policies configured in Policy Management:
-
Approve – Proceed with the transaction
-
Decline – Do not proceed with the transaction
-
Review – Perform a manual review of a transaction before proceeding. If your subscription includes manual reviews, orders that receive this guidance are added to the Case Queue for review.
Streamline the order management process by using these responses as triggers, and leverage any additional data provided for internal processing.
The Device Data Collector process can be validated through the response. If the order.riskInquiry[0].device.id contains an ID, the Device Data Collection process was successful. If the value is an empty string or null, the Device Data Collection process was unsuccessful.
After sending an order to the Orders API, you might need to update the order by providing the result of payment authorization or providing an order ID. Updating the Order does not perform another risk inquiry. Updating an order is ensures that the system is able to detect and prevent fraud.
The Orders API provides the Order Update and Update Orders' Chargeback and Refunds endpoints to update an order.
-
Order Update is used to update specific data properties of an order, such as the authorization status details and customer-provided order ID.
-
Update Orders’ Chargebacks and Refunds is used to provide updates to the order’s lifecycle, such as whether it resulted in a chargeback or refund.
The orders update is primarily used in a pre-authorization workflow after the order has been sent to the payment processor for authorization and you have received the result. Calling the endpoint lets Kount know the result of the authorization for model training, reporting, and order management. Refer to the following chart for the pre-authorization workflow:
The Orders API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to Authentication to learn how to acquire the bearer token. The {Kount Order Id} is a value that would have been retrieved from the order.OrderId in the POST /orders response when the order was originally sent to Kount.
Sandbox Endpoint:
https://api-sandbox.kount.com/commerce/v1/orders/{KOUNT ORDER ID}
Production Endpoint:
https://api.kount.com/commerce/v1/orders/{KOUNT ORDER ID}
Method: PATCH
Header Authentication: Bearer <token>
Header Content Type: application/json
Body: Refer to the properties table.
In order to protect credit or debit card numbers, also known as the Primary Account Number (PAN), we provide you with a tokenization algorithm to create a hash value. This serves as a one-way cryptographic representation of the sensitive payment information.
By tokenizing the payment information, it enables us to utilize the data in our machine learning models and other fraud-prevention systems while ensuring anonymity and complying with the Payment Card Industry Data Security Standards (PCI-DSS).
During the Payments Fraud integration process, your assigned Solutions Engineer or Integration Engineer provides you with an algorithm and salt to generate a hash value from the Primary Account Number (PAN).
The IDs are identical and includes all properties. A request sent from a customer has varying IDs and might not include all properties.
{
"merchantOrderId": "d121ea2210434ffc8a90daff9cc97e76",
"deviceSessionId": "d121ea2210434ffc8a90daff9cc97e76",
"riskInquiry": [
{
"decision": "Approve"
}
],
"fulfillment": [
{
"fulfillmentId": "d121ea2210434ffc8a90daff9cc97e76",
"status": "SCHEDULED",
"accessUrl": "https://example.com/digitalgood/1213901281290",
"shipping": {
"provider": "FEDEX",
"trackingNumber": "TBA056059680404",
"method": "EXPRESS"
}
"digitalDownloaded": true,
"downloadDeviceIp": "192.168.0.1"
}
],
"transactions": [
{
"transactionId": "d121ea2210434ffc8a90daff9cc97e76"
"authorizationStatus": {
"verificationResponse": {
"cvvResult": "Approved",
"avsStatus": "Y"
}
},
"payment": {
"type": "CREDIT_CARD",
"paymentToken": "insertkhashedtokenhere",
"bin": "483312"
}
}
]
}
The endpoint to update orders’ chargebacks and refunds is used for successful orders that result in a chargeback or refund, which could happen weeks or months later. Calling the endpoint improves model training and makes the events available in reporting and order workflow management.
The endpoint takes an array of orders, so you can update multiple orders at a time.
The Orders Batch Update Chargeback Refund API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to Authentication to acquire the bearer token. The {Kount Order Id} is a value that would have been retrieved from the order.kountOrderId in the POST /orders response when the order was originally sent to Kount.
Sandbox Endpoint:
https://api-sandbox.kount.com/commerce/v1/orders:batchUpdateChargebackRefund
Production Endpoint:
https://api.kount.com/commerce/v1/orders:batchUpdateChargebackRefund
Method: PUT
Header Authorization: Bearer <token>
Header Content Type: application/json
Body: Refer to the properties table.
The properties in the request can only be used at different times and can only be selected as refund, a chargeback, or both — both cannot be unselected. You can only delete the chargeback or the refund, but not both at the same time. For example:
-
isChargeback,isRefund, or both can be true; both cannot be false. -
If an order already has a refund and
isChargebackis passed with a value of true, the refund is removed and the chargeback added. If a refund is added to an order with a refund present, the refund is removed and the refund added. -
chargebackReasonCodeshould only be present ifisChargebackis true. -
cardTypeshould only be present ifisChargebackis true. -
isChargebackDeletedorisRefundDeletedcan be true, but not both. -
If either
isChargebackDeletedorisRefundDeletedare true, thenisChargeback,isRefund,chargebackReasonCode, andcardTypeshould not be present.
The chargebackRefundUpdates.cardType value must match the Card Type value to allow the chargebackRefundUpdates.chargebackReasonCode property to have a value in the Reason Code column.
If the endpoint response updates are successful, the only property received is an errors property containing an empty array. Since the request input is an array, if there are errors, the errors property will contain an array, and each error will include a kountOrderId property that correlates to the input order that resulted in an error.