Skip to main content
Version: 1.1

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

NameTypeRequiredDescription
recommendationstringtrueThe recommendation is an advised course of action. The recommendations will be either red, yellow, or green. Recommendations are generated by starting with the default thresholds, and then optimising the model using your customised preferences that you specify during onboarding.
scoredoubletrueThe score is a fraud score between 0 and 1, where the closer to 1, the higher the likelihood that the transaction is fraudulent.
notesstringtrueThe 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

NameTypeRequiredDescription
transactionIdstringtrueCorresponds to the transactionid sent in the request JSON.
notesstringtrueThe 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

NameTypeRequiredDescription
messagestringtrueIndicates 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

NameTypeRequiredDescription
createdintegerfalsehow many entities have been created
deletedintegerfalsehow many entities have been deleted
errors[string]falselist of errors that happened during the operation
ignoredintegerfalsehow many entities have been ignored (usually because they already exist)
receivedintegerfalsehow many entities have been received
updatedintegerfalsehow 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

NameTypeRequiredDescription
ruleIdstring(uuid)trueUnique identifier automatically assigned by the system to each rule.
versionintegertrueIndicates the version of the rule; incremented each time the rule is updated.
customerstringtrueIdentifier for the customer account to which the rule belongs.
createdAtintegertrueUnix timestamp indicating when the rule was created.
createdBystringtrueEmail address of the user who created the rule.
serviceTypestringtrueIndicates 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.
externalIdstringtrueUnique identifier for the rule from an external system.
namestringtrueBrief title for the rule.
descriptionstringtrueDetailed explanation of the rule.
triggerstringtrueLogical expressions to evaluate incoming pre-auth transactions.
actionstringtrueAction to take when the trigger is met. Can be allow, review, or deny.
statusstringtrueCurrent state of the rule. Can be enabled, disabled, or archived.
priorityintegertruePriority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauIdstringfalseUnique 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

NameTypeRequiredDescription
ruleIdstring(uuid)trueUnique identifier automatically assigned by the system to each rule.
versionintegertrueIndicates the version of the rule; incremented each time the rule is updated.
customerstringtrueIdentifier for the customer account to which the rule belongs.
createdAtintegertrueUnix timestamp indicating when the rule was created.
createdBystringtrueEmail address of the user who created the rule.
serviceTypestringtrueIndicates 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.
externalIdstringtrueUnique identifier for the rule from an external system.
namestringtrueBrief title for the rule.
descriptionstringtrueDetailed explanation of the rule.
triggerstringtrueLogical expressions to evaluate incoming pre-auth transactions.
actionstringtrueAction to take when the trigger is met. Can be allow, review, or deny.
statusstringtrueCurrent state of the rule. Can be enabled, disabled, or archived.
priorityintegertruePriority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauIdstringfalseUnique 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

NameTypeRequiredDescription
ruleIdstring(uuid)trueUnique identifier automatically assigned by the system to each rule.
versionintegertrueIndicates the version of the rule; incremented each time the rule is updated.
customerstringtrueIdentifier for the customer account to which the rule belongs.
createdAtintegertrueUnix timestamp indicating when the rule was created.
createdBystringtrueEmail address of the user who created the rule.
serviceTypestringtrueIndicates 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.
externalIdstringtrueUnique identifier for the rule from an external system.
namestringtrueBrief title for the rule.
descriptionstringtrueDetailed explanation of the rule.
triggerstringtrueLogical expressions to evaluate incoming pre-auth transactions.
actionstringtrueAction to take when the trigger is met. Can be allow, review, or deny.
statusstringtrueCurrent state of the rule. Can be enabled, disabled, or archived.
priorityintegertruePriority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauIdstringfalseUnique 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

NameTypeRequiredDescription
ruleIdstring(uuid)trueUnique identifier automatically assigned by the system to each rule.
versionintegertrueIndicates the version of the rule; incremented each time the rule is updated.
customerstringtrueIdentifier for the customer account to which the rule belongs.
createdAtintegertrueUnix timestamp indicating when the rule was created.
createdBystringtrueEmail address of the user who created the rule.
serviceTypestringtrueIndicates 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.
externalIdstringtrueUnique identifier for the rule from an external system.
namestringtrueBrief title for the rule.
descriptionstringtrueDetailed explanation of the rule.
triggerstringtrueLogical expressions to evaluate incoming pre-auth transactions.
actionstringtrueAction to take when the trigger is met. Can be allow, review, or deny.
statusstringtrueCurrent state of the rule. Can be enabled, disabled, or archived.
priorityintegertruePriority level for the rule. Ranges from 1 (highest) to 5 (lowest).
tableauIdstringfalseUnique 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

NameTypeRequiredDescription
typestring(uri)falseA 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.
titlestringfalseA short summary of the problem type. Written in English and readable for engineers; usually not suited for non-technical stakeholders, and not localized.
statusinteger(int32)falseThe HTTP status code generated by the origin server for this specific occurrence of the problem.
detailstringfalseA 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.
instancestring(uri)falseA 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.