Responses

Every API response is accompanied by a response body, the format of which depends on the type of endpoint you have used.

Types of Responses

When issuing a HTTP request to the Fraudio API, you may encounter the following types of responses:

• Successful responses: Any response in the 2xx range indicates a successful transaction.
• Redirects: You should never expect to see any response in the 3xx range from our APIs. These are only used to forward regular HTTP requests to HTTPS.
• Functional errors: Any response in the 4xx range indicates an intentional error from the API, such as an invalid token or an incorrectly formatted request body.
• Programming errors: Any response with a status code of 500 or 501 indicates an unintentional error from the API, such as a bug in the code.
• Network errors: Any response with a status code of 502, 503, or 504 indicates that the network layer, or the API itself, could not be reached, possibly due to a cloud outage.
• Timeouts: When no response is received by the client, it is classified as a timeout.

Please check the full list of HTTP status codes for more details.

200 OK - Payment Fraud Score Response

The request message to the Payment Fraud Score endpoint has been successfully processed. You will receive a 200 OK response.

200 OK response example - green recommendation

{
  "recommendation": "green",
  "score": 0,
  "notes": "Default values were used for the following missing fields: 'transactionip','responsecode','posentrymode','threedsused','channelsubtype'  (... 10 more)."
}

200 OK response example - yellow recommendation

{
  "recommendation": "yellow",
  "score": 0.54,
  "notes": "Default values were used for the following missing fields: 'transactionip','responsecode','posentrymode','threedsused','channelsubtype'  (... 10 more)."
}

200 OK response example - red recommendation

{
  "recommendation": "red",
  "score": 0.99,
  "notes": "Default values were used for the following missing fields: 'transactionip','responsecode','posentrymode','threedsused','channelsubtype'  (... 10 more)."
}

Properties

Name	Type	Required	Description
recommendation	string	true	The recommendation is an advised course of action. The recommendations will be either red, yellow, green, or unavailable. Recommendations are generated by starting with the default thresholds, and then optimising the model using your customised preferences that you specify during onboarding. The value 'unavailable' may be served during onboarding.
score	double	true	The score is a fraud score between 0 and 1, where the closer to 1, the higher the likelihood that the transaction is fraudulent. The value -1 may be served during onboarding.
notes	string	true	The notes consist of relevant information about the transaction that was sent.

200 OK - Payment Events Enrichment Response

The request message to the Payment Events Enrichment endpoint has been successfully processed. You will receive a 200 OK response.

200 OK response example

{
  "transactionId": "49fp3l68395gs24g",
  "notes": "Default values were used for the following missing fields: 'channelsubtype','merchantip'"
}

Properties

Name	Type	Required	Description
transactionId	string	true	Corresponds to the transactionid sent in the request JSON.
notes	string	true	The notes consist of relevant information about the payment event that was sent.

200 OK - Payment Post-Authorization Enrichment Response

The request message to the Post-Authorization Enrichment endpoint has been successfully processed. You will receive a 200 OK response.

200 OK response example

{
    "message": "Payment enrichment was processed successfully"
}

Properties

Name	Type	Required	Description
message	string	true	Indicates the successful result of the payment enrichment process.

200 OK - Data Collection Response

The request message to the endpoint has been successfully processed. You will receive a 200 OK response.

The following endpoints are designed only for data collection:

• Dispute Events
• Merchant Account Information
• Inter-Account Transfers
• Account Bank Transfers
• Merchant Evaluations

Data collection response example

{
  "created": 2,
  "deleted": 0,
  "errors": [],
  "ignored": 0,
  "received": 2,
  "updated": 0
}

Properties

Name	Type	Required	Description
created	integer	false	how many entities have been created
deleted	integer	false	how many entities have been deleted
errors	[string]	false	list of errors that happened during the operation
ignored	integer	false	how many entities have been ignored (usually because they already exist)
received	integer	false	how many entities have been received
updated	integer	false	how many entities have been updated

200 OK - Rule creation response

The request message to the Rule creation endpoint has been successfully processed. You will receive a 200 OK response.

200 OK response example

{
  "ruleId": "3f89eeb6-53bb-4323-ad58-5de64662297f",
  "version": 1,
  "customer": "customer-placeholder",
  "createdAt": 1672527600,
  "createdBy": "customer-placeholder@mail.com",
  "serviceType": "self-service",
  "externalId": "rule-1",
  "name": "Deny merchant",
  "description": "Deny suspicious merchant",
  "trigger": "transaction.merchant == \"suspicious-merchant-1\"",
  "action": "deny",
  "status": "enabled",
  "priority": 1,
  "tableauId": null
}

Properties

Name	Type	Required	Description
ruleId	string(uuid)	true	Unique identifier automatically assigned by the system to each rule.
version	integer	true	Indicates the version of the rule; incremented each time the rule is updated.
customer	string	true	Identifier for the customer account to which the rule belongs.
createdAt	integer	true	Unix timestamp indicating when the rule was created.
createdBy	string	true	Email address of the user who created the rule.
serviceType	string	true	Indicates the origin of the rule: self-service for rules created by the customer either through the Rules Editor UI or the API; custom for rules implemented by Fraudio.
externalId	string	true	Unique identifier for the rule from an external system.
name	string	true	Brief title for the rule.
description	string	true	Detailed explanation of the rule.
trigger	string	true	Logical expressions to evaluate incoming pre-auth transactions.
action	string	true	Action to take when the trigger is met. Can be allow, review, or deny.
status	string	true	Current state of the rule. Can be enabled, disabled, or archived.
priority	integer	true	Priority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauId	string	false	Unique identifier for the rule in the Rules Editor Tableau Dashboard.

200 OK - Rules list response

The request to the List Rules endpoint has been successfully processed. You will receive a 200 OK response with an array of your organization's rule objects.

200 OK response example

[
  {
    "ruleId": "3f89eeb6-53bb-4323-ad58-5de64662297f",
    "version": 1,
    "customer": "your-customer-id",
    "createdAt": 1672527600,
    "createdBy": "your-email@mail.com",
    "serviceType": "self-service",
    "externalId": "rule-1",
    "name": "Deny merchant",
    "description": "Deny suspicious merchant",
    "trigger": "transaction.merchant == \"suspicious-merchant-1\"",
    "action": "deny",
    "status": "enabled",
    "priority": 1,
    "tableauId": null
  },
  {
    "ruleId": "4f98efb7-64cc-4333-bf59-6fe75762380g",
    "version": 2,
    "customer": "your-customer-id",
    "createdAt": 1672528600,
    "createdBy": "your-email@mail.com",
    "serviceType": "custom",
    "externalId": "rule-2",
    "name": "Allow merchant",
    "description": "Allow trusted merchant",
    "trigger": "transaction.merchant == \"trusted-merchant-1\"",
    "action": "allow",
    "status": "enabled",
    "priority": 2,
    "tableauId": "tableau-id-2"
  }
]

Properties

Name	Type	Required	Description
ruleId	string(uuid)	true	Unique identifier automatically assigned by the system to each rule.
version	integer	true	Indicates the version of the rule; incremented each time the rule is updated.
customer	string	true	Identifier for the customer account to which the rule belongs.
createdAt	integer	true	Unix timestamp indicating when the rule was created.
createdBy	string	true	Email address of the user who created the rule.
serviceType	string	true	Indicates the origin of the rule: self-service for rules created by the customer either through the Rules Editor UI or the API; custom for rules implemented by Fraudio.
externalId	string	true	Unique identifier for the rule from an external system.
name	string	true	Brief title for the rule.
description	string	true	Detailed explanation of the rule.
trigger	string	true	Logical expressions to evaluate incoming pre-auth transactions.
action	string	true	Action to take when the trigger is met. Can be allow, review, or deny.
status	string	true	Current state of the rule. Can be enabled, disabled, or archived.
priority	integer	true	Priority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauId	string	false	Unique identifier for the rule in the Rules Editor Tableau Dashboard.

200 OK - Rule list by ID response

The request to retrieve a specific rule by its ID has been successfully processed. You will receive a 200 OK response with the details of the requested rule.

200 OK response example

{
  "ruleId": "3f89eeb6-53bb-4323-ad58-5de64662297f",
  "version": 1,
  "customer": "your-customer-id",
  "createdAt": 1672527600,
  "createdBy": "your-email@mail.com",
  "serviceType": "self-service",
  "externalId": "rule-1",
  "name": "Deny merchant",
  "description": "Deny suspicious merchant",
  "trigger": "transaction.merchant == \"suspicious-merchant-1\"",
  "action": "deny",
  "status": "enabled",
  "priority": 1,
  "tableauId": null
}

Properties

Name	Type	Required	Description
ruleId	string(uuid)	true	Unique identifier automatically assigned by the system to each rule.
version	integer	true	Indicates the version of the rule; incremented each time the rule is updated.
customer	string	true	Identifier for the customer account to which the rule belongs.
createdAt	integer	true	Unix timestamp indicating when the rule was created.
createdBy	string	true	Email address of the user who created the rule.
serviceType	string	true	Indicates the origin of the rule: self-service for rules created by the customer either through the Rules Editor UI or the API; custom for rules implemented by Fraudio.
externalId	string	true	Unique identifier for the rule from an external system.
name	string	true	Brief title for the rule.
description	string	true	Detailed explanation of the rule.
trigger	string	true	Logical expressions to evaluate incoming pre-auth transactions.
action	string	true	Action to take when the trigger is met. Can be allow, review, or deny.
status	string	true	Current state of the rule. Can be enabled, disabled, or archived.
priority	integer	true	Priority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauId	string	false	Unique identifier for the rule in the Rules Editor Tableau Dashboard.

200 OK - Rule updated response

The request message to the Rule update endpoint has been successfully processed. You will receive a 200 OK response.

200 OK response example

{
  "ruleId": "3f89eeb6-53bb-4323-ad58-5de64662297f",
  "version": 2,
  "customer": "customer-placeholder",
  "createdAt": 1672527600,
  "createdBy": "customer-placeholder@mail.com",
  "serviceType": "self-service",
  "externalId": "rule-1-updated",
  "name": "Deny updated merchant",
  "description": "Deny updated suspicious merchant",
  "trigger": "transaction.merchant == \"suspicious-merchant-2\"",
  "action": "review",
  "status": "disabled",
  "priority": 2,
  "tableauId": null
}

Properties

Name	Type	Required	Description
ruleId	string(uuid)	true	Unique identifier automatically assigned by the system to each rule.
version	integer	true	Indicates the version of the rule; incremented each time the rule is updated.
customer	string	true	Identifier for the customer account to which the rule belongs.
createdAt	integer	true	Unix timestamp indicating when the rule was created.
createdBy	string	true	Email address of the user who created the rule.
serviceType	string	true	Indicates the origin of the rule: self-service for rules created by the customer either through the Rules Editor UI or the API; custom for rules implemented by Fraudio.
externalId	string	true	Unique identifier for the rule from an external system.
name	string	true	Brief title for the rule.
description	string	true	Detailed explanation of the rule.
trigger	string	true	Logical expressions to evaluate incoming pre-auth transactions.
action	string	true	Action to take when the trigger is met. Can be allow, review, or deny.
status	string	true	Current state of the rule. Can be enabled, disabled, or archived.
priority	integer	true	Priority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauId	string	false	Unique identifier for the rule in the Rules Editor Tableau Dashboard.

Problem response

If the HTTP response code is not 200 OK, it indicates that there is a problem. We use RFC7807-compliant error messages to provide you with details of the problem.

Problem response example - Unauthorized

{
    "type": "about:blank",
    "status": 401,
    "title": "Missing Authorization Header",
    "detail": "Missing authorization header with valid token."
}

Problem response example - Bad Request

{
    "title": "Bad Request",
    "status": 400,
    "detail": "The following required fields are missing: transactiontype."
}

Problem response example - Service Unavailable

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Connection to database timed out",
  "instance": "http://example.com"
}

Properties

Name	Type	Required	Description
type	string(uri)	false	A relative URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type.
title	string	false	A short summary of the problem type. Written in English and readable for engineers; usually not suited for non-technical stakeholders, and not localized.
status	integer(int32)	false	The HTTP status code generated by the origin server for this specific occurrence of the problem.
detail	string	false	A human-readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
instance	string(uri)	false	A relative URI reference that identifies the specific occurrence of the problem. It may be used to locate the root of the problem in the source code, for example, by adding a fragment identifier or sub-path to the problem type.