docs

Risk Assessment

Risk Check

The Risk Check feature allows you to integrate external fraud-prevention providers directly into the checkout process.

This enables automatic evaluation of an order’s risk level and the execution of predefined actions such as blocking confirmation, disabling payment methods, or displaying customer notifications.

SCAYLE will activate this feature for you on request. Please contact your SCAYLE Account Manager for further information.

Once API credentials are configured and the feature is activated, the checkout will send requests to your configured endpoint.

The provider’s response is stored in the order.customData.score property and can be referenced in the Rule Engine.

How it works

  1. The customer has provided billing and shipping addresses, selected delivery and shipping options, and chosen a payment method.
  2. When the customer proceeds to complete the order (by clicking Buy now):
    • A HTTP call is sent to your custom middleware containing the order data
    • The middleware returns a response, which is stored in order.custom_data
    • The Rule Engine applies rules from the automated_risk_assessment group
    • Rules can reference values returned in the risk check response
    • If no rule applies, the order will be confirmed successfully.
    • The checkout also stores the last risk check result within the customer object for use in future interactions.
  3. Based on the configured rule actions, the checkout can:
    • Reject the order
    • Disable one or more payment methods
    • Show a notification to the customer

How to implement the HTTP service

You must provide an HTTP service that can handle the expected traffic of your shop and accept incoming requests from the SCAYLE network.

If you intend to restrict access by IP address, please contact your SCAYLE Account Manager to obtain the list of SCAYLE network ranges.

The service must expose a POST endpoint that conforms to the following schema:

Request

Your endpoint needs to be able to serve the following request.

Authentication

Basic auth according to SCAYLE Panel configuration.

Headers

ParameterDetails
X-Shop-Id

Integer

The current shop-country id

Body

Request example
Request schema
  • id integer
  • address object (optional)
    • billing object
      • id integer
      • additional string ([!-ɏ0-9 ]) (optional)
      • city string ([!-ɏ0-9 ])
      • collectionPoint object (optional)
      • countryCode string (minimum length: ) (maximum length: 3)
      • houseNumber string ([!-ɏ0-9 ])
      • isDefault object
      • recipient object
      • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
      • street string ([!-ɏ0-9 ])
      • title string ([!-ɏ0-9 ]) (optional)
      • zipCode string ([A-z0-9\- ]{1,12})
    • forward object (optional)
      • additional string ([!-ɏ0-9 ]) (optional)
      • city string ([!-ɏ0-9 ]) (optional)
      • collectionPoint object (optional)
      • countryCode string (optional) (minimum length: ) (maximum length: 3)
      • houseNumber string ([!-ɏ0-9 ]) (optional)
      • recipient object (optional)
      • street string ([!-ɏ0-9 ]) (optional)
      • zipCode string ([A-z0-9\- ]{1,12}) (optional)
      • createdAt string (date-time validation) (optional)
      • updatedAt string (date-time validation) (optional)
    • shipping object
      • id integer
      • additional string ([!-ɏ0-9 ]) (optional)
      • city string ([!-ɏ0-9 ])
      • collectionPoint object (optional)
      • countryCode string (minimum length: ) (maximum length: 3)
      • houseNumber string ([!-ɏ0-9 ])
      • isDefault object
      • recipient object
      • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
      • street string ([!-ɏ0-9 ])
      • title string ([!-ɏ0-9 ]) (optional)
      • zipCode string ([A-z0-9\- ]{1,12})
  • basketKey string
  • campaignKey string (optional)
  • client **** (optional)
  • confirmedAt string (date-time validation) (optional)
  • cost object
    • withoutTax integer
    • withTax integer
  • currencyCode string (^([A-Z]{3})$)
  • customData object (optional) (object is extensible as desired)
  • customer object (optional)
    • id integer
    • authentication object (optional)
      • data object (optional)
      • type enum (facebook password)
    • birthDate string (^((19|20)[0-9]{2}\-[0-9]{2}\-[0-9]{2})$) (optional)
    • customData object (optional) (object is extensible as desired)
    • email string (email validation) (optional) (maximum length: 50)
    • firstName string ([!-ɏ0-9 ])
    • gender enum (m f d) (optional)
    • groups array (optional)
      • item string (^[0-9a-zA-Z\-\\_]*$) (optional) (minimum length: ) (maximum length: 60)
    • lastName string ([!-ɏ0-9 ])
    • phone string (00[0-9]{1,3}/[0-9]{1,20}) (optional)
    • publicKey string (^[0-9a-zA-Z\-\\_]*$) (optional) (minimum length: ) (maximum length: 100)
    • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
    • status object
      • isActive boolean
      • isGuestCustomer boolean
      • isTestCustomer boolean
    • title string ([!-ɏ0-9 ]) (optional) (minimum length: ) (maximum length: 100)
    • type enum (personal retail organization family) (optional)
    • createdAt string (date-time validation)
    • updatedAt string (date-time validation)
  • invoicedAt string (date-time validation) (optional)
  • items array (optional)
    • availableQuantity integer (optional)
    • customData object (optional) (object is extensible as desired)
    • deliveryForecast object (optional)
      • deliverable object
      • subsequentDelivery object
    • itemGroup **** (optional)
    • key string
    • packageId integer
    • price object
      • appliedReductions array (optional)
      • reference object (optional)
      • tax object (object is extensible as desired)
      • withoutTax integer
      • withTax integer
    • product object
      • id integer
      • advancedAttributes object (optional) (object is extensible as desired)
      • attributes object (optional) (object is extensible as desired)
      • categories array (optional)
      • definingAttributes array (optional)
      • images array
      • masterKey string (optional)
      • name string
      • createdAt string (date-time validation)
      • updatedAt string (date-time validation)
    • reservationKey string (optional)
    • status enum (available unavailable deliverable undeliverable cancelled)
    • variant object
      • id integer
      • advancedAttributes object (optional) (object is extensible as desired)
      • attributes object (optional) (object is extensible as desired)
      • referenceKey string (optional)
      • stock object (optional)
      • createdAt string (date-time validation)
      • updatedAt string (date-time validation)
    • warehouseId integer (optional)
    • createdAt string (date-time validation)
    • updatedAt string (date-time validation)
  • loyaltyCard object (optional)
    • cardNumber string
    • points integer
    • provider string ([A-Za-z])
  • packages array (optional)
    • id integer
    • carrierKey string
    • deliveryDate object
      • maximum string ([0-9]{4}\-[0-9]{2}\-[0-9]{2})
      • minimum string ([0-9]{4}\-[0-9]{2}\-[0-9]{2})
    • deliveryStatus enum (open shipment_pending delegation_pending shipment_completed cancellation_completed)
    • returnIdentCode null,string (optional)
    • shipmentKey string (optional)
    • tracking object (optional)
      • id string (optional) (minimum length: )
      • url string (uri validation) (optional)
  • payment array (optional)
    • amount integer (optional)
    • data object (optional) (object is extensible as desired)
    • installment array (optional)
      • amount integer (optional)
      • type enum (annualInterest firstInstallment installmentAddition paymentMethodCosts subsequentInstallments valutaAddition) (optional)
    • key string (optional)
    • options object (optional)
      • countOfInstallments integer (optional)
      • hasPaybreak boolean (optional)
    • transactionKey string (optional)
  • preferred object (optional)
    • carrierKey string (optional)
    • deliveryPolicy enum (least_packages highest_stocks fastest_shipping) (optional)
  • publicKey string (^[0-9a-zA-Z\-\\_]*$) (optional) (minimum length: ) (maximum length: 100)
  • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
  • shipping object (optional)
    • deliveredOn string ([0-9]{4}\-[0-9]{2}\-[0-9]{2}) (optional)
    • deliveryCosts integer (optional)
    • expressDeliveryCosts integer (optional)
    • policy string (^[0-9a-zA-Z\-\\_]*$) (minimum length: )
  • shop object (optional)
    • id integer
    • country string (^([A-Z]{3})$)
    • language string (^([a-z]{2})$)
  • status enum (order_open payment_pending payment_reserved invoice_completed cancellation_pending cancellation_completed invoice_partially_completed)
  • vouchers array (optional)
    • id integer
    • applicableItems array (optional)
      • isApplied boolean (optional)
      • key string (optional)
    • code string ([A-z0-9]{0,12})
    • type enum (absolute relative)
    • value number
  • createdAt string (date-time validation)
  • updatedAt string (date-time validation)

Response

Your service needs to follow this specification when handling the checkout request.

Response body

ParameterDetails
result

Any

enum,object,array,number,string

The response body will be written to the order.customData.score property. Additionally, you may define a custom value set and use this as a reference via the rule engine rules.

Response Examples

green/red based

value based

request failed

Properties:

  • result enum,object,array,number,string,… (optional)

Status Codes:

CodeDescriptionResponse Body
201request was successful
401authentication failedempty

Handling failed requests

In situations with high traffic or temporary service issues, your risk check provider (or your middleware) may fail to respond in time.

When this happens, the order object will not be updated — meaning either no new value is written, or the previously stored value remains available.

If the response is empty or does not return a 201 status code, the property order.customData.score will be set to failed.

Using the Rule Engine with Risk Assessment Results

After a risk assessment, the provider’s response is stored on the order object.

For example, if your risk evaluation is value-based and the customer receives a score of 0.7, the order will contain:

You can now create a rule in the Rule Engine that references this value and applies the appropriate action (e.g., block order confirmation, restrict certain payment methods, or trigger a notification).

Example: Reject Orders with High Risk Score

Let’s assume your fraud provider returns a risk score between 0.0 (no risk) and 1.0 (very high risk).

If you want to reject orders with a score of 0.7 or higher, you can set up the following rule:

Rule Configuration

  • General
    • Name: Reject high-risk orders
    • Description: Reject orders where the risk score is 0.7 or higher
  • Condition
    • Object: order
    • Attribute: customData.score
    • Operator: >=
    • Value: 0.7
  • Result
    • Action: Reject order
    • Optional: Display notification to customer (e.g., “Your order could not be processed.”)

Example: Restrict Payment Methods Based on Risk Score

You may prefer to allow the order but restrict risky payment methods.

For example: if score ≥ 0.5, disable Credit Card and PayPal.

  • Condition
    • Object: order
    • Attribute: customData.score
    • Operator: >=
    • Value: 0.5
  • Result
    • Action: Disable payment method
    • Methods: Credit Card, PayPal

You can always have multiple rules and actions in place if you want to combine them.

Previous
Order State Transition Overview
Next up
External Order Creation