docs

Risk Assessment

Risk Check

Implement a custom risk assessment service

The risk check feature is meant to be used in combination with the Rule Engine. Your risk assessment results will be made available on the order and customer models, so that you can configure the Rule Engine to deny certain or even all payment methods depending on your own custom rule sets.

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

Once you have configured the API Credentials for this service and SCAYLE activated the feature, checkout will execute calls to the given endpoint. The response of those calls will be stored as the customData.score property on the order object.

Risk evaluation

SCAYLE supports the passive risk check approach:

  1. The customer has already provided a billing & shipping address, selected a delivery and shipping options and selected a payment method.
  2. The customer proceeds to close the order (after clicking on Buy now):
    • if the feedback is negative, the customer is redirected to the confirmation page, , leading to limited payment methods and notifying the customer to change the selected payment method
    • if the feedback is positive it redirects the customer to the order success page.

The Checkout will store the last risk check result for future interactions within the customer object.

How to implement

You need to provide a http service that can handle the usual load of your shop and which accepts requests from the SCAYLE networks.

If you want to limit incoming traffic by IP address, your SCAYLE Account Manager can provide more information about our networks.

This service needs to implement a POST endpoint according 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.

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
Previous
Rule Engine
Next up
Express Checkout