Quick Links

Payments Fraud Integration Guide

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.

Device Data Collector Implementation

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. This data is one of the foundations of Kount 360 fraud protection.

The flow for device data collection follows this pattern:

2024___K360_Payments_Fraud_Integration_Diagrams_-_Session_ID_Flow.svg

The steps for Device Data Collector setup are:

  1. Generate Session ID — Generates a session ID and provides it to the Device Data Collector SDK.

  2. DDC SDK collects and sends device data — The Device Data Collector sends the collected device data to Kount 360.

  3. 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.

  4. 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.

  5. Associate device data and event data by matching the session ID — Kount 360 associates the device data and the event data, using the session ID that was passed to Kount 360.

Use our guided Device Data Collector Content generator or follow the steps in the Native iOS and Android SDKs article.

Provisioning an API Key

Sign in to Kount 360 to authenticate your software for access to our API services.

  1. 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.

  2. Select Admin, and then Developer.

  3. Select Options, and then Create API Key.

  4. Select Create.

  5. Expand the organization.

  6. 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 allowed two active API keys per customer. To create another API key after creating two API keys, delete one of the existing keys.

Creating a Bearer Token

Following the OAuth 2.0 framework, after you have provisioned your API credentials in the portal, retrieve a temporary bearer token to authenticate calls to Kount 360 API. Provide the client credentials in an HTTP POST to a specific login.kount.com URL.

With a successful exchange, the returned JSON provides a special bearer token (the access_token property), as well as an expiration date (the expires_in property, provided in seconds until expiration). The API to retrieve the bearer token varies depending if you are calling the Sandbox or Production system.

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, utilize 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. Typically, 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:

Python

Bash

TypeScript

Go

Sending Orders for Evaluation

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 transaction. Following the evaluation, the endpoint provides a response, allowing you to approve, decline, or flag the order for further review.

Payments Fraud Server-Side Integration Sequence

Typical integrations of the Payments Fraud solution into your server-side payment workflow follow seven steps:

2024___K360_Payments_Fraud_Integration_Diagrams_-_High_Level_Sequence.svg
  1. Purchase Initiation: When an end user starts the purchase process, typically by entering payment information and clicking the purchase button, the Device Session ID must be transmitted from the browser to the server if it hasn't been generated and associated on the server side.

  2. Order Processing: Your server processes the order, either pre-credit-authorization or post-credit-authorization, and assesses if the payment carries a high risk.

  3. Orders Risk Inquiry Service Call: Call the Kount 360 Orders API with the risk inquiry parameter 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.

  4. 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.

  5. Orders Risk Inquiry Response: The Orders API sends back the final evaluation (Approve, Decline, or Review) for the transaction.

  6. Determining Order Outcome: Utilize the guidance provided by Kount 360 Order Risk Inquiry to decide how it should affect the final payment outcome in their payment workflow.

  7. Payment Result Screen: Once you determine how to proceed with payment processing, the final result displays for the end user.Payment Result Screen – Once you determine how to proceed with payment processing, the final result displays for the end user.

Pre-authorization versus Post-authorization

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

Pre-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:

2024___K360_Payments_Fraud_Integration_Diagrams_-_Pre-Auth_Update_Highlight__1_.svg

Post-authorization

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:

2024___K360_Payments_Fraud_Integration_Diagrams_-_Post-Auth_Workflow.svg

Invoking the Request from the Backend (Site Code)

The Orders Service 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 Service. 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.

Request Parameters and Data Submission

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/v1/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/v1/orders

Go to Orders API Reference for the full endpoint documentation.

Protecting Sensitive Payment Information

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).

Sending Payment Information to the Orders API

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).

  1. Tokenize the payment information into a hash value.

  2. Pass the hash value to the Orders API in the transactions.payment.paymentToken property.

Orders Endpoint Request Properties Table

Orders Service Example

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.

Payload Response Properties

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.kountOrderId property 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.riskInquiry property, which includes all of the risk inquiry data.

  • Including a risk inquiry: The response includes an order.riskInquiry property, 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.

Orders Service Response Properties Table

Orders Service Response Body Example

All properties are included in the example. A response to a customer request might not include all properties.

Updating Order Details

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.

Orders Update API

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:

2024___K360_Payments_Fraud_Integration_Diagrams_-_Pre-Auth_Update_Highlight.svg

Orders Update API Specifications

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.kountOrderId 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.

Protecting Sensitive Payment Information

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).

Sending Payment Information to the Orders API

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).

  1. Tokenize the payment information into a hash value.

  2. Pass the hash value to the Orders API in the transactions.payment.paymentToken property.

Orders Update API Request Properties

Orders Update API Request Example

The IDs are identical and includes all properties. A request sent from a customer has varying IDs and might not include all properties.

{
  "payment": {
    "authResult": "Approved",
    "addressStatus": "Match",
    "postalCodeStatus": "Match",
    "cvvStatus": "Match",
    "type": "CREDIT_CARD",
    "token": "insertkhashedtokenhere",
    "bin": "483312"
  },
  "merchant": {
    "orderId": "d121ea2210434ffc8a90daff9cc97e76",
    "fraudAssessment": "APPROVED"
  },
  "device": {
    "sessionId": "d121ea2210434ffc8a90daff9cc97e76"
  }
}

Orders Update Response Properties

Orders Update API Response Example

{
  "kountOrderId": "7VQSXX7KHFK5J94X",
  "merchantOrderId": "951300195193806",
  "channel": "DEFAULT",
  "deviceSessionId": "222exampleUpdatedDeviceSessionId222",
  "creationDateTime": "2024-03-23T14:15:22Z",
  "riskInquiry": [],
  "transactions": []
}

Update Orders’ Chargebacks and Refunds

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.

Specifications

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.

Request Parameters and Data Submission

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 isChargeback is 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.

  • chargebackReasonCode should only be present if isChargeback is true.

  • cardType should only be present if isChargeback is true.

  • isChargebackDeleted or isRefundDeleted can be true, but not both.

  • If either isChargebackDeleted or isRefundDeleted are true, then isChargeback, isRefund, chargebackReasonCode, and cardType should not be present.

Chargeback Reason Codes

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.

Update Orders' Chargebacks and Refunds Request Properties

Update Orders' Chargebacks and Refunds API Request Example
{
  "chargebackRefundUpdates": [
    {
      "kountOrderId": "4H777ZTLYSVVVP4L",
      "isChargeback": true,
      "isRefund": false,
      "chargebackReasonCode": "10.2",
      "cardType": "visa",
      "isChargebackDeleted": false,
      "isRefundDeleted": false
    }
  ]
}

Update Orders' Chargebacks and Refunds Response Properties

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.

Response without Errors Example
{
  "errors": []
}
Response with Errors Example
{
  "errors": [
    {
      "kountOrderId": "7VQSXX7KHFK5J94X",
      "error": "7VQSXX7KHFK5J94X transaction update cannot delete both chargeback and refund"
    }
  ]
}
Was this article helpful?
6 out of 6 found this helpful