Quick Links

How to Integrate Kount 360 Ecommerce Fraud (Approve/Decline)

Ecommerce Fraud (Approve/Decline) is an AI-driven digital fraud prevention solution that delivers accurate identity trust decisions in milliseconds; built on the Kount 360 platform. Integrate Ecommerce Fraud (Approve/Decline) to gain access to the Rest API endpoint, view your account in the portal, manage users, resolve transactions, and more.

Step 1: Configure Users in the Self-Service Portal

Log in to the Ecommerce Fraud self-service portal to create your administrator password, retrieve your clientID, and provision user access for your company. You must set up your credentials before you can begin authenticating with Kount or accessing the Kount 360 Rest API.

  1. Open the Kount 360 Account Activation email sent to the administrator email address you provided Kount.
  2. Click Activate Account.
  3. Create an administrator password, and then click to be redirected to the Kount 360 login page.
  4. Log in using the credentials you just created.
    You are redirected to Kount 360.
  5. If you are an Admin and need to create one or more Admin or Power Users, on the side navigation menu, click Admin then User Management.
    1. Click the Roles/Users toggle button mu3.png to switch from the Roles view to the Users view.
    2. Click Create User.
      The Create User form displays.
    3. Fill out the Create User form.
      Note: For the Role drop-down menu, select Power User or Admin. The Power User and Admin roles are required to be able to create and set up clients.
    4. Click Save.
      A notification displays confirming new user creation.
  6. From the side navigation menu, click Developer then Clients.
  7. Click New Client.
    The New Client Name window displays.
  8. Enter a name for the new client, and then click OK.
    The API key window displays. Do not close this window.
    k360api.png
  9. Copy the API key and save it in a secure location.
    Note: This is the only time you are able to view and copy the API key. Do not close this window without copying the API key. If you close the window without copying the API key, then you must create a new API key using the options (...) menu. You only are allowed two new API key creations per client.

Once you have provisioned your clientID and credentials, continue to the next step to set up your bearer token, or you can continue to edit user access and manage the portal.

Step 2: Device Data Collector Implementation

The Device Data Collector (DDC) gathers information from a customer’s device by redirecting the device browser momentarily to Kount then back to the merchant. This passive analysis conceals the Kount interaction with the customer and does not affect the customer’s purchasing experience.

To ease DDC set up, use our guided DDC content generator or follow the steps below.

The DDC requires a two step process for mobile integration: Integration (Step 1) and Invocation (Step 2).

iOS SDK

Android SDK

Hybrid

If you are developing for iOS and Android using a hybrid application refer to:

Web SDK

Refer to How to Integrate the Kount Web Client SDK 1.1.4 into Your Website

Step 3: Authentication

After you have provisioned your clientID and credentials in the self-service portal, follow these steps to retrieve a temporary bearer token.

Provide the client credentials in a POST to login.kount.com. With a successful exchange, the returned JSON provides a special bearer token, as well as an expiration date (expires_in attribute, provided in seconds until expiration).

Example POST in Python:

# Retrieve bearer token

r = requests.post(f'{ISSUER}/v1/token',
     params={'grant_type': 'client_credentials', 'scope': 'k1_integration_api'},
     headers={'Authorization': f'Basic {CREDS}', 'Content-Type': 'application/x-www-form-urlencoded'})

token = r.json()['access_token']
  

The returned bearer token is passed to the Kount sandbox API at api-sandbox.kount.com.

Example POST in Python:

# Make the Kount One evaluate call and print the result.

r = requests.post(f'{API}/identity/v1/evaluate',
                  headers={'Authorization': f'Bearer {token}'},
                  json={"clientId": f"{CLIENT_ID}",
                        "payment": {"paymentType": "CARD", "paymentToken": "4111111111111111", "bin": "414709"}})

print(r.json())
    

This token must be refreshed before it expires. If it is not refreshed, the call to the API fails with 401 Unauthorized. Most tokens issued by login.kount.com expire after 20 minutes. Client credentials never expire unless they are explicitly revoked.

Step 4: Payment Evaluation

The Payment Risk evaluation API endpoint api.kount.com/payments/ joins device data provided by the DDC process with the customer order data sent from the merchant/customer. Once the device data and order data are combined, the Payment Risk endpoint evaluates and scores each transaction. After the evaluation, the endpoint returns a response so the customer can approve or decline the order. The following section describes how to implement the Payment Risk evaluation into your payment workflow.

Ecommerce Fraud Server-Side Integration Sequence

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

image (20).png

  1. Purchase initiated – An end user initiates the purchase, typically after they’ve entered their payment information and clicked on the button to perform the purchase.
  2. Process order – As the Kount customer/merchant server processes the order, either pre-credit-authorization or post-credit-authorization, they must determine if the payment is high risk.
  3. Call Payment Risk Endpoint – The customer/merchant calls the Kount 360 Payment Risk endpoint and passes the transaction details to determine the risk of the transaction.
  4. Evaluate Order – Kount 360 Ecommerce Fraud evaluates the data from the device collection and the details of the transaction against Kount’s Identity Trust Global Network, the machine learning models, and the customer/merchant defined policies to determine the risk.
  5. Payment Risk Response – The Payment Risk endpoint returns the final evaluation (Approve or Decline) for the transaction.
  6. Determine Order Result – The customer/merchant leverages the Kount 360 Payment Risk evaluation and determines how it should influence the final result for the payment in their payment workflow.
  7. Payment Result Screen – Once the customer/merchant determines how to proceed with processing the payment, the final result is displayed to the end user.

Pre-authorization versus Post-authorization

The following sections describe the differences in engaging the Kount 360 Payment Risk endpoint before payment authorization or after payment authorization.

Pre-authorization

Querying the Kount 360 Payment Risk endpoint before authorizing from the payment gateway:

  • Allows the merchant to avoid processing fees on transactions that result in declining a transaction.
  • Sends all credit card information to Kount.
  • Requires a call to the Events endpoint to update the status of the payment authorization or to provide other details provided by the payment gateway.
  • Requires a customer/merchant to pay for inquiries, including transactions that result in declining a transaction (orders that are declined by a business rule are not sent to the Payment Processor, alleviating extra payment processor fees).

Pre-Authorization Workflow:

int1.png

Post-Authorization

Querying the Kount 360 Payment Risk endpoint after attempting an authorization from the payment gateway:

  • Allows all payment gateway information (Authorization, AVS, CVV) to be passed to Kount 360 Ecommerce Fraud, allowing rules to be created regarding AVS and CVV data
  • Prevents linking on Payment Token across the Kount network. Some payment gateways do not pass credit card data once they receive it
  • Does not require a call to the Events API to perform an update
  • Requires a customer/merchant 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 results in calling the Kount 360 Payment Risk API endpoint

Post-Authorization Workflow:

int2.png

Invoking the Kount 360 Payment Risk Endpoint

Specifications

The Payment Risk endpoint is a RESTful HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to the Authentication step for how to acquire the bearer token.

The session identifier created during the DDC process must be passed in as the session identifier in the Payment Risk endpoint. This identifier must be unique for at least 30 days. If a single Session ID were to be used on multiple transactions, those transactions would link together and erroneously affect the risk score.

Endpoints

  • Sandbox: https://api-sandbox.kount.com/kff/uploads
  • Production: https://api.kount.com/payments/v2/evaluate

Method: POST
Header Authorization: Bearer <token>
Header Content-Type: application/json
Body: Refer to the Body Property table below.

Reference

Request Parameters and Data Submission

When submitting data to the Kount 360 Payment Risk endpoint, it is recommended to send as much data as possible. As part of the API call, there are required fields that result in an error if they are not populated.

Body Property table

Body Property

Description

URL path: /{version}/evaluate

N/A

clientId

Kount's unique identifier for a Client. Generated from within the Kount 360 portal.

userType

Customer/merchant designation/type/category for a customer’s end-user. For example, “VIP”.

sessionId

Unique identifier for the customer’s end-user’s session on the site/app. Must be the same session ID used in the device data collection from the client-side Kount SDK.

siteId

Unique identifier of the website from where the order originated.

userIp

The customer/merchant’s end-user’s IPv4 address (in dotted decimal notation), as identified by the customer/merchant. For example, “192.168.1.27”

orderNumber

Customer/merchant’s unique identifier for the specified transaction/order.

Payment Information

 

payment.paymentToken

The payment token submitted by the merchant for the order (credit card, payer ID, routing/transit, MICR, and account number).


The payment token is hashed with salted SHA256.


If paymentType is set to “NONE” then the paymentToken value should be left empty.


POST-AUTH CALLS ONLY – If the credit card information is not available and a tokenized value is returned from the payment processor, set paymentType=”TOKEN” and send the token returned from the payment processor in the paymentToken field.

payment.bin

The Bank Identification Number. Made up of the first six or eight digits of a credit or debit card.

payment.paymentType

The payment type used in the transaction as specified by the customer/merchant:


“APAY” - Apple Pay

“CARD” - Credit Card

“PYPL” - PayPal

“CHEK” - Check

“NONE” - None

“TOKEN” - Token provided from payment processor

“GDMP” - Green Dot Money Pack

“GOOG” - Google Checkout

“BLML” - Bill Me Later

“GIFT” - Gift Card

“BPAY” - BPAY

“NETELLER” - Neteller

“GIROPAY” - GiroPay

“ELV” - ELV

“MERCADE_PAGO” - Mercade Pago

“SEPA” - Single Euro Payments Area

“INTERAC” - Interac

“CARTE_BLEUE” - Carte Bleue

“POLI” - POLi

“SKRILL” - Skrill/Moneybookers

“SOFORT” - Sofort

“AMZN” - Amazon Pay

“SAMPAY” - Samsung Pay

“ALIPAY” - AliPay

“WCPAY” - WeChat Pay

“CRYPTO” - Crypto Payments

“KLARNA” - Klarna

“AFTRPAY” - Afterpay

“AFFIRM” - Affirm

“SPLIT” - Splitit

“FBPAY” - Facebook Pay

payment.total

The total amount of currency in the transaction in its lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”.

payment.authorizationStatus

The authorization status returned to the merchant from the payment processor. Orders where authorizationStatus=”A” will aggregate towards the order velocity of the persona while orders where authorizationStatus=”D” will decrement the order velocity of the persona.

payment.currency

The three-letter ISO-4217 code of the currency used in the transaction. If a code is not provided, it defaults to “USD”

payment.avst

The street verification response returned to the customer/merchant from the payment processor as validated by the Address Verification System. The expected values are:


M = Match

N = No Match

X = Unsupported or Unavailable

payment.avsz

The Zip Code verification response returned to the customer/merchant from the payment processor as validated by the Address Verification System. The expected values are:


M = Match

N = No Match

X = Unsupported or Unavailable

payment.cvvr

The Card Verification Value (CVV, CVS) response returned to the customer/merchant from the payment processor. The expected values are:

M = Match

N = No Match

X = Unsupported or Unavailable

Billing Information

 

billing.emailAddress

The email address of the person/company billed for the order. For example, “john.doe@example.com”

billing.firstName

The first name (forename) of the person/company billed for the order. For example, “John”.

billing.lastName

The last name (surname) of the person/company billed for the order. For example, “Doe”.

billing.address.line1

The first line of the billing address. For example, “12345 Mystreet Ave”.

billing.address.line2

The optional second line of the billing address. For example, “Suite 123”.

billing.address.city

The city of the billing address. For example, "Poplar Bluff"

billing.address.state

The state or province of the billing address. For example, “CO”.

billing.address.postalCode

The postal code of the billing address. For example, "63901-0000".

billing.address.countryCode

The country code of the billing address in the ISO-3166 format. For example,  "US".

billing.phoneNumber

The phone number of the person billed for the order in the E.123 standard format. For example, "+15551234567".

Shipping Information

 

shipping.address.line1

The first line of the shipping address. For example, "12345 MyStreet Ave".

shipping.address.line2

The second line of the shipping address. For example, "Suite 256”

shipping.address.city

The city of the shipping address. For example, "Poplar Bluff".

shipping.address.countryCode

The country code of the shipping address in the ISO-3166 format. For example, "US".

shipping.emailAddress

The email address of the person the order is shipped to. For example, "john.doe@example.com".

shipping.firstName

The first name of the person the order is shipped to. For example, “John”.

shipping.lastName

The last name of the person the order is shipped to. For example, “Doe”.

shipping.address.postalCode

The postal code of the shipping address. For example, "63901-0000".

shipping.phoneNumber

The phone number of the person the order is being shipped to in the E.123 standard format. For example, "+12081234567".

shipping.address.state

The state or province of the shipping address. For example, “CO”.

shipping.shippingType

A two-digit code to indicate the type/class of shipping used to ship the order. The following nomenclature is expected for shipping types to be passed to Kount:

Same Day = “SD”

Next Day = “ND”

Second Day = “2D”

Standard = “ST”

Product Details

 

shoppingCart.items

Shopping cart data array of objects representing each item (separate SKU with quantity) in the order.

shoppingCart.items[].description

The description of the item being purchased. For example, "Samsung 46' LCD HDTV".

shoppingCart.items[].name

The name of the item being purchased, typically the SKU. For example, "LN46B610".

shoppingCart.items[].price

The price of the single item in the lowest currency factor. For example, The lowest currency in USD is pennies, so $1.00 would have the value of “100”. Must be a natural number including 0. For example, 100.

shoppingCart.items[].quantity

The quantity of the item being purchased. For example, 1.

shoppingCart.items[].type

A high level or generalized description of the item added to the shopping cart. For example, "TV".

Miscellaneous Information

 

userCreationDate

The date and time that the client records was when the user was created in their system. Should be in the ISO-8601 format. For example, "2019-08-24T14:15:22Z".

userId

The client’s unique identifier for a client’s end user. For example, "meoyyd8za8jdmwfm".

clientDefinedFields

An object to hold custom fields. Each property key is the custom field name as a string (max 32 characters). The property value is the custom field value as a date, boolean, string (max 256 characters), or number. Supported date format is ISO 8601 (ex: 2021-03-02T19:01:37Z). No object or array values are allowed.


For example:


"clientDefinedFields": {

    "key1": "string1",

    "key2": 89

}

Response

The response from the Kount 360 Payment Risk endpoint is a JSON object in the response body.

The primary field to observe is the paymentRiskResponse.guidance property. It is the property that indicates the final outcome of the policies configured in the Policy Engine. It will provide one of the following responses as the guidance/suggestion for how to proceed according to the Kount 360 Ecommerce Fraud solution:

  • Approve – Proceed with the transaction.
  • Decline – Do not proceed with the transaction.

You can automate the order management process by keying off these responses and then utilize any of the additional data returned for internal processing.

Payment Risk response properties table:

Payment Risk response properties table

Body Property

Description

version

The version of the Payment Risk endpoint response contract used for this response, as a string containing a three-digit semantic version number. For example, “1.0.0”.

paymentRiskResponse

All of the properties of the payment risk evaluation performed on the provided transaction.

paymentRiskResponse.transactionId

Unique identifier of the transaction so the transaction can be queried and referenced in other contexts. For example, "d121ea2210434ffc8a90daff9cc97e76".

paymentRiskResponse.sessionId

Unique identifier for this user’s session on the site/app. Should be the same session ID that was used for device collection from the client-side Kount SDK. For example, "d121ea2210434ffc8a90daff9cc97e76".

paymentRiskResponse.siteId

Customer-provided unique identifier of the website where the order originated. Can be any arbitrary string, as long as it is unique to each site the customer wants to track separately.

paymentRiskResponse.orderNumber

Merchant’s unique identifier for this order. 

paymentRiskResponse.omniscore

A number between 0 and 100 indicating the machine-learning model’s evaluation of the transaction risk. The higher the score, the safer the transaction was evaluated to be. For example, “99.9”.

paymentRiskResponse.guidance

The final outcome of the policies configured in the Policy Engine. One of the following enumeration values determining the guidance/suggestion for how to proceed:


"Approve" – Proceed with the transaction.

"Decline" – Do not proceed with the transaction.

paymentRiskResponse.persona

Properties of the person the machine learning model has associated with this transaction.

paymentRiskResponse.persona.uniqueCards

Number of unique payment tokens (payment methods/cards) associated with the persona.

paymentRiskResponse.persona.uniqueDevices

Number of unique device IDs (browsers/phones) associated with the persona.

paymentRiskResponse.persona.uniqueEmails

Number of unique email addresses associated with the persona.

paymentRiskResponse.address.billing

The properties of the address the order was billed to.

paymentRiskResponse.address.billing.line1

The first line of the billing address. For example, "5813-5849 Quail Meadows Dr".

paymentRiskResponse.address.billing.line2

The first line of the billing address. For example, "Suite 256”.

paymentRiskResponse.address.billing.city

The city of the billing address. For example, "Poplar Bluff".

paymentRiskResponse.address.billing.state

The state or province of the billing address. For example, “CO”.

paymentRiskResponse.address.billing.postalCode

The postal code of the billing address. For example, "63901-0000".

paymentRiskResponse.address.billing.countryCode

The country code of the billing address in the ISO-3166 format. For example, "US".

paymentRiskResponse.address.shipping

The properties of the address the order was shipped to.

paymentRiskResponse.address.shipping.line1

The first line of the shipping address. For example, "5813-5849 Quail Meadows Dr".

paymentRiskResponse.address.shipping.line2

The second line of the shipping address. For example, "Suite 256”.

paymentRiskResponse.address.shipping.city

The city of the shipping address. For example, "Poplar Bluff".

paymentRiskResponse.address.shipping.state

The state or province of the shipping address. For example, “CO”.

paymentRiskResponse.address.shipping.postalCode

The postal code of the shipping address. For example,  "63901-0000".

paymentRiskResponse.address.shipping.countryCode

The country code of the shipping address in the ISO-3166 format. For example, "US".

paymentRiskResponse.payment

The properties of the payment that was submitted with the transaction.

paymentRiskResponse.payment.currency

The three letter ISO-4217 currency code of the currency used to purchase the order. Defaults to “USD” if a value is not provided.

paymentRiskResponse.payment.cvvr

The Card Verification Value response returned to the merchant from the payment processor. The following values are expected:


Match = “M”

No Match = “N”

Unsupported or Unavailable = “X”

paymentRiskResponse.payment.paymentType

The Payment Type submitted by merchant given as one value from an enumeration of the following possible values:


“APAY” - Apple Pay

“CARD” - Credit Card

“PYPL” - PayPal

“CHEK” - Check

“NONE” - None

“TOKEN” - Token provided from payment processor

“GDMP” - Green Dot Money Pack

“GOOG” - Google Checkout

“BLML” - Bill Me Later

“GIFT” - Gift Card

“BPAY” - BPAY

“NETELLER” - Neteller

“GIROPAY” - GiroPay

“ELV” - ELV

“MERCADE_PAGO” - Mercade Pago

“SEPA” - Single Euro Payments Area

“INTERAC” - Interac

“CARTE_BLEUE” - Carte Bleue

“POLI” - POLi

“SKRILL” - Skrill/Moneybookers

“SOFORT” - Sofort

“AMZN” - Amazon Pay

“SAMPAY” - Samsung Pay

“ALIPAY” - AliPay

“WCPAY” - WeChat Pay

“CRYPTO” - Crypto Payments

“KLARNA” - Klarna

“AFTRPAY” - Afterpay

“AFFIRM” - Affirm

“SPLIT” - Splitit

“FBPAY” - Facebook Pay

paymentRiskResponse.payment.total

The total amount in currency submitted in the lowest currency factor. For example, the lowest currency in USD is pennies, so $1.00 would have the value of “100”. The total must be a natural number, which includes “0”.

paymentRiskResponse.payment.cardBrand

The credit card brand used in the transaction as determined by the BIN. For example, “MASTERCARD”.

paymentRiskResponse.device

The properties collected from the device (browser, phone/app) that the end user used to place the order.

paymentRiskResponse.device.deviceId

The unique identifier that was generated by Kount for the device.

paymentRiskResponse.device.deviceTime

The date/time when the device collection began. Supported date/time format is ISO 8601. For example, “2021-03-02T19:01:37Z”.

paymentRiskResponse.device.browserAttributes

The properties of the browser that was used (if any) that the end user used to place the order.

paymentRiskResponse.device.browserAttributes.browser

The name and the version number of the browser that was used (if any) that the end user used to place the order. For example, "Chrome 106.0.0.0".

paymentRiskResponse.device.browserAttributes.browserLanguage

The language that the browser had set at the time the order was placed. For example, "en-US".

paymentRiskResponse.device.deviceAttributes

The properties of the device hardware/software that the end user used to place the order.

paymentRiskResponse.device.deviceAttributes.os

The operating system that was running on the device when the order was placed. For example, "Android 9.0.0".

paymentRiskResponse.device.deviceAttributes.deviceResolution

The screen resolution of the device when the order was placed. For example, "1440x3440".

paymentRiskResponse.device.deviceAttributes.firstSeen

The date/time when this device was first seen in the Kount 360 network. Useful to understand whether this is a device with a long history. Supported date/time format is ISO 8601. For example, “2021-03-02T19:01:37Z”.

paymentRiskResponse.device.deviceAttributes.language

The language that the operating system had set at the time the order was placed. For example, "en-US".

paymentRiskResponse.device.deviceAttributes.currentOffset

The offset for the device local time zone when compared to GMT (in minutes).

paymentRiskResponse.device.deviceAttributes.mobileAttributes

The properties of the mobile device that was used by the end user to perform the order.

paymentRiskResponse.device.deviceAttributes.mobileAttributes.deviceLanguage

The language that the native mobile operating system had set at the time the order was placed. For example, "en-US".

paymentRiskResponse.device.deviceAttributes.mobileAttributes.deviceType

Which Kount SDK was used during the collection process, either iOS or Android. For example, "Android App SDK".

paymentRiskResponse.device.deviceLocation

The location that the device collector reported the device was located when the order was placed.

paymentRiskResponse.device.deviceLocation.areaCode

A string containing the three-digit US Area Code of the device during collection (based on an IP address match from Neustar).

paymentRiskResponse.device.deviceLocation.city

The name of the city where the device was reportedly located when the order was placed.

paymentRiskResponse.device.deviceLocation.country

The name of the country where the device was reportedly located when the order was placed. 

paymentRiskResponse.device.deviceLocation.countryCode

The country code where the device was reportedly located when the order was placed in the ISO-3166 format.

paymentRiskResponse.device.deviceLocation.latitude

A floating point number of the latitude where the device was reportedly located when the order was placed.

paymentRiskResponse.device.deviceLocation.longitude

A floating point number of the longitude where the device was reportedly located when the order was placed.

paymentRiskResponse.device.deviceLocation.postalCode

A string containing the postal code where the device was reportedly located when the order was placed.

paymentRiskResponse.device.deviceLocation.stateProvince

The name of the state or province where the device was reportedly located when the order was placed.

paymentRiskResponse.device.deviceLocation.stateProvinceCode

The short code for the state or province where the device was reportedly located when the order was placed. For example, “ID”.

paymentRiskResponse.device.ipMasks

A data collection that contains information about 2whether a proxy was used by the device during the collection.

paymentRiskResponse.device.ipMasks.proxy

A boolean indicating whether Kount has determined whether this connection was most likely made through a proxy rather than a direct connection.

paymentRiskResponse.device.ipMasks.tor

A boolean indicating whether the IP address is listed as a Tor node.

paymentRiskResponse.policySetExecuted

The properties of all of the policies and triggers that were evaluated and passed during the evaluation of the transaction.

paymentRiskResponse.policySetExecuted.policySetId

The unique ID of the policy set that was executed during transaction evaluation. For example,  "62dcb41e-3be6-4c20-a3a1-614837a870a3".

paymentRiskResponse.policySetExecuted.policySetName

The name of the policy set that was executed during transaction evaluation.

paymentRiskResponse.policySetExecuted.triggerId

The unique ID of the trigger that was executed during transaction evaluation. For example, "f28eb8fc-3e71-41ae-a02f-a095046aa682".

paymentRiskResponse.policySetExecuted.triggerName

The name of the trigger that was executed during transaction evaluation.

paymentRiskResponse.policySetExecuted.triggerPriority

An integer representing the priority of the trigger in the policy set that was executed during transaction evaluation, where 1 is the top priority trigger.

paymentRiskResponse.policySetExecuted.policiesExecuted[]

An array containing the policies that were executed during the transaction evaluation.

paymentRiskResponse.policySetExecuted.policiesExecuted[].policyId

The unique ID of the policy. For example, "f4ce5e65-a7c7-4cbb-a7bc-c104df90cbea".

paymentRiskResponse.policySetExecuted.policiesExecuted[].policyName

The name of the policy.

paymentRiskResponse.policySetExecuted.policiesExecuted[].policyOutcome

An object containing the type of an outcome that occurred on a policy and the value of the outcome for that type of outcome.

paymentRiskResponse.policySetExecuted.policiesExecuted[].policyOutcome.type

The type of the outcome. For example, "guidance".

paymentRiskResponse.policySetExecuted.policiesExecuted[].policyOutcome.value

The value of the outcome. For example, "decline".

Payment Authorization Update

A merchant can update fields such as the status of payment authorization. This is done by using the /events endpoint to send the updated transaction event.

After the update is made, the new values are reflected in the transaction in the Kount 360 Portal. The transaction is not re-evaluated and does not count toward the number of transactions purchased.

When implementing a pre-authorization workflow, making the /events update is required to keep complete and accurate data on the transaction. For more information on pre-authorization workflows, refer to the Ecommerce Fraud Server-Side Integration Sequence section.

Specifications

The Events endpoint is a RESTful HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to the Step 3: Authentication for how to acquire the bearer token.

Endpoints

  • Sandbox: https://api-sandbox.kount.com/events
  • Production: https://api.kount.com/events

Method: POST
Header Authorization: Bearer <token>
Header Content-Type: application/json
Body: Refer to the table below.

Reference

Request Parameters and Data Submission

Request Parameters and Data Submission table

Body Property

Description

paymentAuth

An object containing the properties that can be updated to a payment transaction after an authorization has occurred from the payment provider.

paymentAuth.clientId

Kount's unique identifier for a Client. Generated from within the Kount 360 portal.

paymentAuth.transactionId

The Kount-generated unique identifier of the transaction. For example, "d121ea2210434ffc8a90daff9cc97e76".

paymentAuth.timestamp

The date/time when the transaction was performed. Supported date/time format is ISO 8601 For example, “2021-03-02T19:01:37Z”.

paymentAuth.authorizationResult

The payment provider’s authorization result, as one value of the following enumerated values: "Unknown", "Approved" or "Declined".

paymentAuth.verificationResponse

An object containing the properties of the payment provider’s verification responses.

paymentAuth.verificationResponse.address

The payment provider’s verification result against the provided address, as one value of the following enumerated values: "Unknown", "Match" or "NoMatch".

paymentAuth.verificationResponse.postalCode

The payment provider’s verification result against the provided postal code, as one value of the following enumerated values: "Unknown", "Match" or "NoMatch".

paymentAuth.verificationResponse.cvv

The payment provider’s verification result against the provided Card Verification Value (CVV), as one value of the following enumerated values: "Unknown", "Match" or "NoMatch".

paymentAuth.paymentCredentials

An object containing the properties of the payment credentials, such as tokens used by digital payment methods.

paymentAuth.paymentCredentials.type

The type of payment used, such as specifying a digital payment method. For example, “SEPA”.

paymentAuth.paymentCredentials.token

The token used in the transaction as the credentials for the payment method. For example, “4pwmr0z2fh8qrt2isjdvkujow0”.

Response

Since no evaluation is performed, the response body only contains a correlation ID and error codes (if applicable). Please see the reference documentation for details.

Frequently Asked Questions

Are there other additional examples for authenticating as shown in Step 2?

Bash

    #!/usr/bin/env bash
    
    API='https://api-sandbox.kount.com'
    ISSUER='https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
    CLIENT_ID='<Your client ID here!>'
    CREDS='<Your client credentials here!>'
    
    # Get our token (it is valid for 20 minutes)
    RESPONSE=$(curl -s -X POST "${ISSUER}/v1/token?grant_type=client_credentials&scope=k1_integration_api" -H "Authorization: Basic ${CREDS}" -H "Content-Type: application/x-www-form-urlencoded")
    TOKEN=$(echo $RESPONSE | jq -r .access_token)
    
    # Make our evaluation request
    RESPONSE=$(curl -s -X POST ${API}/identity/v1/evaluate -H "Authorization: Bearer ${TOKEN}" \
    -d '{"clientId": "${CLIENT_ID}", "payment":{"paymentType": "CARD", "paymentToken": "4111111111111111", "bin": "414709"}}')
    echo $RESPONSE | jq
    

TypeScript

    const axios = require('axios')
    
    const API = 'https://api-sandbox.kount.com'
    const ISSUER = 'https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
    const CLIENT_ID = '<Your client ID here!>'
    const CREDS = '<Your client credentials here!>'
    
    async function getBearerToken() {
    
    const auth = await axios({
    url: `${ISSUER}/v1/token`,
    method: 'post',
    headers: {
    authorization: `Basic ${CREDS}`
    },
params: { grant_type: 'client_credentials', scope: 'k1_integration_api' } }) return auth.data.access_token } async function evaluateIdentity(token: string) { const resp = await axios({ url: `${API}/identity/v1/evaluate`, method: 'post', headers: { authorization: `Bearer ${token}`, }, data: { clientId: CLIENT_ID, payment: { paymentType: 'CARD', paymentToken: '4111111111111111', bin: '414709', }, } }) return resp.data } const main = async () => { const token = await getBearerToken(); const resp = await evaluateIdentity(token); console.log(JSON.stringify(resp, null, 4)) } main()

Go

    package main
    import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    )
    
    type config struct {
    API string
    Issuer string
    ClientId string
    Creds 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 IdentityEvalReq, token string) string {
    
    j, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest(http.MethodPost, api+"/identity/v1/evaluate", 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 IdentityEvalReq struct {
    ClientId string `json:"clientId"`
    Payment IdentityEvalPaymentReq `json:"payment"`
    }
    
    type IdentityEvalPaymentReq struct {
    PaymentType string `json:"paymentType"`
    PaymentToken string `json:"paymentToken"`
    BIN string `json:"bin"`
    }
    
    func main() {
    config := config{
    API: "https://api-sandbox.kount.com",
    Issuer: "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357",
    ClientId: "<Your client ID here!>",
    Creds: "<Your client credentials here!>",
    }
    client := &http.Client{}
    token := getToken(client, config.Issuer, config.Creds)
    
    payload := IdentityEvalReq{
    ClientId: config.ClientId,
    Payment: IdentityEvalPaymentReq{
    PaymentType: "CARD",
    PaymentToken: "4111111111111111",
    BIN: "414709",
    },
    }
    
    resp := evaluate(client, config.API, payload, token)
    fmt.Printf( "%s", resp)
    }
    
Was this article helpful?
0 out of 0 found this helpful