Kount 360 Integration API Reference

This document provides detailed API reference information for all endpoints exposed by the Kount Fraud Evaluation Integration.

Overview

The Kount Fraud Evaluation Integration exposes two main endpoints:

Risk Evaluation API - Synchronous endpoint for fraud risk assessment
Order Fulfillment Webhook - Asynchronous webhook handler for order status updates

All endpoints return JSON responses and use standard HTTP status codes for error handling.

Base URLs

Integration endpoints are region-specific:

US East: https://hooks.us-east-2.elasticpathintegrations.com
EU West: https://hooks.eu-west-1.elasticpathintegrations.com

Important: Actual endpoint URLs include encoded flow configuration IDs that are generated during integration deployment. Obtain the complete URLs from your Prismatic integration instance.

Authentication

API Key Authentication

The Risk Evaluation Flow should be secured with an API key generated during instance configuration.

Header: x-api-key: {your_api_key}

Webhook Authentication

Webhook endpoints, such as the Order Fulfillment Flow use EPCC's standard webhook authentication. The following security header is automatically sent by Elastic Path Commerce Cloud when it invokes the configured webhook.

Header: x-moltin-secret-key: {webhook_secret}

The webhook secret is configured during integration setup and must match the value configured in EPCC. The integration attempts to configure this secret automatically during integration instance creation.

Risk Evaluation API

Endpoint

POST /trigger/{flowId}

Type: Synchronous Format: JSON

Purpose

Evaluates fraud risk for an EPCC cart before checkout completion. This endpoint:

Retrieves cart data from EPCC
Transforms cart to Kount order format
Sends order to Kount for risk evaluation
Stores Kount order ID in EPCC cart custom attributes
Returns risk decision and score

Request Format

Headers

Content-Type: application/json
x-api-key: {your_api_key}

Request Body

{
  "cartId": "d121ea2210434ffc8a90daff9cc97e76",
  "orderNumber": "ORD-2024-001234",
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "New York",
    "region": "NY",
    "postalCode": "10001",
    "countryCode": "US",
    "phoneNumber": "+1-555-123-4567"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "line1": "456 Oak Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10002",
    "countryCode": "US",
    "phoneNumber": "+1-555-123-4567"
  },
  "deviceSessionId": "abc123def456ghi789jkl",
  "userIp": "192.168.1.100",
  "customFields": {
    "merchantId": "12345",
    "campaignId": "summer2024"
  },
  "riskInquiry": true,
  "channelIdentifier": "WEB",
  "fulfillmentType": "SHIPPED"
}

Required Fields

Field	Type	Description
`cartId`	string	EPCC cart identifier
`orderNumber`	string	Merchant order number (used as Kount merchant order ID)
`billingAddress`	object	Customer billing address
`userIp`	string	Customer IP address (IPv4 format)

Optional Fields

Field	Type	Description	Default
`shippingAddress`	object	Shipping address (uses cart shipping groups if not provided)	From cart
`deviceSessionId`	string	Kount device session identifier	null
`customFields`	object	Additional merchant-specific data
`riskInquiry`	boolean	Enable immediate risk evaluation	Configuration default
`channelIdentifier`	string	Channel identifier for order classification	Configuration default
`fulfillmentType`	string	Fulfillment method	Configuration default

Address Object Format

{
  "firstName": "John",
  "lastName": "Doe",
  "company": "Acme Corp",
  "line1": "123 Main Street",
  "line2": "Apt 4B",
  "city": "New York",
  "region": "NY",
  "postalCode": "10001",
  "countryCode": "US",
  "phoneNumber": "+1-555-123-4567"
}

Response Format

Success Response (200 OK)

{
  "decision": "APPROVE",
  "score": 85.5,
  "kountOrderId": "B2C3D4F6G7H8J10K",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "processingTimeMs": 1250,
  "fallback": false
}

Response Fields

Field	Type	Description
`decision`	string	Risk decision: `APPROVE`, `DECLINE`, or `REVIEW`
`score`	number	Risk score (0-100, higher = safer)
`kountOrderId`	string	Kount order identifier for tracking
`correlationId`	string	Request correlation ID for debugging
`processingTimeMs`	integer	Processing time in milliseconds
`fallback`	boolean	Whether fallback decision was used
`fallbackReason`	string	Reason for fallback (if applicable)

Error Responses

Validation Error (200)

{
  "name": "IntegrationError",
  "code": "VALIDATION_ERROR",
  "correlationId": "",
  "timestamp": "2025-08-26T20:11:48.187Z"
}

Cart Empty (200)

{
  "name": "IntegrationError",
  "code": "INTERNAL_ERROR",
  "correlationId": "kount-1756239042367-65b3f15f-d5b0-4c70-b223-b5a318036e2c",
  "timestamp": "2025-08-26T20:10:43.155Z",
  "details": "risk_evaluation_failed",
  "originalError": {
    "code": "CART_EMPTY"
  }
}

Internal Server Error (200)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal processing error occurred",
    "correlationId": "kount-20241201-123456-uuid",
    "timestamp": "2024-12-01T10:30:00Z"
  }
}

Order Fulfillment Webhook

Endpoint

POST /webhook/order-fulfilled

Type: Asynchronous Format: JSON Security: EPCC webhook secret validation

Purpose

Processes EPCC order.fulfilled webhook events and updates Kount with order fulfillment status. This webhook:

Validates EPCC webhook authentication
Extracts order fulfillment information
Updates Kount with fulfillment status
Returns processing confirmation

Request Format

Headers

Content-Type: application/json
x-moltin-secret-key: {webhook_secret}

Request Body

EPCC automatically sends webhook payloads in the following format:

{
  "id": "1cb8697d-d13a-4cda-94e2-5b1881c877cd",
  "triggered_by": "order.fulfilled",
  "attempt": 1,
  "integration": {
    "id": "a13b32fd-cb8c-4adf-9f71-de830b8d777a",
    "integration_type": "webhook",
    "name": "Kount Fraud Detection"
  },
  "payload": {
    "data": {
      "id": "45936d34-7ce7-48fd-9673-eae9b434dd5e",
      "type": "order",
      "status": "complete",
      "payment": "paid",
      "shipping": "fulfilled",
      "order_number": "ORD-2024-001234",
      "shipping_tracking_number": "1Z999999999999999",
      "shipping_tracking_url": "https://tracking.example.com/1Z999999999999999",
      "custom_attributes": {
        "kountOrderId": {
          "type": "string",
          "value": "B2C3D4F6G7H8J10K"
        }
      },
      "meta": {
        "timestamps": {
          "created_at": "2024-12-01T10:00:00Z",
          "updated_at": "2024-12-01T11:00:00Z"
        }
      }
    }
  }
}

Response Format

NOTE: This is an asynchronous flow which always replies with an HTTP 200 code and an execution id that can be used to monitor or lookup the final results. The following error messages would be visible in logs for the execution flow.

Success Response

{
  "status": "success",
  "message": "Order fulfillment status updated successfully",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-12-01T10:30:00Z",
  "processingTimeMs": 450,
  "kountOrderId": "B2C3D4F6G7H8J10K"
}

Error Responses

Invalid Webhook Secret (401 Unauthorized)

{
  "code": "INVALID_WEBHOOK_SECRET",
  "message": "Webhook authentication failed",
  "correlationId": "kount-20241201-123456-uuid",
  "timestamp": "2024-12-01T10:30:00Z"
}

Validation Error (400 Bad Request)

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid webhook payload structure",
  "details": "Missing required field: payload.data.id",
  "correlationId": "kount-20241201-123456-uuid",
  "timestamp": "2024-12-01T10:30:00Z"
}

Error Handling

Error Code Reference

Code	Description	HTTP Status	Recommended Action
`VALIDATION_ERROR`	Request validation failed	400	Fix request format/data
`CART_EMPTY`	EPCC cart not found	404	Verify cart ID exists
`KOUNT_API_ERROR`	Kount service error	500	Retry request, check Kount status
`EPCC_API_ERROR`	EPCC service error	500	Retry request, check EPCC status
`NETWORK_ERROR`	Network connectivity issue	500	Retry with backoff
`INTERNAL_ERROR`	Internal processing error	500	Contact support with correlation ID
`INVALID_WEBHOOK_SECRET`	Webhook authentication failed	401	Verify webhook secret configuration
`KOUNT_ORDER_NOT_FOUND`	Kount order not found	404	Verify Kount order exists

Error Response Format

All errors follow a consistent format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": "Additional error context (optional)",
  "correlationId": "UUID for tracking",
  "timestamp": "ISO 8601 timestamp"
}

Kount Retry Guidelines

Rate Limit Errors: 429 response code triggers a retry with exponential backoff with configurable delay and attempts

SDK Examples

JavaScript/Node.js

Risk Evaluation Request

const axios = require('axios');

const evaluateRisk = async (cartData) => {
  try {
    const response = await axios.post(
      'https://hooks.us-east-2.elasticpathintegrations.com/trigger/YOUR_FLOW_ID',
      {
        cartId: cartData.cartId,
        orderNumber: cartData.orderNumber,
        billingAddress: cartData.billingAddress,
        shippingAddress: cartData.shippingAddress,
        userIp: cartData.userIp,
        deviceSessionId: cartData.deviceSessionId,
        riskInquiry: true
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.PRISMATIC_API_KEY}`
        },
        timeout: 10000
      }
    );

    return response.data;
  } catch (error) {
    console.error('Risk evaluation failed:', error.response?.data || error.message);
    throw error;
  }
};

// Example usage
const cartData = {
  cartId: 'd121ea2210434ffc8a90daff9cc97e76',
  orderNumber: 'ORD-2024-001234',
  billingAddress: {
    firstName: 'John',
    lastName: 'Doe',
    line1: '123 Main Street',
    city: 'New York',
    region: 'NY',
    postalCode: '10001',
    countryCode: 'US'
  },
  shippingAddress: {
    firstName: 'John',
    lastName: 'Doe',
    line1: '456 Oak Avenue',
    city: 'New York',
    region: 'NY',
    postalCode: '10002',
    countryCode: 'US'
  },
  userIp: '192.168.1.100',
  deviceSessionId: 'abc123def456'
};

evaluateRisk(cartData)
  .then(result => {
    console.log('Risk Decision:', result.decision);
    console.log('Risk Score:', result.score);
    console.log('Kount Order ID:', result.kountOrderId);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Python

Risk Evaluation Request

import requests
import json
from typing import Dict, Any

def evaluate_risk(cart_data: Dict[str, Any], api_key: str, flow_id: str) -> Dict[str, Any]:
    """
    Evaluate fraud risk for a cart using the Kount integration.
    
    Args:
        cart_data: Cart and customer information
        api_key: Prismatic API key
        flow_id: Integration flow ID
    
    Returns:
        Risk evaluation response
    """
    url = f"https://hooks.us-east-2.elasticpathintegrations.com/trigger/{flow_id}"
    
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {api_key}'
    }
    
    payload = {
        'cartId': cart_data['cart_id'],
        'orderNumber': cart_data['order_number'],
        'billingAddress': cart_data['billing_address'],
        'shippingAddress': cart_data.get('shipping_address'),
        'userIp': cart_data['user_ip'],
        'deviceSessionId': cart_data.get('device_session_id'),
        'riskInquiry': True
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=30)
        response.raise_for_status()
        return response.json()
    
    except requests.exceptions.RequestException as e:
        print(f"Risk evaluation failed: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Error details: {e.response.json()}")
        raise

# Example usage
cart_data = {
    'cart_id': 'd121ea2210434ffc8a90daff9cc97e76',
    'order_number': 'ORD-2024-001234',
    'billing_address': {
        'firstName': 'John',
        'lastName': 'Doe',
        'line1': '123 Main Street',
        'city': 'New York',
        'region': 'NY',
        'postalCode': '10001',
        'countryCode': 'US'
    },
    'user_ip': '192.168.1.100',
    'device_session_id': 'abc123def456'
}

try:
    result = evaluate_risk(cart_data, 'your_api_key', 'your_flow_id')
    print(f"Risk Decision: {result['decision']}")
    print(f"Risk Score: {result['score']}")
    print(f"Kount Order ID: {result['kountOrderId']}")
except Exception as e:
    print(f"Error: {e}")

cURL

Risk Evaluation Request

curl -X POST \
  https://hooks.us-east-2.elasticpathintegrations.com/trigger/YOUR_FLOW_ID \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "cartId": "d121ea2210434ffc8a90daff9cc97e76",
    "orderNumber": "ORD-2024-001234",
    "billingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "line1": "123 Main Street",
      "city": "New York",
      "region": "NY",
      "postalCode": "10001",
      "countryCode": "US"
    },
    "userIp": "192.168.1.100",
    "deviceSessionId": "abc123def456",
    "riskInquiry": true
  }'

Integration Patterns

Error Handling with Fallback

const evaluateRiskWithFallback = async (cartData) => {
  try {
    const result = await evaluateRisk(cartData);
    
    // Check if fallback decision was used
    if (result.fallback) {
      console.warn(`Fallback decision used: ${result.fallbackReason}`);
      // Implement additional logging or monitoring
    }
    
    return result;
  } catch (error) {
    // Implement fallback logic for critical errors
    if (response?.code) {
      console.error('Service unavailable, using local fallback');
      return {
        decision: 'REVIEW', // Safe default
        score: 0,
        kountOrderId: null,
        fallback: true,
        fallbackReason: 'Service unavailable'
      };
    }
    
    throw error;
  }
};

OpenAPI Specifications

Complete OpenAPI specifications are available:

Risk Evaluation API: OpenAPI Specification YAML
Order Fulfillment Webhook: OpenAPI Specification YAML

These specifications can be used with API development tools like Postman, Insomnia, or Swagger UI for testing and integration development.

Overview​

Base URLs​

Authentication​

API Key Authentication​

Webhook Authentication​

Risk Evaluation API​

Endpoint​

Purpose​

Request Format​

Headers​

Request Body​

Required Fields​

Optional Fields​

Address Object Format​

Response Format​

Success Response (200 OK)​

Response Fields​

Error Responses​

Validation Error (200)​

Cart Empty (200)​

Internal Server Error (200)​

Order Fulfillment Webhook​

Endpoint​

Purpose​

Request Format​

Headers​

Request Body​

Response Format​

Success Response​

Error Responses​

Invalid Webhook Secret (401 Unauthorized)​

Validation Error (400 Bad Request)​

Error Handling​

Error Code Reference​

Error Response Format​

Kount Retry Guidelines​

SDK Examples​

JavaScript/Node.js​

Risk Evaluation Request​

Python​

Risk Evaluation Request​

cURL​

Risk Evaluation Request​

Integration Patterns​

Error Handling with Fallback​

OpenAPI Specifications​

Overview

Base URLs

Authentication

API Key Authentication

Webhook Authentication

Risk Evaluation API

Endpoint

Purpose

Request Format

Headers

Request Body

Required Fields

Optional Fields

Address Object Format

Response Format

Success Response (200 OK)

Response Fields

Error Responses

Validation Error (200)

Cart Empty (200)

Internal Server Error (200)

Order Fulfillment Webhook

Endpoint

Purpose

Request Format

Headers

Request Body

Response Format

Success Response

Error Responses

Invalid Webhook Secret (401 Unauthorized)

Validation Error (400 Bad Request)

Error Handling

Error Code Reference

Error Response Format

Kount Retry Guidelines

SDK Examples

JavaScript/Node.js

Risk Evaluation Request

Python

Risk Evaluation Request

cURL

Risk Evaluation Request

Integration Patterns

Error Handling with Fallback

OpenAPI Specifications