Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt

Use this file to discover all available pages before exploring further.

An Order Validator is a Kibo platform capability that intercepts an order after submission and routes it to an external service for validation. The most common use case is fraud detection, but the capability contract is generic enough to support any order-level validation logic. Kibo provides two supported, pre-built Order Validator applications — Kount and CyberSource Decision Manager — and also supports custom validator implementations via any externally hosted REST endpoint or Kibo API Extension function.

​
How Order Validation Works

When an order is submitted, Kibo calls every registered Order Validator capability for the site, collects the result, and uses the returned status to determine the order’s next state. The OrderValidator capability type is scoped per-site and uses MultiplePerSite mode, meaning more than one Order Validator may be registered per site simultaneously. Validators can be integrated via an external REST endpoint or a Kibo API Extension function. If no Order Validator capability is registered for a site, the platform automatically treats the order as Pass and proceeds to fulfillment without calling any external service. If Kibo cannot reach your validator endpoint (network error, timeout, etc.), the platform defaults the result to Fail and the order goes to PendingReview.

​
Validator Types

The validatorType field on an OrderValidationResult identifies the category of validation being performed.
ValueDescription
"Fraud"Indicates that the result is from a fraud-detection service
"Fraud" is the only formally defined constant in the platform. The validatorType field is a free-form string, so custom implementations may use other values for internal tracking purposes, but the platform does not apply any special routing behavior based on custom type values.

​
Validator Statuses

The status field on the OrderValidationResult determines what happens to the order after validation. Four statuses are recognized:
StatusString ValueOrder State Effect
Pass"Pass"Order proceeds to Validated, then moves toward fulfillment (Accepted / PendingShipment)
Review"Review"Order is placed into PendingReview — a human agent must manually accept or cancel
Fail"Fail"Order is placed into PendingReview — requires manual intervention
Error"Error"Order is placed into PendingReview — validator encountered an error condition

​
Order State Flow

​
Add Order Validator

Follow the below steps to add an order validator:
  1. In Dev Center, navigate to Develop > Applications > Packages > Capabilities.
  2. Click Add Capability.
  3. Search for Order Validator in the Add Capability modal and click Ok. Add Capability modal with capabilities suggestions
  4. Add a URL for a web service that you host externally, or an API Extension function if you want it hosted in Kibo. Order Validator modal for external URL with save button at bottom.
The URL is a REST endpoint that accepts the full Order object via POST and returns an OrderValidationResult response.

​
OrderValidationResult Schema

Your validator endpoint must return an OrderValidationResult JSON object. The validationId and createdDate fields are required — requests missing either will be rejected by the platform. 
{
  "validationId": "string",        // REQUIRED — unique ID for this validation attempt (set by your service)
  "validatorName": "string",       // Friendly name of your validator
  "validatorType": "string",       // The type of validation — "Fraud" is the only formally defined value
  "status": "string",              // "Pass", "Review", "Fail", or "Error"
  "createdDate": "2024-01-01T00:00:00.000Z",  // REQUIRED — ISO 8601 UTC timestamp
  "messages": [
    {
      "orderItemId": "string",     // Optional — links the message to a specific line item
      "messageType": "string",     // Classification of the message
      "message": "string"          // Human-readable message content
    }
  ]
}

​
API Endpoints

Add a validation result (for async validators that review orders after the fact): PUT /api/commerce/orders/{orderId}/validationresults — API reference Get validation results for an order: GET /api/commerce/orders/{orderId}/validationresults — API reference

​
Building a Custom Validator

If you want to implement your own order validator rather than using a pre-built integration, follow this pattern.

​
Step 1 — Create your endpoint

Your service must expose a POST endpoint that:
  • Accepts the full Kibo Order object in the request body (JSON)
  • Returns an OrderValidationResult JSON object
  • Responds with an HTTP 2xx status code on success

​
Step 2 — Register the capability in Dev Center

Register your endpoint URL as the ValidateOrder operation URL on an Order Validator capability (see Add Order Validator above).

​
Step 3 — Return a valid result

Your response must always include validationId, createdDate, and status. The status value drives order routing (see Validator Statuses above). Example — Pass: 
{
  "validationId": "txn-20240601-001",
  "validatorName": "Acme Fraud Check",
  "validatorType": "Fraud",
  "status": "Pass",
  "createdDate": "2024-06-01T12:00:00.000Z",
  "messages": []
}
Example — Review with messages: 
{
  "validationId": "txn-20240601-002",
  "validatorName": "Acme Fraud Check",
  "validatorType": "Fraud",
  "status": "Review",
  "createdDate": "2024-06-01T12:00:01.000Z",
  "messages": [
    {
      "messageType": "RiskFlag",
      "message": "IP address does not match billing country"
    },
    {
      "orderItemId": "item-abc",
      "messageType": "HighValue",
      "message": "Line item value exceeds threshold"
    }
  ]
}

​
Pre-Built Validator Integrations

​
Kount

Kount is a fraud detection service that:
  • Automatically sends submitted order data to Kount for screening (browser type, IP, device, billing info, etc.)
  • Calculates a fraud score using your configured Kount rules
  • Returns one of four Kount statuses: Accept (A), Decline (D), Review (R), Escalate (E)
  • Maps results back to Kibo order status (Accepted, PendingReview, or Cancelled)
  • Supports a monetary threshold below which orders are not screened
  • Supports the Kount Event Notification System (ENS) to sync status changes from Kount back to Kibo in near real-time

​
CyberSource Decision Manager

CyberSource Decision Manager is a fraud protection platform that:
  • Automatically sends submitted order data to Decision Manager for screening
  • Applies your configured Decision Manager rules to produce a fraud score and validation result (accept, review, or reject)
  • Maps results back to Kibo order status (Accepted, PendingReview, or Cancelled)
  • Supports scheduled order synchronization to pull status updates from Decision Manager back into Kibo
  • Supports combined authorization and fraud validation in a single call
  • Supports a monetary threshold below which orders are not screened

​
Platform Capability Type Reference

OrderValidator is one of four publicly available capability types the Kibo platform supports. For the full reference, see Application Capabilities.