NAV
Shell Python Java Perl Php

Introduction

Welcome to Fraudio!


Fraudio's mission is to fight fraud smarter by decomplexifying and disrupting the fraud detection industry to the benefit of all companies like yours. This mission is achieved through our powerful centralized AI brain that prevents, detects and fights fraud in real time, creating unrivalled value.


Fraudio's products are unique because they leverage AI, ML, APIs and cloud computing into a plug & play and pay-as-you-go solution that allows us to provide you with unique fraud scores for your transactions and more.


This manual will guide you to successfully integrate with Fraudio’s products and start creating value. Fraudio abstracts away all the complexity, making seamless integration and reliability the priority. Integrating with Fraudio’s products can take as little as two weeks, and is as simple as knowing how to interact with our API. We also provide you with diagrams and code snippets to support you along the way.


This manual is structured as follows:

Follow the steps below to start fighting fraud smarter!

Quickstart

The objective of this section is to help you to integrate with Fraudio’s products as fast and smoothly as possible. Fraudio provides a "plug and play" API for each of its products. The interaction paradigm is request-response (or request-reply), and the communication protocol is HTTP.

Request credentials

Fraudio's API endpoints are protected using role based access control (RBAC). You will therefore need a set of credentials to access our resources. To schedule an appointment and request registration, please get in touch with your Fraudio contact.


To use Fraudio's products, you will need a valid token.

Authentication and authorization

Requests to the Transaction Fraud Score API are authenticated using HTTPS Bearer Authentication. In order to go live, you will need to receive your unique bearer token (API Key) from our support team to use in your request header.

API URL

In order to interact/integrate with our API, you will need to issue HTTPS requests against our central API URL:


https://api.fraudio.com


In the products chapter, you'll learn which endpoints to use based on the product you are integrating with.


In general, an endpoint is composed of:

For the purpose of this quickstart, we will show you how to perform your first API call.

Sandboxing

Your integration with Fraudio’s products happens in a sandbox.


As a Fraudio customer, you can have 2 statuses:

  1. Sandboxed: A sandboxed customer is simply a customer that is not yet fully integrated with our API. When you're sandboxed, you can test any endpoint of our API without affecting any production usage.

  2. Live: Once you are fully integrated with our API, you can request Fraudio to go live. Once you become a live customer, our AI brain starts learning from your usage and automatically improves itself, which will give you better scores as it receives more data.

First API Request

curl -X POST 'https://api.fraudio.com/v1/transactions/score' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{"transactionid":"49fp3l68395gs24g","transactiontype":"void","originalamount":251.41,"currency":"012","timestamp":1646063615,"cardbin":"442742","merchant":"Fred&FreddySportsStore","parenttransactionid":"4583409307","cardtoken":"49fp3l68395gs24g","acceptorip":"542.6.8.838","cardexpirydate":"03/21","channel":"moto","channelsubtype":"paymentlink","lastfourdigits":"4932","mcccode":"5969","merchantip":"128.0.0.1","posentrymode":"012","recurring":"true","recurringparentid":"09a70bd7-2993-4df6-a693-99c26ee4bedb","registrationdate":100041643253.143105,"threedsused":"true","transactionip":"152.0.6.152","acceptorid":"6ad3b45e-0f14-4522-885b-dd8049fc773c","acceptorcity":"London","acceptorcountry":"056","acceptorpostalcode":"38010","acceptorstatecode":"38010","acceptorstreetaddress":"29Ravenscroft,Covingham","acquirer":"Acquirer X","acquirercountry":"056","avsused":"true","bankaccountnumber":"NL15INGB4014343434343","cardaccess":"pinaccess","cardholder":"JohnSpencer","cardholderemail":"support@fraudio.com","cardholderphonenumber":"+31 71 000 0000","cavvused":"true","cvvused":"true","digitalwalletoperator":"staged","gateway":"staged","initialrecurring":"true","issuingplan":"merchant plan 1","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b3hh","merchantstatecode":"GA","merchanturl":"www.foreverliving.com","mid":"1532512","ocptenabled":"true","processor":"ProcessorY","shopperemail":"support@fraudio.com","shoppername":"John Spencer","shopperphonenumber":"+31 71 000 0000","submerchant":"ShoestoreX","terminaltype":"cat1","transactioncountry":"056","transactionpostalcode":"w1b3hh","transactionstatecode":"GA","transactionstreetaddress":"29Ravenscroft,Covingham","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","authresult":"success","cavvresult":"5","ddresult":"ZXC*SiteAccess4343-432-333","gatewaydeclinereason":"CardDisabled","ucafindicator":"2"}'
import json
import os

import requests

scoring_endpoint = 'https://api.fraudio.com/v1/transactions/score'
access_token = os.environ['ACCESS_TOKEN']
transaction = {"transactionid":"49fp3l68395gs24g","transactiontype":"void","originalamount":251.41,"currency":"012","timestamp":1646063615,"cardbin":"442742","merchant":"Fred&FreddySportsStore","parenttransactionid":"4583409307","cardtoken":"49fp3l68395gs24g","acceptorip":"542.6.8.838","cardexpirydate":"03/21","channel":"moto","channelsubtype":"paymentlink","lastfourdigits":"4932","mcccode":"5969","merchantip":"128.0.0.1","posentrymode":"012","recurring":"true","recurringparentid":"09a70bd7-2993-4df6-a693-99c26ee4bedb","registrationdate":100041643253.143105,"threedsused":"true","transactionip":"152.0.6.152","acceptorid":"6ad3b45e-0f14-4522-885b-dd8049fc773c","acceptorcity":"London","acceptorcountry":"056","acceptorpostalcode":"38010","acceptorstatecode":"38010","acceptorstreetaddress":"29Ravenscroft,Covingham","acquirer":"Acquirer X","acquirercountry":"056","avsused":"true","bankaccountnumber":"NL15INGB4014343434343","cardaccess":"pinaccess","cardholder":"JohnSpencer","cardholderemail":"support@fraudio.com","cardholderphonenumber":"+31 71 000 0000","cavvused":"true","cvvused":"true","digitalwalletoperator":"staged","gateway":"staged","initialrecurring":"true","issuingplan":"merchant plan 1","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b3hh","merchantstatecode":"GA","merchanturl":"www.foreverliving.com","mid":"1532512","ocptenabled":"true","processor":"ProcessorY","shopperemail":"support@fraudio.com","shoppername":"John Spencer","shopperphonenumber":"+31 71 000 0000","submerchant":"ShoestoreX","terminaltype":"cat1","transactioncountry":"056","transactionpostalcode":"w1b3hh","transactionstatecode":"GA","transactionstreetaddress":"29Ravenscroft,Covingham","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","authresult":"success","cavvresult":"5","ddresult":"ZXC*SiteAccess4343-432-333","gatewaydeclinereason":"CardDisabled","ucafindicator":"2"}
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
r = requests.post(scoring_endpoint, headers=headers, data=json.dumps(transaction))
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class FraudScore
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String fraudScoreEndpoint = "https://api.fraudio.com/v1/transactions/score";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String transaction = "{\"transactionid\":\"49fp3l68395gs24g\",\"transactiontype\":\"void\",\"originalamount\":251.41,\"currency\":\"012\",\"timestamp\":1646063615,\"cardbin\":\"442742\",\"merchant\":\"Fred&FreddySportsStore\",\"parenttransactionid\":\"4583409307\",\"cardtoken\":\"49fp3l68395gs24g\",\"acceptorip\":\"542.6.8.838\",\"cardexpirydate\":\"03/21\",\"channel\":\"moto\",\"channelsubtype\":\"paymentlink\",\"lastfourdigits\":\"4932\",\"mcccode\":\"5969\",\"merchantip\":\"128.0.0.1\",\"posentrymode\":\"012\",\"recurring\":\"true\",\"recurringparentid\":\"09a70bd7-2993-4df6-a693-99c26ee4bedb\",\"registrationdate\":100041643253.143105,\"threedsused\":\"true\",\"transactionip\":\"152.0.6.152\",\"acceptorid\":\"6ad3b45e-0f14-4522-885b-dd8049fc773c\",\"acceptorcity\":\"London\",\"acceptorcountry\":\"056\",\"acceptorpostalcode\":\"38010\",\"acceptorstatecode\":\"38010\",\"acceptorstreetaddress\":\"29Ravenscroft,Covingham\",\"acquirer\":\"Acquirer X\",\"acquirercountry\":\"056\",\"avsused\":\"true\",\"bankaccountnumber\":\"NL15INGB4014343434343\",\"cardaccess\":\"pinaccess\",\"cardholder\":\"JohnSpencer\",\"cardholderemail\":\"support@fraudio.com\",\"cardholderphonenumber\":\"+31 71 000 0000\",\"cavvused\":\"true\",\"cvvused\":\"true\",\"digitalwalletoperator\":\"staged\",\"gateway\":\"staged\",\"initialrecurring\":\"true\",\"issuingplan\":\"merchant plan 1\",\"kyclevel\":\"5\",\"kyclevelnorm\":0.5,\"limitprofile\":\"5\",\"merchantcity\":\"London\",\"merchantcountry\":\"528\",\"merchantemail\":\"support@fraudio.com\",\"merchantpostalcode\":\"w1b3hh\",\"merchantstatecode\":\"GA\",\"merchanturl\":\"www.foreverliving.com\",\"mid\":\"1532512\",\"ocptenabled\":\"true\",\"processor\":\"ProcessorY\",\"shopperemail\":\"support@fraudio.com\",\"shoppername\":\"John Spencer\",\"shopperphonenumber\":\"+31 71 000 0000\",\"submerchant\":\"ShoestoreX\",\"terminaltype\":\"cat1\",\"transactioncountry\":\"056\",\"transactionpostalcode\":\"w1b3hh\",\"transactionstatecode\":\"GA\",\"transactionstreetaddress\":\"29Ravenscroft,Covingham\",\"avsresult\":\"A\",\"cvvresult\":\"S\",\"eci\":\"02\",\"responsecode\":\"05\",\"success\":\"true\",\"authresult\":\"success\",\"cavvresult\":\"5\",\"ddresult\":\"ZXC*SiteAccess4343-432-333\",\"gatewaydeclinereason\":\"CardDisabled\",\"ucafindicator\":\"2\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(fraudScoreEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(transaction))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $fraud_score_endpoint = 'https://api.fraudio.com/v1/transactions/score';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $transaction = '{"transactionid":"49fp3l68395gs24g","transactiontype":"void","originalamount":251.41,"currency":"012","timestamp":1646063615,"cardbin":"442742","merchant":"Fred&FreddySportsStore","parenttransactionid":"4583409307","cardtoken":"49fp3l68395gs24g","acceptorip":"542.6.8.838","cardexpirydate":"03/21","channel":"moto","channelsubtype":"paymentlink","lastfourdigits":"4932","mcccode":"5969","merchantip":"128.0.0.1","posentrymode":"012","recurring":"true","recurringparentid":"09a70bd7-2993-4df6-a693-99c26ee4bedb","registrationdate":100041643253.143105,"threedsused":"true","transactionip":"152.0.6.152","acceptorid":"6ad3b45e-0f14-4522-885b-dd8049fc773c","acceptorcity":"London","acceptorcountry":"056","acceptorpostalcode":"38010","acceptorstatecode":"38010","acceptorstreetaddress":"29Ravenscroft,Covingham","acquirer":"Acquirer X","acquirercountry":"056","avsused":"true","bankaccountnumber":"NL15INGB4014343434343","cardaccess":"pinaccess","cardholder":"JohnSpencer","cardholderemail":"support@fraudio.com","cardholderphonenumber":"+31 71 000 0000","cavvused":"true","cvvused":"true","digitalwalletoperator":"staged","gateway":"staged","initialrecurring":"true","issuingplan":"merchant plan 1","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b3hh","merchantstatecode":"GA","merchanturl":"www.foreverliving.com","mid":"1532512","ocptenabled":"true","processor":"ProcessorY","shopperemail":"support@fraudio.com","shoppername":"John Spencer","shopperphonenumber":"+31 71 000 0000","submerchant":"ShoestoreX","terminaltype":"cat1","transactioncountry":"056","transactionpostalcode":"w1b3hh","transactionstatecode":"GA","transactionstreetaddress":"29Ravenscroft,Covingham","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","authresult":"success","cavvresult":"5","ddresult":"ZXC*SiteAccess4343-432-333","gatewaydeclinereason":"CardDisabled","ucafindicator":"2"}';
my $req = HTTP::Request -> new(POST => $fraud_score_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($transaction);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $fraud_score_endpoint = 'https://api.fraudio.com/v1/transactions/score';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $transaction = "{\"transactionid\":\"49fp3l68395gs24g\",\"transactiontype\":\"void\",\"originalamount\":251.41,\"currency\":\"012\",\"timestamp\":1646063615,\"cardbin\":\"442742\",\"merchant\":\"Fred&FreddySportsStore\",\"parenttransactionid\":\"4583409307\",\"cardtoken\":\"49fp3l68395gs24g\",\"acceptorip\":\"542.6.8.838\",\"cardexpirydate\":\"03/21\",\"channel\":\"moto\",\"channelsubtype\":\"paymentlink\",\"lastfourdigits\":\"4932\",\"mcccode\":\"5969\",\"merchantip\":\"128.0.0.1\",\"posentrymode\":\"012\",\"recurring\":\"true\",\"recurringparentid\":\"09a70bd7-2993-4df6-a693-99c26ee4bedb\",\"registrationdate\":100041643253.143105,\"threedsused\":\"true\",\"transactionip\":\"152.0.6.152\",\"acceptorid\":\"6ad3b45e-0f14-4522-885b-dd8049fc773c\",\"acceptorcity\":\"London\",\"acceptorcountry\":\"056\",\"acceptorpostalcode\":\"38010\",\"acceptorstatecode\":\"38010\",\"acceptorstreetaddress\":\"29Ravenscroft,Covingham\",\"acquirer\":\"Acquirer X\",\"acquirercountry\":\"056\",\"avsused\":\"true\",\"bankaccountnumber\":\"NL15INGB4014343434343\",\"cardaccess\":\"pinaccess\",\"cardholder\":\"JohnSpencer\",\"cardholderemail\":\"support@fraudio.com\",\"cardholderphonenumber\":\"+31 71 000 0000\",\"cavvused\":\"true\",\"cvvused\":\"true\",\"digitalwalletoperator\":\"staged\",\"gateway\":\"staged\",\"initialrecurring\":\"true\",\"issuingplan\":\"merchant plan 1\",\"kyclevel\":\"5\",\"kyclevelnorm\":0.5,\"limitprofile\":\"5\",\"merchantcity\":\"London\",\"merchantcountry\":\"528\",\"merchantemail\":\"support@fraudio.com\",\"merchantpostalcode\":\"w1b3hh\",\"merchantstatecode\":\"GA\",\"merchanturl\":\"www.foreverliving.com\",\"mid\":\"1532512\",\"ocptenabled\":\"true\",\"processor\":\"ProcessorY\",\"shopperemail\":\"support@fraudio.com\",\"shoppername\":\"John Spencer\",\"shopperphonenumber\":\"+31 71 000 0000\",\"submerchant\":\"ShoestoreX\",\"terminaltype\":\"cat1\",\"transactioncountry\":\"056\",\"transactionpostalcode\":\"w1b3hh\",\"transactionstatecode\":\"GA\",\"transactionstreetaddress\":\"29Ravenscroft,Covingham\",\"avsresult\":\"A\",\"cvvresult\":\"S\",\"eci\":\"02\",\"responsecode\":\"05\",\"success\":\"true\",\"authresult\":\"success\",\"cavvresult\":\"5\",\"ddresult\":\"ZXC*SiteAccess4343-432-333\",\"gatewaydeclinereason\":\"CardDisabled\",\"ucafindicator\":\"2\"}";
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $transaction
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($fraud_score_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/v1/transactions/score

This endpoint is part of the payment fraud detection product, whose main purpose is to score transactions for fraud. To the right of this paragraph, you will see boilerplate code samples, which you can use to help you quickly perform your first API request. Please copy and paste the provided code snippets to quickly integrate. You can choose between a shell script, Python, Java, Perl, and PHP.


The meaning of each field of the input JSON of this API call is explained in the API endpoints section. Later, you will have to map your transactions schema to the schema accepted by the fraud score endpoint. However, the goal of this quickstart tutorial is simply to give you the tools to integrate quickly with one of our main endpoints.

Products

Fraudio currently offers two main products:

  1. Payment fraud detection: allows you to detect payment fraud.

  2. Merchant initiated fraud detection: allows you to detect merchant initiated fraud.

Payment fraud detection

The payment fraud detection product detects payment fraud in real-time. The product is composed of three API endpoints:

Please see the section on API endpoints to view a more detailed explanation on how to connect and interact with each of the endpoints.

Merchant initiated fraud detection

The merchant initiated fraud detection product generates scores for merchants, instead of transactions. Fraudio will periodically (e.g. every 12 hours) deliver reports via your preferred channel (email, Slack, dashboards, notifications).


The merchant initiated fraud detection product is composed of the three endpoints of the payment fraud detection product (fraud score endpoint, post-authorization backfill endpoint and chargebacks endpoint), plus four additional endpoints:

For a detailed technical description of all endpoints mentioned above, please check the API endpoints chapter. There, you can find the accepted formats for the data you need to send to these endpoints, as well as code snippet examples and more.

API endpoints

This chapter explains, in detail, how to connect to Fraudio's API endpoints. These explanations are accompanied by code samples in several programming languages. Please choose a tab from the top-right side of this guide to see code examples in your preferred programming language.

The base URL of Fraudio's API is:

The central API that manages our AI brain is comprised of several endpoints:

Authentication Method

Fraudio API authentication method is:

Required Headers
Header Type Value Description
Authorization string Bearer ACCESS_TOKEN Fraudio API endpoints are secured through Bearer Authentication. Therefore, you must provide the HTTP header Authorization: Bearer ACCESS_TOKEN for every request that you issue against protected Fraudio API endpoints. Please replace ACCESS_TOKEN with the token you have received from Fraudio.
Content-Type string application/json Fraudio API endpoints require the Content-Type: application/json HTTP header to be set on the HTTP request.
Types of Responses

We can distinguish the following outcomes of a HTTP request issued to the Fraudio API:

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

The 200 OK Code

If the API endpoint replies with a 200 OK code, your call has been successful. A 200 OK code is always paired with a response body. The response body format depends on the endpoint you have used.

The API endpoints section explains the format of200 OK responses for each endpoint.

Data collection response

Some of our endpoints (specifically: chargebacks, merchant account information, inter account transfers, account bank transfers and merchant evaluations endpoints) exist only to collect data. Therefore, on success, they return a generic response that we refer to as a data collection response. This will give you information about the collection process of the particular data entity that you are trying to submit to the endpoint. Those endpoints will return the response together with the 200 OK code.

Properties
{
  "created": 2,
  "deleted": 0,
  "errors": 2,
  "ignored": 5,
  "received": 0,
  "updated": 0
}
Name Type Required Restrictions Description
created integer false none how many entities have been created
deleted integer false none how many entities have been deleted
errors [string] false none list of errors that happened during the operation
ignored integer false none how many entities have been ignored (usually because they already exist)
received integer false none how many entities have been received
updated integer false none how many entities have been updated
Error Messages

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. Below, the definition of a problem response.

Problem

Problem response compliant with RFC7807.

Properties
{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Connection to database timed out",
  "instance": "http://example.com"
}
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, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.

Fraud Score

Code samples

curl -X POST 'https://api.fraudio.com/v1/transactions/score' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{"customer":"customer-placeholder","transactionid":"49fp3l68395gs24g","transactiontype":"void","originalamount":251.41,"currency":"012","timestamp":1646063615,"cardbin":"442742","merchant":"Fred&FreddySportsStore","parenttransactionid":"4583409307","cardtoken":"49fp3l68395gs24g","acceptorip":"542.6.8.838","cardexpirydate":"03/21","channel":"moto","channelsubtype":"paymentlink","lastfourdigits":"4932","mcccode":"5969","merchantip":"128.0.0.1","posentrymode":"012","recurring":"true","recurringparentid":"09a70bd7-2993-4df6-a693-99c26ee4bedb","registrationdate":100041643253.143105,"threedsused":"true","transactionip":"152.0.6.152","acceptorid":"6ad3b45e-0f14-4522-885b-dd8049fc773c","acceptorcity":"London","acceptorcountry":"056","acceptorpostalcode":"38010","acceptorstatecode":"38010","acceptorstreetaddress":"29Ravenscroft,Covingham","acquirer":"Acquirer X","acquirercountry":"056","avsused":"true","bankaccountnumber":"NL15INGB4014343434343","cardaccess":"pinaccess","cardholder":"JohnSpencer","cardholderemail":"support@fraudio.com","cardholderphonenumber":"+31 71 000 0000","cavvused":"true","cvvused":"true","digitalwalletoperator":"staged","gateway":"staged","initialrecurring":"true","issuingplan":"merchant plan 1","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b3hh","merchantstatecode":"GA","merchanturl":"www.foreverliving.com","mid":"1532512","ocptenabled":"true","processor":"ProcessorY","shopperemail":"support@fraudio.com","shoppername":"John Spencer","shopperphonenumber":"+31 71 000 0000","submerchant":"ShoestoreX","terminaltype":"cat1","transactioncountry":"056","transactionpostalcode":"w1b3hh","transactionstatecode":"GA","transactionstreetaddress":"29Ravenscroft,Covingham","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","authresult":"success","cavvresult":"5","ddresult":"ZXC*SiteAccess4343-432-333","gatewaydeclinereason":"CardDisabled","ucafindicator":"2"}'
import json
import os

import requests

scoring_endpoint = 'https://api.fraudio.com/v1/transactions/score'
access_token = os.environ['ACCESS_TOKEN']
transaction = {"customer": "customer-placeholder","transactionid":"49fp3l68395gs24g","transactiontype":"void","originalamount":251.41,"currency":"012","timestamp":1646063615,"cardbin":"442742","merchant":"Fred&FreddySportsStore","parenttransactionid":"4583409307","cardtoken":"49fp3l68395gs24g","acceptorip":"542.6.8.838","cardexpirydate":"03/21","channel":"moto","channelsubtype":"paymentlink","lastfourdigits":"4932","mcccode":"5969","merchantip":"128.0.0.1","posentrymode":"012","recurring":"true","recurringparentid":"09a70bd7-2993-4df6-a693-99c26ee4bedb","registrationdate":100041643253.143105,"threedsused":"true","transactionip":"152.0.6.152","acceptorid":"6ad3b45e-0f14-4522-885b-dd8049fc773c","acceptorcity":"London","acceptorcountry":"056","acceptorpostalcode":"38010","acceptorstatecode":"38010","acceptorstreetaddress":"29Ravenscroft,Covingham","acquirer":"Acquirer X","acquirercountry":"056","avsused":"true","bankaccountnumber":"NL15INGB4014343434343","cardaccess":"pinaccess","cardholder":"JohnSpencer","cardholderemail":"support@fraudio.com","cardholderphonenumber":"+31 71 000 0000","cavvused":"true","cvvused":"true","digitalwalletoperator":"staged","gateway":"staged","initialrecurring":"true","issuingplan":"merchant plan 1","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b3hh","merchantstatecode":"GA","merchanturl":"www.foreverliving.com","mid":"1532512","ocptenabled":"true","processor":"ProcessorY","shopperemail":"support@fraudio.com","shoppername":"John Spencer","shopperphonenumber":"+31 71 000 0000","submerchant":"ShoestoreX","terminaltype":"cat1","transactioncountry":"056","transactionpostalcode":"w1b3hh","transactionstatecode":"GA","transactionstreetaddress":"29Ravenscroft,Covingham","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","authresult":"success","cavvresult":"5","ddresult":"ZXC*SiteAccess4343-432-333","gatewaydeclinereason":"CardDisabled","ucafindicator":"2"}
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
r = requests.post(scoring_endpoint, headers=headers, data=json.dumps(transaction))
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class FraudScore
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String fraudScoreEndpoint = "https://api.fraudio.com/v1/transactions/score";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String transaction = "{\"customer\": \"customer-placeholder\",\"transactionid\":\"49fp3l68395gs24g\",\"transactiontype\":\"void\",\"originalamount\":251.41,\"currency\":\"012\",\"timestamp\":1646063615,\"cardbin\":\"442742\",\"merchant\":\"Fred&FreddySportsStore\",\"parenttransactionid\":\"4583409307\",\"cardtoken\":\"49fp3l68395gs24g\",\"acceptorip\":\"542.6.8.838\",\"cardexpirydate\":\"03/21\",\"channel\":\"moto\",\"channelsubtype\":\"paymentlink\",\"lastfourdigits\":\"4932\",\"mcccode\":\"5969\",\"merchantip\":\"128.0.0.1\",\"posentrymode\":\"012\",\"recurring\":\"true\",\"recurringparentid\":\"09a70bd7-2993-4df6-a693-99c26ee4bedb\",\"registrationdate\":100041643253.143105,\"threedsused\":\"true\",\"transactionip\":\"152.0.6.152\",\"acceptorid\":\"6ad3b45e-0f14-4522-885b-dd8049fc773c\",\"acceptorcity\":\"London\",\"acceptorcountry\":\"056\",\"acceptorpostalcode\":\"38010\",\"acceptorstatecode\":\"38010\",\"acceptorstreetaddress\":\"29Ravenscroft,Covingham\",\"acquirer\":\"Acquirer X\",\"acquirercountry\":\"056\",\"avsused\":\"true\",\"bankaccountnumber\":\"NL15INGB4014343434343\",\"cardaccess\":\"pinaccess\",\"cardholder\":\"JohnSpencer\",\"cardholderemail\":\"support@fraudio.com\",\"cardholderphonenumber\":\"+31 71 000 0000\",\"cavvused\":\"true\",\"cvvused\":\"true\",\"digitalwalletoperator\":\"staged\",\"gateway\":\"staged\",\"initialrecurring\":\"true\",\"issuingplan\":\"merchant plan 1\",\"kyclevel\":\"5\",\"kyclevelnorm\":0.5,\"limitprofile\":\"5\",\"merchantcity\":\"London\",\"merchantcountry\":\"528\",\"merchantemail\":\"support@fraudio.com\",\"merchantpostalcode\":\"w1b3hh\",\"merchantstatecode\":\"GA\",\"merchanturl\":\"www.foreverliving.com\",\"mid\":\"1532512\",\"ocptenabled\":\"true\",\"processor\":\"ProcessorY\",\"shopperemail\":\"support@fraudio.com\",\"shoppername\":\"John Spencer\",\"shopperphonenumber\":\"+31 71 000 0000\",\"submerchant\":\"ShoestoreX\",\"terminaltype\":\"cat1\",\"transactioncountry\":\"056\",\"transactionpostalcode\":\"w1b3hh\",\"transactionstatecode\":\"GA\",\"transactionstreetaddress\":\"29Ravenscroft,Covingham\",\"avsresult\":\"A\",\"cvvresult\":\"S\",\"eci\":\"02\",\"responsecode\":\"05\",\"success\":\"true\",\"authresult\":\"success\",\"cavvresult\":\"5\",\"ddresult\":\"ZXC*SiteAccess4343-432-333\",\"gatewaydeclinereason\":\"CardDisabled\",\"ucafindicator\":\"2\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(fraudScoreEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(transaction))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $fraud_score_endpoint = 'https://api.fraudio.com/v1/transactions/score';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $transaction = '{"customer": "customer-placeholder","transactionid":"49fp3l68395gs24g","transactiontype":"void","originalamount":251.41,"currency":"012","timestamp":1646063615,"cardbin":"442742","merchant":"Fred&FreddySportsStore","parenttransactionid":"4583409307","cardtoken":"49fp3l68395gs24g","acceptorip":"542.6.8.838","cardexpirydate":"03/21","channel":"moto","channelsubtype":"paymentlink","lastfourdigits":"4932","mcccode":"5969","merchantip":"128.0.0.1","posentrymode":"012","recurring":"true","recurringparentid":"09a70bd7-2993-4df6-a693-99c26ee4bedb","registrationdate":100041643253.143105,"threedsused":"true","transactionip":"152.0.6.152","acceptorid":"6ad3b45e-0f14-4522-885b-dd8049fc773c","acceptorcity":"London","acceptorcountry":"056","acceptorpostalcode":"38010","acceptorstatecode":"38010","acceptorstreetaddress":"29Ravenscroft,Covingham","acquirer":"Acquirer X","acquirercountry":"056","avsused":"true","bankaccountnumber":"NL15INGB4014343434343","cardaccess":"pinaccess","cardholder":"JohnSpencer","cardholderemail":"support@fraudio.com","cardholderphonenumber":"+31 71 000 0000","cavvused":"true","cvvused":"true","digitalwalletoperator":"staged","gateway":"staged","initialrecurring":"true","issuingplan":"merchant plan 1","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b3hh","merchantstatecode":"GA","merchanturl":"www.foreverliving.com","mid":"1532512","ocptenabled":"true","processor":"ProcessorY","shopperemail":"support@fraudio.com","shoppername":"John Spencer","shopperphonenumber":"+31 71 000 0000","submerchant":"ShoestoreX","terminaltype":"cat1","transactioncountry":"056","transactionpostalcode":"w1b3hh","transactionstatecode":"GA","transactionstreetaddress":"29Ravenscroft,Covingham","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","authresult":"success","cavvresult":"5","ddresult":"ZXC*SiteAccess4343-432-333","gatewaydeclinereason":"CardDisabled","ucafindicator":"2"}';
my $req = HTTP::Request -> new(POST => $fraud_score_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($transaction);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $fraud_score_endpoint = 'https://api.fraudio.com/v1/transactions/score';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $transaction = "{\"customer\": \"customer-placeholder\", \"transactionid\":\"49fp3l68395gs24g\",\"transactiontype\":\"void\",\"originalamount\":251.41,\"currency\":\"012\",\"timestamp\":1646063615,\"cardbin\":\"442742\",\"merchant\":\"Fred&FreddySportsStore\",\"parenttransactionid\":\"4583409307\",\"cardtoken\":\"49fp3l68395gs24g\",\"acceptorip\":\"542.6.8.838\",\"cardexpirydate\":\"03/21\",\"channel\":\"moto\",\"channelsubtype\":\"paymentlink\",\"lastfourdigits\":\"4932\",\"mcccode\":\"5969\",\"merchantip\":\"128.0.0.1\",\"posentrymode\":\"012\",\"recurring\":\"true\",\"recurringparentid\":\"09a70bd7-2993-4df6-a693-99c26ee4bedb\",\"registrationdate\":100041643253.143105,\"threedsused\":\"true\",\"transactionip\":\"152.0.6.152\",\"acceptorid\":\"6ad3b45e-0f14-4522-885b-dd8049fc773c\",\"acceptorcity\":\"London\",\"acceptorcountry\":\"056\",\"acceptorpostalcode\":\"38010\",\"acceptorstatecode\":\"38010\",\"acceptorstreetaddress\":\"29Ravenscroft,Covingham\",\"acquirer\":\"Acquirer X\",\"acquirercountry\":\"056\",\"avsused\":\"true\",\"bankaccountnumber\":\"NL15INGB4014343434343\",\"cardaccess\":\"pinaccess\",\"cardholder\":\"JohnSpencer\",\"cardholderemail\":\"support@fraudio.com\",\"cardholderphonenumber\":\"+31 71 000 0000\",\"cavvused\":\"true\",\"cvvused\":\"true\",\"digitalwalletoperator\":\"staged\",\"gateway\":\"staged\",\"initialrecurring\":\"true\",\"issuingplan\":\"merchant plan 1\",\"kyclevel\":\"5\",\"kyclevelnorm\":0.5,\"limitprofile\":\"5\",\"merchantcity\":\"London\",\"merchantcountry\":\"528\",\"merchantemail\":\"support@fraudio.com\",\"merchantpostalcode\":\"w1b3hh\",\"merchantstatecode\":\"GA\",\"merchanturl\":\"www.foreverliving.com\",\"mid\":\"1532512\",\"ocptenabled\":\"true\",\"processor\":\"ProcessorY\",\"shopperemail\":\"support@fraudio.com\",\"shoppername\":\"John Spencer\",\"shopperphonenumber\":\"+31 71 000 0000\",\"submerchant\":\"ShoestoreX\",\"terminaltype\":\"cat1\",\"transactioncountry\":\"056\",\"transactionpostalcode\":\"w1b3hh\",\"transactionstatecode\":\"GA\",\"transactionstreetaddress\":\"29Ravenscroft,Covingham\",\"avsresult\":\"A\",\"cvvresult\":\"S\",\"eci\":\"02\",\"responsecode\":\"05\",\"success\":\"true\",\"authresult\":\"success\",\"cavvresult\":\"5\",\"ddresult\":\"ZXC*SiteAccess4343-432-333\",\"gatewaydeclinereason\":\"CardDisabled\",\"ucafindicator\":\"2\"}";
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $transaction
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($fraud_score_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/v1/transactions/score

Connecting to the fraud score endpoint allows you to score transactions for fraud.

This endpoint will return a fraud score and a recommendation. More specifically, it will return a prediction.

A fraud score is a number between 0 and 1. The closer to 1 the fraud score number is, the higher the likelihood that the transaction is fraudulent.

A recommendation is an advised course of action. This recommendation will be either Red, Yellow or Green. Recommendations are generated based on the thresholds that we set; these are typically customised based on your preferences and requirements, which are set after a discussion with Fraudio’s support team. Thresholds determine which transactions fall into which recommendation category, and are set based on multiple factors including your risk appetite, your business model, and any downstream actions that you want to trigger.

Parameter

Name In Type Required Description
body body Transaction true none

Transaction

A transaction event that contains pre-authorization information. Only in case of post-auth scoring the post-authorization information can be included.

Properties
{
  "customer": "customer-placeholder",
  "transactionid": "49fp3l68395gs24g",
  "transactiontype": "void",
  "originalamount": 251.41,
  "currency": "012",
  "timestamp": 1646063615,
  "cardbin": "442742",
  "merchant": "Fred & Freddy Sports Store",
  "parenttransactionid": "4583409307",
  "cardtoken": "49fp3l68395gs24g",
  "acceptorip": "542.6.8.838",
  "cardexpirydate": "03/21",
  "channel": "moto",
  "channelsubtype": "paymentlink",
  "lastfourdigits": "4932",
  "mcccode": "5969",
  "merchantip": "128.0.0.1",
  "posentrymode": "012",
  "recurring": "true",
  "recurringparentid": "09a70bd7-2993-4df6-a693-99c26ee4bedb",
  "registrationdate": 100041643253.143105,
  "threedsused": "true",
  "transactionip": "152.0.6.152",
  "acceptorid": "6ad3b45e-0f14-4522-885b-dd8049fc773c",
  "acceptorcity": "London",
  "acceptorcountry": "056",
  "acceptorpostalcode": "38010",
  "acceptorstatecode": "38010",
  "acceptorstreetaddress": "29 Ravenscroft, Covingham",
  "acquirer": "Acquirer X",
  "acquirercountry": "056",
  "avsused": "true",
  "bankaccountnumber": "NL15INGB4014343434343",
  "cardaccess": "pinaccess",
  "cardholder": "John Spencer",
  "cardholderemail": "support@fraudio.com",
  "cardholderphonenumber": "+31 71 000 0000",
  "cavvused": "true",
  "cvvused": "true",
  "digitalwalletoperator": "staged",
  "gateway": "staged",
  "initialrecurring": "true",
  "issuingplan": "merchant plan 1",
  "kyclevel": "5",
  "kyclevelnorm": 0.5,
  "limitprofile": "5",
  "merchantcity": "London",
  "merchantcountry": "528",
  "merchantemail": "support@fraudio.com",
  "merchantpostalcode": "w1b 3hh",
  "merchantstatecode": "GA",
  "merchanturl": "www.foreverliving.com",
  "mid": "1532512",
  "ocptenabled": "true",
  "processor": "Processor Y",
  "shopperemail": "support@fraudio.com",
  "shoppername": "John Spencer",
  "shopperphonenumber": "+31 71 000 0000",
  "submerchant": "Shoestore X",
  "terminaltype": "cat1",
  "transactioncountry": "056",
  "transactionpostalcode": "w1b 3hh",
  "transactionstatecode": "GA",
  "transactionstreetaddress": "29 Ravenscroft, Covingham",
  "avsresult": "A",
  "cvvresult": "S",
  "eci": "02",
  "responsecode": "05",
  "success": "true",
  "authresult": "success",
  "cavvresult": "5",
  "ddresult": "ZXC* Site Access 4343-432-333",
  "gatewaydeclinereason": "Card Disabled",
  "ucafindicator": "2"
}
Name Type Required Description
customer string true The name of the Fraudio customer making the API call.
transactionid string true The transaction ID is the unique identifier of the transaction event. So every auth, capture, auth_capture, etc. has its own unique ID.
transactiontype string true The type of transaction event. Possible values are: auth, capture, auth_capture, refund, void, top_up, incremental_auth, atm or reversal. Details about each possible value below.

auth: An authorization is used to reserve funds on the customer's card without yet deducting them.
capture: A capture is used to immediately deduct authorized funds (up to the amount auth'd) from a customer's card. A capture should always be linked to at least one authorization via the parenttransactionid.
auth_capture: A simultaneous combination of auth and capture in the same transaction, for when there is no need to perform these operations separately.
refund: A refund transaction returns credit to a customer's payment method.
void: A void transaction is the explicit discarding of authorization of funds.
top_up: Increases the available credit of a credit card.
incremental_auth: A transaction that increases the authorized amount of a confirmed auth transaction that has not yet been captured.
atm: An automated teller machine (atm) transaction.
reversal: A reversal annuls the transaction and re-credits the customer's payment method; this happens directly after the transaction has taken place but before the funds have been fully processed.
none: Use only when the transactiontype is unknown.
originalamount double true Amount/value of the transaction in the original currency. Must be a nonnegative value.
currency string true Numerical currency code of the currency used for the transaction (ISO 4217)
timestamp integer(int64) true The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted.
cardbin string true The Bank Identification Number (BIN), also known as the Issuer Identification Number (IIN), is the first six or eight digits of the card number.
merchant string true The name or identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
parenttransactionid string false The identifier that links separate events of one transaction. The parenttransactionid can link auths with captures, voids and refunds and it can link auth_captures with refunds and voids. Any name or unique identifier is accepted.
cardtoken string false The card token is the encryption that is used to identify the credit card. Any salted hash is accepted.
acceptorip string false IP-address of the card acceptor, so IP where the merchant's terminal is located.
cardexpirydate string false The expiry date of the card. Accepted format: MM/yy.
channel string false The name of the channel indicating how the payment was made. Accepted values: ecom, pos, moto, none. Details about each possible value below.
- ecom: An ecommerce payment is done over the internet.
- pos: Point of Sale transaction.
- moto: A mail or telephone order is a card-not-present transaction where the cardholder gives permission to process the transaction by providing order and payment details by mail (not email), fax, or telephone.
channelsubtype string false The name of the channel subtype. Accepted values: paymentlink, telephoneorder, mailorder, or none. Details about each possible value below.
- paymentlink: Payment is done using a link that is shared by the merchant.
- telephoneorder: Order and payment details are provided by telephone.
- mailorder: Order and payment details are provided by mail (not email).
- none: Unknown.
lastfourdigits string false The last four digits of the card number. Without cardtoken this field becomes important.
mcccode string false A Merchant Category Code (MCC) is a four-digit number listed for financial services. An MCC is used to classify a business by the types of goods or services it provides. Only ISO 18245 mcc codes are accepted.
merchantip string false IP-address of the merchant, so IP where the merchant is registered. There is a difference between acceptorip and merchantip: acceptorip is the location of the merchant's server on which the payment is received. So a merchant can have multiple acceptorips but only one merchantip.
posentrymode string false The POS entry mode is the code (3 digits) that identifies the method used to capture the PAN entry mode and the PIN entry capability. ISO 8583 (field 22) POS entry mode consists of 2 parts:
1. PAN (Primary Account Number) entry mode (the first 2 digits):
 - 00: Unknown.
 - 01: Key entered / Manual.
 - 02: Magnetic stripe.
 - 03: Bar code.
 - 05: ICC (integrated circuit card, that is, chip).
 - 07: Auto entry via contactless EMV.
 - 10: Merchant has Cardholder Credentials on File.
 - 80: Fallback from integrated circuit card (ICC) to magnetic stripe.
 - 81: Electronic commerce.
 - 91: Auto entry via contactless magnetic stripe.
2. PIN entry capability (the third digit):
 - 0: Unkown
 - 1: Terminal can accept PINs.
 - 2: Terminal cannot accept PINs.
- none: Completely unknown posentrymode.
recurring string false Indicates if the payment is recurring or not. Accepted values are true, false or none.
- true: Is recurring.
- false: is not recurring.
- none: Unknown.
recurringparentid string false The identifier that links back to the initial recurring transaction (the first of a series of recurring transactions).
registrationdate double false The time UTC at which the merchant got registered. Only Unix Timestamps are accepted.
threedsused string false Indicates if 3D-Secure is enabled for the transaction. Possible values are true, false or none.
- true: 3-D Secure has been used.
- false: 3-D Secure has not been used.
- none: Unknown.
transactionip string false IP-address of the transaction, so IP where the card holder's device is located.
acceptorid string false The name or identifier of the acceptor. Any name or unique identifier is accepted.
acceptorcity string false City where the card acceptor is located. Without acceptorip this field becomes important. Any city name is accepted.
acceptorcountry string false Countrycode of country where the card acceptor is located. Only ISO 3166-1 numeric country codes are accepted.
acceptorpostalcode string false Postal code where the card acceptor is located. Without acceptorip this field becomes important. Any postal code is accepted.
acceptorstatecode string false State where the card acceptor is located. Without acceptorip this field becomes important. Any state code is accepted.
acceptorstreetaddress string false Street address where the card acceptor is located. Without acceptorip this field becomes important. Any street address is accepted.
acquirer string false The acquirer is a financial institution with whom the merchant has a bank account.
acquirercountry string false Countrycode of country where the acquirer is registered. Only ISO 3166-1 numeric country codes are accepted.
avsused string false Indicates if AVS is enabled for the transaction. Accepted values are:
- true: AVS enabled.
- false: AVS disabled.
- none: Unknown.
bankaccountnumber string false IBAN (International Bank Account Number). Bank account number or ID is also sufficient.
cardaccess string false Information on how the card was accessed. Accepted values are:
- pinaccess: Card is accessed by using a pincode.
- signatureaccess: Card is accessed by using a signature.
- hybrid: Card is accessed by using a pincode and a signature.
- none: Unknown.
cardholder string false The name or identifier of the cardholder. This is not the same as the cardtoken, as a cardholder can have multiple credit cards (cardtokens). Any name or unique identifier is accepted.
cardholderemail string false The email address of the card holder.
cardholderphonenumber string false The phone number of the card holder.
cavvused string false Indicates if Cardholder Authentication Verification Value (CAVV) is enabled for the transaction. Accepted values are:
- true: CAVV enabled.
- false: CAVV disabled.
- none: Unknown.
cvvused string false Indicates if Card Verification Value (CVV) checks are done for the transaction. Accepted values are:
- true: CVV checks are done.
- false: CVV checks are not done.
- none: Unknown.
digitalwalletoperator string false Indicates the Digital Wallet Operator (DWO). A digital wallet refers to an electronic system that allows customers to pay for purchases without presenting a physical credit or debit card. Customers load their card details into a digital wallet app, and pay by tapping their device on a compatible terminal or by selecting their choice from stored payment methods when making an online purchase. Accepted values are:
- staged: A staged digital wallet transaction is done with a wallet that uses multiple “stages” to complete the transaction (a “funding” stage and a “payment” stage) and doesn’t necessarily pass along card information to the card brand or issuer.
- pass_through: A pass-through digital wallet transaction is done with a wallet where card payment information is used directly in the transaction, and passed along to the issuer and card network.
- none: Unknown.
gateway string false A payment gateway is a merchant service that facilitates a payment transaction by the transfer of information between a payment portal (such as a website, mobile phone or interactive voice response service) and the front end processor or acquiring bank.
initialrecurring string false Indicates if the transaction is the first of a series of recurring transactions. Accepted values are:
- true: The transaction is the first of a series ofof recurring transactions.
- false: The transaction is not the first of a series of recurring transactions.
- none: Unknown.
issuingplan string false Group created by the issuer that bundles cards together, such as product combinations that an issuer may offer.
kyclevel string false The Know-Your-Customer level of the merchant. Any indication level is accepted.
kyclevelnorm double false A normalized know-your-customer level of the merchant between 0 and 1, where 0 is a totally unknown and untrusted merchant and 1 is a fully known and absolutely trusted merchant.
limitprofile string false The limit profile of a merchant is a set of limits imposed on the daily/weekly/monthly transaction amounts. A low limit profile number denotes low limits on all transactions.
merchantcity string false City where the merchant is registered. Without merchantip this field becomes important. Any city is accepted.
merchantcountry string false Countrycode of country where the merchant is registered.Only ISO 3166-1 numeric country codes are accepted
merchantemail string false The email address of the merchant.
merchantpostalcode string false Postal code where the merchant is registered. Without merchantip this field becomes important. Any postal code is accepted.
merchantstatecode string false State where the merchant is registered. Without merchantip this field becomes important. Any state code is accepted.
merchanturl string false URL of merchant’s site or page where transaction took place. Any URL is accepted.
mid string false Unique identifier that is assigned to a merchant account by the payment processor. An important distinction to make is that the MID does not uniquely identify a merchant, a MID only uniquely identifies the merchant account. Reason is that one merchant can have multiple MIDs, as a merchant can for example have different merchant accounts for different arms of the business.
ocptenabled string false Indicates if ocpt is enabled for this merchant. When ocpt is enabled, payout back to the cardholder is supported.
processor string false A payment processor is a company (often a third party) appointed by a merchant to handle transactions from various channels such as credit cards and debit cards for merchant acquiring banks.
shopperemail string false The email address of the shopper.
shoppername string false The name or identifier of the shopper. Any name or unique identifier is accepted.
shopperphonenumber string false The phone number of the shopper.
submerchant string false The name or identifier of the submerchant, which is a merchant that processes under a payment service provider or payment facilitator. These services use one merchant account to process the transactions of many sub-merchants, thereby eliminating the need for each sub-merchant to open and maintain a fully-fledged merchant account. Any name or unique identifier is accepted.
terminaltype string false The type of unattended POS terminal, also known as Cardholder-Activated Terminal (CAT) types. Accepted values are:
- cat1: Automated Dispensing Machine
- cat2: Self Service Terminal
- cat3: Limited Amount Terminal
- cat4: InFlight Terminal
- cat6: Electronic Commerce
- cat7: Transponder
- cat9: MPOS (mobile POS)
- none: Unknown.
transactioncountry string false Countrycode of country where the card holder's device is located. Without transactionip this field becomes important. Only ISO 3166-1 numeric country codes are accepted.
transactionpostalcode string false Postal code where the card holder's device is located. Without transactionip this field becomes important.
transactionstatecode string false State where the card holder's device is located. Without transactionip this field becomes important.
transactionstreetaddress string false Street address where the card holder's device is located.. Without transactionip this field becomes important.
avsresult string true The result of Address Verification Service (AVS) checks, used to verify the address of a person claiming to own a credit card. Accepted values are:
- A: Addresses match/ZIP codes do not.
- B: Street addresses match, but ZIP codes failed verification due to incompatible formats.
- C: Street address and postal/ZIP codes failed verification due to incompatible formats.
- D: Street addresses and postal/ZIP codes match (VISA).
Customer name incorrect, ZIP codes match (AMEX / JCB).
- E: Customer name incorrect, billing address and ZIP code match.
- F: Street addresses and postal codes match (VISA). Customer name incorrect, billing address matches (AMEX / JCB).
- G: Address information failed verification for international transaction.
- I: Address information failed verification.
- K: Customer name matches.
- L: Customer name and ZIP code match.
- M: Street addresses and postal/ZIP codes match.
- N: No match.
- O: Customer name and billing address match.
- P: Postal/ZIP codes match. Acquirer sent both postal/ZIP code and street address, but street address failed verification due to incompatible formats.
- R: Retry: System unavailable or timed out. Issuer ordinarily performs address verification but was unavailable.
- S: AVS not supported.
- T: Nine-digit zip code matches, address does not match.
- U: Information is unavailable.
- W: For U.S. Addresses, nine-digit postal code matches, address does not; for address outside the U.S. postal code matches, address does not (MasterCard / Discover). Customer name, billing address, and postal code are all correct ( AMEX / JCB).
- X: For U.S. addresses, nine-digit postal code and addresses matches; for addresses outside the U.S., postal code and address match.
- Y: Street address and postal/ZIP match.
- Z: Postal/ZIP match, street addresses do not match or street address not included in request.
- none: Unknown.
cvvresult string true Contains the CVV response returned by the processor. Accepted values:
- M: CVV2 Match.
- N: CVV2 No Match.
- P: Not processed.
- S: CVV2 should be on the card.
- U: Issuer does not participate in CVV2 service, or participates but has not provided the encryption keys, or both.
- X: No response from association.
- none: Unknown.
eci string true The Electronic Commerce Indicator (ECI) value returned by the issuer. Different card schemes use different values. Accepted values are:

Visa / American Express / JCB / Discover / Diners
- 05: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.
- 06: Either cardholder or card issuing bank is not 3D enrolled.
- 07: Authentication is unsuccessful or not attempted.
- none: Unknown.

MasterCard
- 02: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.
- 01: Either cardholder or card issuing bank is not 3D enrolled.
- 00: Authentication is unsuccessful or not attempted.
- none: Unknown.
responsecode string true The authorization response code returned by the Payment Service Provider (PSP) or issuer. The code must be 2 character ISO8583-1987 response.
success string true Indicates if the transaction was successfully completed with no technical error. Accepted values are: true, false or none.
- true: Successfully completed.
- false: Unsuccessfully completed..
- none: Unknown.
authresult string false Indicates if the transaction successfully passed all authentication and authorization checks. Accepted values are:
- fail: failed authentication and authorization.
- success: successfull authentication and authorization.
- none: Unknown.
cavvresult string false The Cardholder Authentication Verification Value (CAVV) is a value that allows VISA to validate the integrity of the Verified by Visa (VbV) transaction data for VISA 3Ds transactions. Accepted values are:
- 0: CAVV authentication results invalid, no verification performed.
- 1: CAVV failed verification (authentication), Issuer approves authorization.
- 2: CAVV passed verification (authentication), Issuer approves authorization.
- 3: CAVV passed verification (attempt), Issuer approves authorization.
- 4: CAVV failed verification (attempt), Issuer approves authorization.
- 5: Not Used - Reserved.
- 6: CAVV failed verification (VisaNet flag for Issuer not selected), Issuer approves authorization.
- 7: CAVV failed verification (attempt), Issuer approves authorization.
- 8: CAVV passed verification (attempt), Issuer approves authorization.
- 9: CAVV failed verification (attempt), Issuer approves authorization.
- A: CAVV passed verification (attempt), Issuer approves authorization.
- B: CAVV passed verification (authentication).
- C: CAVV failed verification (attempt).
- D: CAVV failed verification (authentication).
- none: Unknown.
ddresult string false The dynamic descriptor result returned by the processor is the text that represents businesses on bank account statements. Can be up to 22 characters long.
gatewaydeclinereason string false The decline reason returned by the payment gateway when a transaction cannot be completed. Declinecodes differ from gateway to gateway, therefore the reason of the decline is preferred. Any declinereason is accepted. E.g. Application Incomplete, Duplicate, Fraud, Risk Thresholds, Card Disabled.
ucafindicator string false The Universal Cardholder Authentication (UCAF) indicator indicates to what extend the UCAF data collection is supported for MasterCard 3DS transactions. Accepted values are:
- 0: UCAF data collection is not supported by the merchant.
- 1: UCAF data collection is supported by the merchant, and UCAF data may be present and contain an attempted AAV.
- 2: UCAF data collection is supported by the merchant and UCAF data must be present and contain a fully authenticated AAV.
- none: Unknown.

Responses

Status Meaning Description Schema
200 OK A successful response Prediction
default Default A problem Problem

Prediction

Represents the prediction of Fraudio`s AI regarding the transaction you just scored.

Properties

200 OK Response

{
  "Score": "0.54",
  "Transaction_ID": "0f48djmm"
  "Fraudio_Transaction_ID": "customer-placeholder-0f48djmm",
  "Recommendation":"yellow",
  "Notes": "Default values were used for the following missing fields: Important fields: acceptorip, eci, recurring. Optional fields: acceptorpostalcode, avsused."
}
Name Type Required Description
Score string true The numerical score generated by Fraudio for this transaction
Transaction_ID string true The transactionid of the payment you just submitted to the fraud score endpoint
Fraudio_Transaction_ID string true The ID generated by Fraudio for this transaction
Recommendation string true The "traffic light" recommendation generated by Fraudio for this transaction
Notes string true Additional notes regarding the response

Post-Authorization Backfill

Code samples

curl -X POST https://api.fraudio.com/v1/transactions/post-auth \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"customer": "customer-placeholder","transactionid": "00000001","transactiontype": "capture","avsresult": "A","cvvresult": "S","eci": "02","responsecode": "05","success": "true","timestamp": 1646063615,"authresult": "success","cavvresult": "5","ddresult": "ZXC* Site Access 800-123-4567","gatewaydeclinereason": "Card Disabled","ucafindicator": "2"}'
import json
import os

import requests

post_auth_backfill_endpoint = 'https://api.fraudio.com/v1/transactions/post-auth'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Content-Type': 'application/json','Authorization': f'Bearer {access_token}'}
post_auth_data = {"customer": "customer-placeholder", "transactionid":"00000001","transactiontype":"capture","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","timestamp":1646063615,"authresult":"success","cavvresult":"5","ddresult":"ZXC* Site Access 800-123-4567","gatewaydeclinereason":"Card Disabled","ucafindicator":"2"}
r = requests.post(post_auth_backfill_endpoint, data=json.dumps(post_auth_data), headers=headers)
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class PostBackfill
{
    public static void main(String[] args)  throws IOException, URISyntaxException, InterruptedException
    {
        String postAuthBackfillEndpoint = "https://api.fraudio.com/v1/transactions/post-auth";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String postAuthData = "{\"customer\": \"customer-placeholder\",\"transactionid\":\"00000001\",\"transactiontype\":\"capture\",\"avsresult\":\"A\",\"cvvresult\":\"S\",\"eci\":\"02\",\"responsecode\":\"05\",\"success\":\"true\",\"timestamp\":1512828988826,\"authresult\":\"success\",\"cavvresult\":\"5\",\"ddresult\":\"ZXC*SiteAccess800-123-4567\",\"gatewaydeclinereason\":\"CardDisabled\",\"ucafindicator\":\"2\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(postAuthBackfillEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(postAuthData))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + " Response Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $post_auth_endpoint = 'https://api.fraudio.com/v1/transactions/post-auth';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $post_auth_data = '{"customer": "customer-placeholder","transactionid": "00000001","transactiontype": "capture","avsresult": "A","cvvresult": "S","eci": "02","responsecode": "05","success": "true","timestamp": 1646063615,"authresult": "success","cavvresult": "5","ddresult": "ZXC* Site Access 800-123-4567","gatewaydeclinereason": "Card Disabled","ucafindicator": "2"}';
my $req = HTTP::Request -> new(POST => $post_auth_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($post_auth_data);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $fraud_score_endpoint = 'https://api.fraudio.com/v1/transactions/post-auth';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $post_auth_data = '{"customer": "customer-placeholder","transactionid": "00000001","transactiontype": "capture","avsresult": "A","cvvresult": "S","eci": "02","responsecode": "05","success": "true","timestamp": 1646063615,"authresult": "success","cavvresult": "5","ddresult": "ZXC* Site Access 800-123-4567","gatewaydeclinereason": "Card Disabled","ucafindicator": "2"}';
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $post_auth_data
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($fraud_score_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/v1/transactions/post-auth

Connecting to the post-authorization backfill endpoint allows you to backfill post-authorization data for the transactions that you previously scored through the fraud score endpoint.

Additional data is generated when a transaction goes through the authorization process - for example, noting whether 3DS or the CCV was used. We need to collect this data to input into our continuous improvement algorithms so that we can continue to deliver high-quality service.

You have already sent the transaction’s data pre-authorization to our fraud score endpoint. Now we need to know how these same transactions were treated by the credit/debit card issuer with regard to authorization - this is where the post-authorization backfill endpoint comes in.

In summary: the data generated when a transaction goes through the authorization process must be sent to the post-authorization backfill endpoint.

Parameters

Name In Type Required Description
body body Post-Auth Transaction true none

Post-Auth Transaction

Transaction event containing post-authorization information about the original pre-auth authorization event that was sent to the fraud score endpoint.

Properties

{
  "customer": "customer-placeholder",
  "transactionid": "00000001",
  "transactiontype": "auth",
  "avsresult": "A",
  "cvvresult": "S",
  "eci": "02",
  "responsecode": "05",
  "success": "true",
  "timestamp": 1646063615,
  "authresult": "success",
  "cavvresult": "5",
  "ddresult": "ZXC* Site Access 800-123-4567",
  "gatewaydeclinereason": "Card Disabled",
  "ucafindicator": "2"
}

Name Type Required Description
customer string true The name of the Fraudio customer making the API call.
transactionid string true The transaction ID is the identifier of the original transaction event that is being backfilled.
transactiontype string true The type of transaction event. Must match the transactiontype of the transaction you're backfilling.
avsresult string true The result of Address Verification Service (AVS) checks, used to verify the address of a person claiming to own a credit card. Accepted values are:
- A: Addresses match/ZIP codes do not.
- B: Street addresses match, but ZIP codes failed verification due to incompatible formats.
- C: Street address and postal/ZIP codes failed verification due to incompatible formats.
- D: Street addresses and postal/ZIP codes match (VISA).
Customer name incorrect, ZIP codes match (AMEX / JCB).
- E: Customer name incorrect, billing address and ZIP code match.
- F: Street addresses and postal codes match (VISA). Customer name incorrect, billing address matches (AMEX / JCB).
- G: Address information failed verification for international transaction.
- I: Address information failed verification.
- K: Customer name matches.
- L: Customer name and ZIP code match.
- M: Street addresses and postal/ZIP codes match.
- N: No match.
- O: Customer name and billing address match.
- P: Postal/ZIP codes match. Acquirer sent both postal/ZIP code and street address, but street address failed verification due to incompatible formats.
- R: Retry: System unavailable or timed out. Issuer ordinarily performs address verification but was unavailable.
- S: AVS not supported.
- T: Nine-digit zip code matches, address does not match.
- U: Information is unavailable.
- W: For U.S. Addresses, nine-digit postal code matches, address does not; for address outside the U.S. postal code matches, address does not (MasterCard / Discover). Customer name, billing address, and postal code are all correct ( AMEX / JCB).
- X: For U.S. addresses, nine-digit postal code and addresses matches; for addresses outside the U.S., postal code and address match.
- Y: Street address and postal/ZIP match.
- Z: Postal/ZIP match, street addresses do not match or street address not included in request.
- none: Unknown.
cvvresult string true Contains the CVV response returned by the processor. Accepted values:
- M: CVV2 Match.
- N: CVV2 No Match.
- P: Not processed.
- S: CVV2 should be on the card.
- U: Issuer does not participate in CVV2 service, or participates but has not provided the encryption keys, or both.
- X: No response from association.
- none: Unknown.
eci string true The Electronic Commerce Indicator (ECI) value returned by the issuer. Different card schemes use different values. Accepted values are:

Visa / American Express / JCB / Discover / Diners
- 05: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.
- 06: Either cardholder or card issuing bank is not 3D enrolled.
- 07: Authentication is unsuccessful or not attempted.
- none: Unknown.

MasterCard
- 02: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.
- 01: Either cardholder or card issuing bank is not 3D enrolled.
- 00: Authentication is unsuccessful or not attempted.
- none: Unknown.
responsecode string true The authorization response code returned by the Payment Service Provider (PSP) or issuer. The code must be 2 character ISO8583-1987 response.
success string true Indicates if the transaction was successfully completed with no technical error. Accepted values are: true, false or none.
- true: Successfully completed.
- false: Unsuccessfully completed..
- none: Unknown.
timestamp number true The time UTC at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted.
authresult string false Indicates if the transaction successfully passed all authentication and authorization checks. Accepted values are:
- fail: failed authentication and authorization.
- success: successful authentication and authorization.
- none: Unknown.
cavvresult string false The Cardholder Authentication Verification Value (CAVV) is a value that allows VISA to validate the integrity of the Verified by Visa (VbV) transaction data for VISA 3Ds transactions. Accepted values are:
- 0: CAVV authentication results invalid, no verification performed.
- 1: CAVV failed verification (authentication), Issuer approves authorization.
- 2: CAVV passed verification (authentication), Issuer approves authorization.
- 3: CAVV passed verification (attempt), Issuer approves authorization.
- 4: CAVV failed verification (attempt), Issuer approves authorization.
- 5: Not Used - Reserved.
- 6: CAVV failed verification (VisaNet flag for Issuer not selected), Issuer approves authorization.
- 7: CAVV failed verification (attempt), Issuer approves authorization.
- 8: CAVV passed verification (attempt), Issuer approves authorization.
- 9: CAVV failed verification (attempt), Issuer approves authorization.
- A: CAVV passed verification (attempt), Issuer approves authorization.
- B: CAVV passed verification (authentication).
- C: CAVV failed verification (attempt).
- D: CAVV failed verification (authentication).
- none: Unknown.
ddresult string false The dynamic descriptor result returned by the processor is the text that represents businesses on bank account statements. Can be up to 22 characters long.
gatewaydeclinereason string false The decline reason returned by the payment gateway when a transaction cannot be completed. Decline codes differ from gateway to gateway, therefore the reason of the decline is preferred. Any decline reason is accepted. E.g. Application Incomplete, Duplicate, Fraud, Risk Thresholds, Card Disabled.
ucafindicator string false The Universal Cardholder Authentication (UCAF) indicator indicates to what extend the UCAF data collection is supported for MasterCard 3DS transactions. Accepted values are:
- 0: UCAF data collection is not supported by the merchant.
- 1: UCAF data collection is supported by the merchant, and UCAF data may be present and contain an attempted AAV.
- 2: UCAF data collection is supported by the merchant and UCAF data must be present and contain a fully authenticated AAV.
- none: Unknown.

Responses

Status Meaning Description Schema
200 OK A successful response PostAuthSuccess
default Default A problem Problem

PostAuthSuccess

Post-backfill API response that indicates that the operation succeeded.

Properties

200 OK Response

{
  "Message": "string",
  "Status": "string"
}
Name Type Required Description
Message string true The response message
Status string true The HTTP Response status code

Chargebacks

Code samples

curl -X POST https://api.fraudio.com/v1/transactions/chargebacks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"data":[{"chargebackid": "1003125","chargebackreason": "Payment was not authorized","fraudimportdate": 1602868410.143105,"fraudreason": "Suspicious account number used","reporttype": "1st chargeback","merchant": "346888e3-a907-4d2b-d286-1fbc0bb988d9","timestamp": 1646063615,"transactionid": "00000001"}]}'
import json
import os

import requests

chargebacks_endpoint = 'https://api.fraudio.com/v1/transactions/chargebacks'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
chargeback = {"data":[{"chargebackid": "1003125","chargebackreason": "Payment was not authorized","fraudimportdate": 1602868410.143105,"fraudreason": "Suspicious account number used","reporttype": "1st chargeback","merchant": "346888e3-a907-4d2b-d286-1fbc0bb988d9","timestamp": 1646063615,"transactionid": "00000001"}]}
r = requests.post(chargebacks_endpoint, data=json.dumps(chargeback), headers=headers)
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Chargebacks
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String chargebacksEndpoint = "https://api.fraudio.com/v1/transactions/chargebacks";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String chargeback = "{\"data\":[{\"chargebackid\":\"1003125\",\"chargebackreason\":\"Payment was not authorized\",\"fraudimportdate\":1602868410.143105,\"fraudreason\":\"Suspicious account number used\",\"reporttype\":\"1st chargeback\",\"merchant\":\"346888e3-a907-4d2b-d286-1fbc0bb988d9\",\"timestamp\":1602668123.456,\"transactionid\":\"00000001\"}]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(chargebacksEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(chargeback))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $chargebacks_endpoint = 'https://api.fraudio.com/v1/transactions/chargebacks';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $chargeback = '{"data":[{"chargebackid": "1003125","chargebackreason": "Payment was not authorized","fraudimportdate": 1602868410.143105,"fraudreason": "Suspicious account number used","reporttype": "1st chargeback","merchant": "346888e3-a907-4d2b-d286-1fbc0bb988d9","timestamp": 1646063615,"transactionid": "00000001"}]}';
my $req = HTTP::Request -> new(POST => $chargebacks_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($chargeback);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $chargebacks_endpoint = 'https://api.fraudio.com/v1/transactions/chargebacks';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $chargeback = '{"data":[{"chargebackid": "1003125","chargebackreason": "Payment was not authorized","fraudimportdate": 1602868410.143105,"fraudreason": "Suspicious account number used","reporttype": "1st chargeback","merchant": "346888e3-a907-4d2b-d286-1fbc0bb988d9","timestamp": 1646063615,"transactionid": "00000001"}]}';
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $chargeback
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($chargebacks_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/v1/transactions/chargebacks

The chargebacks endpoint is an API endpoint to which you must send your fraud reports, consisting of chargebacks and fraud notification. Fraud reports can be sent either individually or in batch to the Chargebacks endpoint.

Parameters

Name In Type Required Description
body body Fraud reports true none

Fraud Reports

A fraud report is the report that is filed after a consumer disputes the transaction. The process is initiated by either the merchant or the cardholder`s issuing bank.

Properties
{
  "data": [
    {
      "transactionid": "00000001",
      "timestamp": 1646063615,
      "merchant": "346888E3-A907-4D2B-D286-1FBC0BB988D9",
      "fraudimportdate": 1602868410.143105,
      "chargebackid": "1003125",
      "chargebackreason": "10.4",
      "fraudreason": "Suspicious account number used",
      "reporttype": "1st chargeback"
    }
  ]
}
Name Type Required Description
data [array] true none
transactionid string true The transaction ID is the unique identifier of the original transaction event.
timestamp number true Timestamp (UTC) of the original transaction that led to the chargeback. Only Unix Timestamps are accepted.
merchant string false The name or identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
fraudimportdate double false Timestamp when a dispute was opened.
chargebackid string false External ID of this chargeback, unique for the customer.
chargebackreason string false Reason for the chargeback.
fraudreason string false Reason why the transaction was fraudulent.
reporttype string false The type of fraud report. Some possible values are fraud notification, 1st chargeback, information supplied, reversed chargeback, pre-arbitration, 2nd chargeback. Details about each possible value below.
- fraud notification: Fraud activity reported by the (cardholder's) bank. Examples are Visa's TC40 files and MasterCard's SAFE files.
- 1st chargeback: First stage of the chargeback where the disputed amount is withdrawn from the merchant's account.
- information supplied: Defense documents against the 1st chargeback are supplied.
- reversed chargeback: The disputed amount is transferred back to the merchant's account.
- pre-arbitration: Card scheme evaluates the defense.
- 2nd chargeback: 2nd and definite chargeback where the disputed amount is withdrawn from the merchant's account.

Responses

200 OK Response

{
  "created": 2,
  "deleted": 0,
  "errors": 2,
  "ignored": 5,
  "received": 0,
  "updated": 0
}
Status Meaning Description Schema
200 OK A successful response Data collection response
default Default default Problem

Account Bank Transfers

Code samples

curl -X POST https://api.fraudio.com/v1/transactions/account-bank-transfers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"data":[{"transactionid":"00000001","transactiontype":"withdrawal","timestamp":1646063615,"merchant":"853CA6B7-79BB-DE46-049F-FC2603FAC59F","walletid":"893067473928","originalamount":1.1,"currency":"978","iban":"NL51INGB40123456789876"}]}'
import json
import os

import requests

account_bank_transfers_endpoint = 'https://api.fraudio.com/v1/transactions/account-bank-transfers'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
account_bank_transfer = {"data":[{"sender_transactionid": "0000023232","receiver_transactionid": "receiver_transactionid","transactionid":"a9899d6a-46a8-4574-a881-3e7786ba69","timestamp":1646063615,"transactiontype":"withdrawal","sistertransactionid":"00000001","merchant":"CFBE1FC6-3069-B390-4287-F0D653ACC3CC","walletid":"783067473928","originalamount":1.1,"currency":"978"}]}
r = requests.post(account_bank_transfers_endpoint, data=json.dumps(account_bank_transfer), headers=headers)
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class AccountBankTransfers
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String accountBankTransfersEndpoint = "https://api.fraudio.com/v1/transactions/account-bank-transfers";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String accountBankTransfer = "{\"data\":[{\"transactionid\":\"00000001\",\"transactiontype\":\"withdrawal\",\"timestamp\":1602668123.456,\"merchant\":\"853CA6B7-79BB-DE46-049F-FC2603FAC59F\",\"walletid\":\"893067473928\",\"originalamount\":1.1,\"currency\":\"978\",\"iban\":\"NL51INGB40123456789876\"}]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(accountBankTransfersEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(accountBankTransfer))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $account_bank_transfers_endpoint = 'https://api.fraudio.com/v1/transactions/account-bank-transfers';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $account_bank_transfer = '{"data":[{"transactionid":"00000001","transactiontype":"withdrawal","timestamp":1646063615,"merchant":"853CA6B7-79BB-DE46-049F-FC2603FAC59F","walletid":"893067473928","originalamount":1.1,"currency":"978","iban":"NL51INGB40123456789876"}]}';
my $req = HTTP::Request -> new(POST => $account_bank_transfers_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($account_bank_transfer);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $account_bank_transfers_endpoint = 'https://api.fraudio.com/v1/transactions/account-bank-transfers';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $account_bank_transfer = '{"data":[{"transactionid":"00000001","transactiontype":"withdrawal","timestamp":1646063615,"merchant":"853CA6B7-79BB-DE46-049F-FC2603FAC59F","walletid":"893067473928","originalamount":1.1,"currency":"978","iban":"NL51INGB40123456789876"}]}';
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $account_bank_transfer
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($account_bank_transfers_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/v1/transactions/account-bank-transfers

The Account Bank Transfer endpoint allows you to upload withdrawals, incoming and outgoing bank transfers in and out of your merchants' bank accounts.

Parameters

Name In Type Required Description
body body Account bank transfers true none

Account Bank Transfers

Transfer of money in and out of the merchant's bank account.

Properties
{
  "transactionid": "00000001",
  "transactiontype": "withdrawal",
  "timestamp": 1646063615,
  "merchant": "853CA6B7-79BB-DE46-049F-FC2603FAC59F",
  "walletid": "893067473928",
  "originalamount": 1.1,
  "currency": "978",
  "iban": "NL51INGB40123456789876"
}
Name Type Required Description
data [array] true none
transactionid string true The transaction ID is the unique identifier of the transaction event.
transactiontype string true The type of transaction. Possible values are: incoming_bank_transfer, outgoing_bank_transfer and withdrawal. Details about each possible value below.

incoming_bank_transfer: Transfer of credit into the merchant's bank account.
outgoing_bank_transfer: Transfer of credit out of the merchant's bank account.
withdrawal: Cash withdrawal from the merchant's bank account.
timestamp number true The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted.
merchant string false The name or identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
walletid string false External ID of the wallet used.
originalamount number false Amount/value of the transaction in the original currency. Must be a nonnegative value.
currency string false Numerical currency code of the currency used for the transaction (ISO 4217)
iban string false IBAN number for the recipient of the bank transfer.

Responses

200 OK Response

{
  "created": 2,
  "deleted": 0,
  "errors": 2,
  "ignored": 5,
  "received": 0,
  "updated": 0
}
Status Meaning Description Schema
200 OK A successful response Data collection response
default Default default Problem

Inter Account Transfers

Code samples

curl -X POST https://api.fraudio.com/v1/transactions/inter-account-transfers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"data":[{"sender_transactionid": "sender_transactionid","receiver_transactionid": "receiver_transactionid","transactionid":"00000001","timestamp":1646063615,"transactiontype":"incoming_wallet_transfer","sistertransactionid":"00000001","merchant":"CFBE1FC6-3069-B390-4287-F0D653ACC3CC","walletid":"783067473928","originalamount":1.1,"currency":"978"}]}'
import json
import os

import requests

inter_account_transfers_endpoint = 'https://api.fraudio.com/v1/transactions/inter-account-transfers'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
inter_account_transfer = {"data":[{"sender_transactionid": "sender_transactionid","receiver_transactionid": "receiver_transactionid","transactionid":"00000001","timestamp":1646063615,"transactiontype":"incoming_wallet_transfer","sistertransactionid":"00000001","merchant":"CFBE1FC6-3069-B390-4287-F0D653ACC3CC","walletid":"783067473928","originalamount":1.1,"currency":"978"}]}
r = requests.post(inter_account_transfers_endpoint, data=json.dumps(inter_account_transfer), headers=headers)
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class InterAccountTransfers
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String interAccountTransfersEndpoint = "https://api.fraudio.com/v1/transactions/inter-account-transfers";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String interAccountTransfer = "{\"data\":[{\"sender_transactionid\": \"sender_transactionid\",\"receiver_transactionid\": \"receiver_transactionid\",\"transactionid\":\"00000001\",\"timestamp\":1646063615,\"transactiontype\":\"incoming_wallet_transfer\",\"sistertransactionid\":\"00000001\",\"merchant\":\"CFBE1FC6-3069-B390-4287-F0D653ACC3CC\",\"walletid\":\"783067473928\",\"originalamount\":1.1,\"currency\":\"978\"}]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(interAccountTransfersEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(interAccountTransfer))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $inter_account_transfers_endpoint = 'https://api.fraudio.com/v1/transactions/inter-account-transfers';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $inter_account_transfer = '{"data":[{"sender_transactionid": "sender_transactionid","receiver_transactionid": "receiver_transactionid","transactionid":"00000001","timestamp":1646063615,"transactiontype":"incoming_wallet_transfer","sistertransactionid":"00000001","merchant":"CFBE1FC6-3069-B390-4287-F0D653ACC3CC","walletid":"783067473928","originalamount":1.1,"currency":"978"}]}';
my $req = HTTP::Request -> new(POST => $inter_account_transfers_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($inter_account_transfer);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $inter_account_transfers_endpoint = 'https://api.fraudio.com/v1/transactions/inter-account-transfers';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $inter_account_transfer = '{"data":[{"sender_transactionid": "sender_transactionid","receiver_transactionid": "receiver_transactionid","transactionid":"00000001","timestamp":1646063615,"transactiontype":"incoming_wallet_transfer","sistertransactionid":"00000001","merchant":"CFBE1FC6-3069-B390-4287-F0D653ACC3CC","walletid":"783067473928","originalamount":1.1,"currency":"978"}]}';
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $inter_account_transfer
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($inter_account_transfers_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/v1/transactions/inter-account-transfers

The Inter Account Transfers endpoint allows you to upload wallet transfers in, out and between your merchants' wallets.

Parameters

Name In Type Required Description
body body Inter Account Transfers true none

Inter Account Transfer

Transfer of money in, out or between your merchants' wallets.

Properties
{"data":
  [
    {
      "transactionid": "00000001",
      "timestamp": 1646063615,
      "transactiontype": "incoming_wallet_transfer",
      "sistertransactionid": "00000001",
      "merchant": "CFBE1FC6-3069-B390-4287-F0D653ACC3CC",
      "walletid": "783067473928",
      "originalamount": 1.1,
      "currency": "978"
    }
  ]
}
Name Type Required Description
data [array] true none
transactionid string true The transaction ID is the unique identifier of the transaction event.
timestamp number true The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted.
transactiontype string true The type of transaction. Possible values are: incoming_wallet_transfer and outgoing_wallet_transfer. Details about each possible value below.

incoming_wallet_transfer: Transfer of credit into the merchant's wallet account.
outgoing_wallet_transfer: Transfer of credit out of the merchant's wallet account.
sistertransactionid string true If this is an incoming transfer, sistertransactionid is the transactionid for the corresponding outgoing transfer and vice versa.
merchant string false The name or identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
walletid string false External ID of the merchant wallet.
originalamount number false Amount/value of the transaction in the original currency. Must be a nonnegative value.
currency string false Numerical currency code of the currency used for the transaction (ISO 4217)

Responses

200 OK Response

{
  "created": 2,
  "deleted": 0,
  "errors": 2,
  "ignored": 5,
  "received": 0,
  "updated": 0
}
Status Meaning Description Schema
200 OK A successful response Data collection response
default Default default Problem

Merchant Evaluations

Code samples

curl -X POST https://api.fraudio.com/v1/merchants/risk-evaluations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"data":[{"merchant":"eec1d18f-a714-491d-9721-4600ba7c44c3","evaluation":"suspicious","timestamp":1646063615,"comment":"No Action - False Alarm"}]}'
import json
import os

import requests

merchant_risk_evaluations_endpoint = 'https://api.fraudio.com/v1/merchants/risk-evaluations'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
merchant_evaluation = {"data":[{"merchant":"eec1d18f-a714-491d-9721-4600ba7c44c3","evaluation":"suspicious","timestamp":1646063615,"comment":"No Action - False Alarm"}]}
r = requests.post(merchant_risk_evaluations_endpoint, data=json.dumps(merchant_evaluation), headers=headers)
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class MerchantsEvaluation
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String merchantsEvaluationsEndpoint = "https://api.fraudio.com/v1/merchants/risk-evaluations";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String merchantEvaluation = "{\"data\":[{\"merchant\":\"eec1d18f-a714-491d-9721-4600ba7c44c3\",\"evaluation\":\"falsepositive\",\"timestamp\":1602668410.143105,\"comment\":\"No Action - False Alarm\"}]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(merchantsEvaluationsEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(merchantEvaluation))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $merchants_risk_evaluation_endpoint = 'https://api.fraudio.com/v1/merchants/risk-evaluations';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $merchant_evaluation = '{"data":[{"merchant":"eec1d18f-a714-491d-9721-4600ba7c44c3","evaluation":"suspicious","timestamp":1646063615,"comment":"No Action - False Alarm"}]}';
my $req = HTTP::Request -> new(POST => $merchants_risk_evaluation_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($merchant_evaluation);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $merchants_risk_evaluations_endpoint = 'https://api.fraudio.com/v1/merchants/risk-evaluations';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $merchant_evaluation = '{"data":[{"merchant":"eec1d18f-a714-491d-9721-4600ba7c44c3","evaluation":"suspicious","timestamp":1646063615,"comment":"No Action - False Alarm"}]}';
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $merchant_evaluation
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($merchants_risk_evaluations_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/merchants/risk-evaluations

Allows you to upload the outcome of investigations of merchants that you have evaluated. This helps us incorporate your feedback into our AI models to improve the merchant initiated fraud detection product.

Parameters

Name In Type Required Description
body body Merchant evaluations true none

Merchant Evaluations

Your evaluation regarding the specified merchant. The evaluation field of this data structure is flexible. Get in touch with us in order to agree on best format for your use case.

Properties
{"data":
  [
    {
      "merchant": "eec1d18f-a714-491d-9721-4600ba7c44c3",
      "evaluation": "fraudster",
      "timestamp": 1646063615,
      "comment": "Money launderer."
    }
  ]
}
Name Type Required Description
data [array] true none
merchant string true The name or identifier of the merchant that is evaluated. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
evaluation string true Internal evaluation. Valid values are:
-fraudster
-suspicious
-legitimate
timestamp number true The UTC time at which the merchant evaluation was done. Only Unix Timestamps are accepted.
comment string false Comment to provide more detailed information about the merchant evaluation. For example, if the merchant is suspected to be involved in money laundering, it is important to note that here.

Responses

200 OK Response

{
  "created": 2,
  "deleted": 0,
  "errors": 2,
  "ignored": 5,
  "received": 0,
  "updated": 0
}
Status Meaning Description Schema
200 OK A successful response Data collection response
default Default default Problem

Merchant Account Information

Code samples

curl -X POST https://api.fraudio.com/v1/merchants/account-information \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"data":[{"merchant":"Fred & Freddy Sports Store","walletid":"1121451","mcccode":"5969","registrationdate":1646063615.143105,"acquirer":"Acquirer X","acquirercountry":"056","merchantip":"34.231.107.3","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b 3hh","merchantstatecode":"GA","merchantstreetadress":"29 Ravenscroft, Covingham","merchanturl":"www.foreverliving.com","ocptenabled":true}]}'
import json
import os

import requests

merchant_account_information_endpoint = 'https://api.fraudio.com/v1/merchants/account-information'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
merchant_account = {"data":[{"merchant":"Fred & Freddy Sports Store","walletid":"1121451","mcccode":"5969","registrationdate":1646063615.143105,"acquirer":"Acquirer X","acquirercountry":"056","merchantip":"34.231.107.3","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b 3hh","merchantstatecode":"GA","merchantstreetadress":"29 Ravenscroft, Covingham","merchanturl":"www.foreverliving.com","ocptenabled": True}]}
r = requests.post(merchant_account_information_endpoint, data=json.dumps(merchant_account), headers=headers)
print(r.json())
package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class MerchantsAccountInformation
{
    public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
    {
        String merchantAccountInformationEndpoint = "https://api.fraudio.com/v1/merchants/account-information";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String merchantAccount = "{\"data\":[{\"merchant\":\"Fred & Freddy Sports Store\",\"walletid\":\"1121451\",\"mcccode\":\"5969\",\"registrationdate\":1646063615.143105,\"acquirer\":\"Acquirer X\",\"acquirercountry\":\"056\",\"merchantip\":\"34.231.107.3\",\"kyclevel\":\"5\",\"kyclevelnorm\":0.5,\"limitprofile\":\"5\",\"merchantcity\":\"London\",\"merchantcountry\":\"528\",\"merchantemail\":\"support@fraudio.com\",\"merchantpostalcode\":\"w1b 3hh\",\"merchantstatecode\":\"GA\",\"merchantstreetadress\":\"29 Ravenscroft, Covingham\",\"merchanturl\":\"www.foreverliving.com\",\"ocptenabled\":true}]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(merchantAccountInformationEndpoint))
            .header("Authorization", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(merchantAccount))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + "\nResponse Body: " + responseBody);
    }
}
use LWP::UserAgent;
use HTTP::Request::Common;

my $merchants_account_information_endpoint = 'https://api.fraudio.com/v1/merchants/account-information';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $merchant_account = '{"data":[{"merchant":"Fred & Freddy Sports Store","walletid":"1121451","mcccode":"5969","registrationdate":1646063615.143105,"acquirer":"Acquirer X","acquirercountry":"056","merchantip":"34.231.107.3","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b 3hh","merchantstatecode":"GA","merchantstreetadress":"29 Ravenscroft, Covingham","merchanturl":"www.foreverliving.com","ocptenabled": true}]}';
my $req = HTTP::Request -> new(POST => $merchants_account_information_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($merchant_account);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
  $merchants_account_information_endpoint = 'https://api.fraudio.com/v1/merchants/account-information';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $merchant_account = '{"data":[{"merchant":"Fred & Freddy Sports Store","walletid":"1121451","mcccode":"5969","registrationdate":1646063615.143105,"acquirer":"Acquirer X","acquirercountry":"056","merchantip":"34.231.107.3","kyclevel":"5","kyclevelnorm":0.5,"limitprofile":"5","merchantcity":"London","merchantcountry":"528","merchantemail":"support@fraudio.com","merchantpostalcode":"w1b 3hh","merchantstatecode":"GA","merchantstreetadress":"29 Ravenscroft, Covingham","merchanturl":"www.foreverliving.com","ocptenabled": true}]}';
  $options = [
    'http' => [
        'header'  => "Authorization: Bearer $access_token\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => $merchant_account
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($merchants_account_information_endpoint, false, $context);
  print $result;
?>

POST https://api.fraudio.com/merchants/account-information

Allows to upload information about merchants to Fraudio's data centers. Through this endpoint you will be sending us in real-time any information regarding your merchants as soon as you are aware of it. Fraudio's AI uses this information to scan your merchants for merchant initiated fraud.

Parameters

Name In Type Required Description
body body Merchants true none

Merchants

A merchant is a seller of goods and/or services who accepts card transactions as payments and pays a transaction facilitation fee to the acquirer.

Properties

{
  "data": [
    {
      "merchant": "Fred & Freddy Sports Store",
      "walletid": "1121451",
      "mcccode": "5969",
      "registrationdate": 100041643253.143105,
      "acquirer": "Acquirer X",
      "acquirercountry": "056",
      "merchantip": "34.231.107.3",
      "kyclevel": "5",
      "kyclevelnorm": 0.5,
      "limitprofile": "5",
      "merchantcity": "London",
      "merchantcountry": "528",
      "merchantemail": "support@fraudio.com",
      "merchantpostalcode": "w1b 3hh",
      "merchantstatecode": "GA",
      "merchantstreetadress": "29 Ravenscroft, Covingham",
      "merchanturl": "www.foreverliving.com",
      "ocptenabled": "true",
      "submerchant": "Shoestore X"
    }
  ]
}
Name Type Required Description
data [array] true none
merchant string true The name or identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
walletid string true The wallet ID is the unique identifier of the wallet. Any unique identifier is accepted.
mcccode string true A Merchant Category Code (MCC) is a four-digit number listed for financial services. An MCC is used to classify a business by the types of goods or services it provides. Only ISO 18245 mcc codes are accepted.
registrationdate double true The time UTC at which the merchant got registered. Only Unix Timestamps are accepted.
acquirer string false The acquirer is a financial institution with whom the merchant has a bank account.
acquirercountry string false Countrycode of country where the acquirer is registered. Only ISO 3166-1 numeric country codes are accepted.
merchantip string false IP-address of the merchant, so IP where the merchant is registered. There is a difference between acceptorip and merchantip: acceptorip is the location of the merchant server on which the payment is received. So a merchant can have multiple acceptorips but only one merchantip.
kyclevel string false The Know-Your-Customer level of the merchant. Any indication level is accepted.
kyclevelnorm double false A normalized know-your-customer level of the merchant between 0 and 1, where 0 is a totally unknown and untrusted merchant and 1 is a fully known and absolutely trusted merchant.
limitprofile string false The limit profile of a merchant is a set of limits imposed on the daily/weekly/monthly transaction amounts. A low limit profile number denotes low limits on all transactions.
merchantcity string false City where the merchant is registered. Without merchantip this field becomes important. Any city is accepted.
merchantcountry string false Countrycode of country where the merchant is registered.Only ISO 3166-1 numeric country codes are accepted.
merchantemail string false The email address of the merchant.
merchantpostalcode string false Postal code where the merchant is registered. Without merchantip this field becomes important. Any postal code is accepted.
merchantstatecode string false State where the merchant is registered. Without merchantip this field becomes important. Any state code is accepted.
merchantstreetadress string false Street address where the merchant is registered. Without merchantip this field becomes important. Any street address is accepted.
merchanturl string false URL of merchant web site or page where transaction took place. Any URL is accepted.
ocptenabled string false Indicates if ocpt is enabled for this merchant. When ocpt is enabled, payout back to the cardholder is supported.
submerchant string false The name or identifier of the submerchant, which is a merchant that processes under a payment service provider or payment facilitator. These services use one merchant account to process the transactions of many sub-merchants, thereby eliminating the need for each sub-merchant to open and maintain a fully-fledged merchant account. Any name or unique identifier is accepted.

Responses

200 OK Response

{
  "created": 2,
  "deleted": 0,
  "errors": 2,
  "ignored": 5,
  "received": 0,
  "updated": 0
}
Status Meaning Description Schema
200 OK A successful response Data collection response
default Default default Problem

Fault tolerance

When interacting with Fraudio API, you will use standard HTTP messages. Most of the time you will receive 200 OK response codes. However, sometime a different code may be returned. This section focuses on unforeseen cases where the API does not perform well, such as during network outages and problems with newly released features. Of course, we will go to great lengths to avoid these, but nobody is perfect!

Setting Request Timeouts

The request timeout to use is very dependent on your use case. We propose the following by default:

Retry & Backoff

Only timeouts and network errors (as described above) are candidates for retrying the request. There are two kinds of retries that we recommend.

Immediate retries are suitable for time-sensitive requests. For example, when scoring a transaction is needed to process a live payment. Usually, an immediate retry will yield the same result as the first request. If the processing pipeline allows, we recommend 1 retry. A backoff period is not feasible, since the request is time sensitive.

Backfills apply when a request fails to yield a response in the required time. We consider something as a backfill when the data is coming in, much later than usual. For example when an outage occurs, the direct value of a scored transaction may be lost. A backfill can then inform Fraudio of missed events and allows our fraud models to work with complete and consistent data. If feasible, we recommend to use a queuing mechanism to store the requests yet to be fulfilled. Backfill attempts can be made with exponential backoff up to a maximum of 3 days.

Implementing backfills is inherently more complex than retries, because backfills can have long time delays. This is why many of our customers decide to use a manual backfill process, sharing data dumps on an as-needed basis.

Flood control

Our APIs and services are equipped to handle peak hour loads, and automatically scale up when capacity is reached. In regular operations, you do not need to worry about implementing flood controls.

During potential outages, there may be a queue buildup on the client side. When our services come back online, we recommend sending 10 concurrent requests until the queue is caught up. With mean latency, this should allow catching up at a rate of 100-200 transactions per second.

When sharing a large dump of data at once (e.g. a historical data dump or manual backfill), we have separate ways of processing these. Please discuss this with your contact at Fraudio if needed.

Sending data

All the data you send to Fraudio needs to be mapped to the Fraudio schema. As part of your integration you will need to send Fraudio your historical and live data.

Mapping data

The transaction data that you send to the API need to contain as many fields as possible from the schemas specified by each endpoint. To achieve this we recommend you to first map the data in batch.

When doing the mapping try to carefully go through our schemas and determine for every field if it matches a field in your dataset. If it does, you can add the field to your sample. When the names do not match, you adjust the name of the field in your sample.

Once you have gone through all fields and have gathered as much data fields as possible, you can go through the sample and make sure the data types and the accepted values also match with the Fraudio schema. The schemas contain details of all the data fields we use including their data types, data examples and descriptions. Our schemas are constantly being revised and updated with new data fields that we collect and use for our fraud scoring models.

After your Fraudio contact has confirmed that the mapping is correct, you can repeat the process that you did in batch for sending live transactions.

Historical and live Data

Historical data

You need to send us at least 24 months of historical data. Your historical data will need to consist of payment transactions and chargebacks. Fraudio uses this data to improve our fraud detection models allowing them to identify fraud cases.

Live data

To score your transactions, you will need to send Fraudio your live transaction data to the fraud score endpoint. The API requests should occur pre-authorization and require the accurate mapping of your data fields and values to the equivalent Fraudio data fields and values. Visit the FAQs to learn more about pre- and post-authorization data.

The data that we need can be divided in transaction data and batch data. When going live, the transaction data will need to be either processed in real time or it needs to be sent in batch on a frequent basis (we suggest every 12 to 24 hours). The batch data can be updated, say, every month.

How to transfer historical data to Fraudio?

To share files with Fraudio, you can upload them in CSV format to our dedicated storage on Amazon S3. We chose this storage solution because it is widely used, offers easy integrations and its data governance complies with security and privacy regulations.

On request, we will securely share a key ID and secret with you that you can use to upload files to a designated folder. There are many S3 clients available for uploading: the command-line interface (CLI), various GUIs and client-side libraries for most programming languages. Detailed information on such transfer are available in the batch transfer integration manual.

If you prefer other options to send your data please get in touch. And remember, the more data Fraudio receives, the better your fraud scores will be!

Transaction types

At Fraudio we need to receive different types of transactions to detect fraudulent transactions and merchants. Apart from regular payment data, we like to receive bank transfers, wallet transfers, withdrawals, payouts and other relevant deposits to track a merchant’s behaviour.

Payment data

A payment is always a series of transaction events. A series can for example be initiated by an authorization request, followed by an authentication/authorization response, capture, and refund. We will need to receive all these transaction events as separate entries.

Authorizations

Example (1)

{
"transactionid" : "4583409307",
"transactiontype" : "auth",
"cvvused": true,
"threedsused": true,
#rest of the fields
}

Example (2)

{
  "transactionid": "4583409307",
  "avsresult": "A",
  "cvvresult": "S",
  "eci": "02",
  "responsecode": "05",
  "success": "true",
  "timestamp": 1646063615,
  "authresult": "success",
  "cavvresult": "5",
  "ddresult": "ZXC* Site Access 800-123-4567",
  "gatewaydeclinereason": "Card Disabled",
  "ucafindicator": "2"
}

Authorizations often occur in two stages: pre- and post-authentication/authorization. Fraudio needs both these stages to provide you with the most accurate fraud scores. For the authorization request it is known which authentication and authorization checks are going to be used, but it is not known what the results of these checks will be.

On your right you have an example (1) of a transaction. This data type only contains pre-authentication/authorization information as you can observe from the example.

After the authorization request has been processed, an authentication/authorization response should follow. For batch and live data we will be asking you to aggregate the authentication and authorization response into one transaction event. This response will need to have the same transactionid as the original authorization request. Observe example (2) on your right to grasp how authentication and authorization have been aggregated into one transaction event.

For live transactions, the authorization response can be sent to the post-authorization backfill endpoint.

Captures, reversals, refunds, voids and top ups

Example (3)

{
"transactionid" : "4583409307",
"transactiontype" : "auth",
"parenttransactionid" : "none",
#rest of the fields
}

Example (4)

{
"transactionid" : "5752161401",
"transactiontype" : "capture",
"parenttransactionid" : "4583409307",
#rest of the fields
}

The transaction events captures, reversals, refunds, voids and top ups all need to be linked to the original authorization request with the parenttransactionid. So for these transaction types you need to use the transactionid of the corresponding transaction of type auth or auth_capture as the parenttransactionid. Besides, the respective transaction type needs to be defined in the field transactiontype.

On your right there is a JSON payload example (3) of a transaction of type auth, therefore an authorization.

On your right there is a JSON payload example (4) of the capture of the above authorization, therefore a transaction of type capture.

Inter account transfers

Example (5)

{
"transactionid" : "5752161401",
"transactiontype" : "outgoing_wallet_transfer",
#rest of the fields
}

Example (6)

{
"transactionid" : "18394736",
"transactiontype" : "outgoing_wallet_transfer",
"sistertransactionid": "5752161401"
#rest of the fields
}

Historical fund transfers can be sent as a separate table. For live fund transfers, you can use the inter account transfers endpoint. An inter account transfer event always happens from the merchant’s perspective.

On your right there is a minimal JSON payload example (5) of an inter account transfer.

In case a fund transfer happens between two known entitites, so for example when a merchant sends funds to another known merchant, the transfer can be mirrored, through the sistertransactionid field. On your right there is a JSON payload example (6) of a mirrored inter account transfer linked to the previous one through the sistertransactionid field.

As you can observe the original inter account transfer is linked via the sistertransactionid.

Fraud Notifications

In order to understand if our scores were correct and to help our AI improve its learning mechanism about your fraud cases, you need to continuously inform us about all the chargebacks and fraud reports that you've had. A chargeback happens when a cardholder that suffered fraud asks the merchant's bank to give back the stolen money. A fraud report is filed when a transaction is likely fraudulent, but not necessarily chargebacked. Therefore sharing this information is fundamental if you want to catch fraud using our product to its best extent.

Other Transaction Types

Other transaction types that we process are payouts and withdrawals. To find out more details about how these and the previously mentioned transaction types are labelled and sent including datatypes, descriptions, & example values - read our API endpoints section so that you can understand which are Fraudio schemas.

Batch transfer

At Fraudio, we offer real-time transaction fraud monitoring where you can connect to an API and inform us of transactions as soon as they occur. We use these transactions to identify fraud directly, to prepare our AI for future transactions, and to power our merchant fraud detection product.

Although using the API is straightforward and our preferred approach, we realize that a real-time integration may entail more than just the implementation aspect. This is why we are now offering a separate means of integration, where the data does not arrive in real time through an API, but rather via recurring file dumps. In this type of integration, new files you upload are imported to our systems on a daily basis.

Batch transfer vs API

The below table has the objective of helping you choosing between the 2 available integration types:

  1. API, or
  2. Batch transfer
API Batch transfer
Large amounts of data at once no yes
Programming effort medium low
Encrypted by default yes yes
Transaction fraud detection period sub-seconds days
Merchant fraud detection period less than a day days
Data quality reporting Automatic On Request
Protocol HTTPS S3
Format JSON Zipped CSV
Authentication API Token Key ID + Secret
Maximal no. of scored transactions per day - 10.000.000 (soft limit)

Upload Files

To share files with Fraudio, you can upload them to our dedicated storage on Amazon S3. We chose this storage solution because it is widely used, offers easy integrations and its data governance complies with security and privacy regulations.

On request, we will share a Key ID and Secret with you that you can use to upload files to a designated folder. There are many S3 clients available for uploading: the command-line interface (CLI), various GUIs and client-side libraries for most programming languages.

Below you have a guide about how to use the CLI. Each step it is accompanied by Shell code snippets to to help you quickly integrate. Follow them to start integrating in batch with Fraudio products.

Get Fraudio Credentials

Install AWS CLI

Log into AWS

aws configure

List all files in your bucket

aws s3 ls "fraudio-customer-batch-data/${CUSTOMER_NAME}/shared/"

View a file from your bucket

aws s3api get-object --bucket fraudio-customer-batch-data --key "${CUSTOMER_NAME}/shared/example.csv" /dev/stdout

Download files

aws s3 cp "s3://fraudio-customer-batch-data/${CUSTOMER_NAME}/shared/example.csv" ./

Upload files

aws s3 cp --acl bucket-owner-full-control ./example.csv "s3://fraudio-customer-batch-data/${CUSTOMER_NAME}/shared/"

File Format

To send files to Fraudio, we ask you to use the CSV file format following the RFC-4180 specification. When in doubt, you can create a small sample file (stripping any private data) and test it at CSV Lint using the default settings. If there are any errors or warnings, please adjust the file format accordingly. The first line should contain column headers, all lines thereafter contain data. The field separator should be , and lines should be separated by \n. Please take into account that free text fields in the CSV may contain commas, spaces and newlines. In those cases the value should be surrounded by "double quotes". If a value contains a double quote, it can be escaped with another double quote, e.g. "Just say, ""hi""!".

We ask you to compress files as ZIP files to reduce our network traffic and storage requirements. A good rule of thumb is compression applies when there are many files, or files of more than 1MB. In case of a batch integration, this is nearly always the case so we ask you to always compress those CSVs.

The S3 bucket enforces encryption during transfer and storage. You do not need to encrypt the files or protect them with a password.

Folder and Files Structures

We ask our customers to use the following folder structure.

File Categories

In general, batch transfer integration accepts the same categories of data as the API, therefore the sync should contain the following categories of data:

  1. Category transaction: contains acquiring transactions between the merchant and the consumer, including information about the authorization (response code, eci, etc.). This category also includes failed transactions and refunds. Files for this category should go within folder: ${CUSTOMER_NAME}/sync/transactions/.
  2. Category chargeback, providing reason codes for the chargeback and referring to the transaction by the transaction ID. Files for this category should go within folder: ${CUSTOMER_NAME}/sync/chargebacks/.
  3. Category merchant account, which provides more information about each merchant such as registration date and KYC level. You can also include this information with each transaction instead. Files for this category should go within folder: ${CUSTOMER_NAME}/sync/merchant-accounts.
  4. Category account bank transfer is related to a transfer of money from the merchant account into a bank account. We also refer to this as withdrawals, incoming or outgoing bank transfers. Files for this category should go within folder: ${CUSTOMER_NAME}/sync/account-bank-transfers.
  5. Category inter account transfer is related to the merchant transferring funds to other merchant accounts or sub-accounts. Files for this category should go within folder: ${CUSTOMER_NAME}/sync/inter-account-transfers.

Over time, these categories of data tend to grow quite large. We recommend sending data in parts, i.e. only communicate new and changed rows rather than sending the complete dataset each time.

Data Schema

In order for Fraudio to process the files automatically, we ask you to use an agreed upon data schema. A schema consists of field names, data types and (depending on the field) allowed values. The schemas used for batch transfer are the same as the ones used on our API endpoints. Please read API endpoints section in order to understand how to map your data to Fraudio schemas.

It is possible that your data is different from this schema. We will collaborate with you if necessary to perform the field mapping. Data types are flexible and can also be mapped on Fraudio's side.

Please ensure that the uploaded files have a consistent schema that does not change over time. This allows us to maintain a stable integration and ensure that you receive the best anti-fraud services that we can provide!

FAQ

  1. How can I request credentials for the APIs?
    • Get in touch with your Fraudio contact or support@fraudio.com to schedule an appointment and request your credentials.
  2. What is historical data and how can I transfer it?
    • Historical data consists of payment transactions and chargebacks. Fraudio uses this data to improve our fraud detection models allowing them to identify all cases of fraud. To share files with Fraudio, you can upload them in CSV format to our dedicated storage on Amazon S3. We chose this storage solution because it is widely used, offers easy integrations and its data governance complies with security and privacy regulations. On request, we will securely share a key ID and secret with you that you can use to upload files to a designated folder. There are many S3 clients available for uploading: the command-line interface (CLI), various GUIs and client-side libraries for most programming languages. Detailed information on such transfer are available in the batch transfer manual. If you prefer other options to send your data please get in touch. And remember, the more data Fraudio receives, the better your fraud scores will be!
  3. What is pre- and post- authorization data?
    • A payment transaction is a set of information about money that flows from an entity (the payer) to another entity (the beneficiary) through the payment ecosystem. Along its journey, the transaction is processed by different entities (e.g. payment gateway, acquirer, issuer, etc). At some point in time, the transaction needs to be authorized by the bank of the payer.
      • The information a transaction holds before trying to get the authorization of the issuing bank is called pre-authorization information.
      • The information that is obtained after a transaction gets authorized by the issuing bank is called post-authorization information.
  4. Why do I need to send post-authorization data?
    • Post-authorization data is necessary to get the best out of Fraudio's products. We use the authorization data to give transactions historical context.
  5. Can I send data just post-authorization?
    • As a general rule, you should send Fraudio your transactions’ data pre-authorization. However, depending on your role within the payment ecosystem, you may want to detect fraud using our payment fraud detection product after the transaction gets authorized. In both cases, we need you to send us both sets of information, to allow our AI brain to accurately detect fraud from the payment transaction. You usually score your transaction using only pre-authorization information. As soon as you obtain the post-authorization information, you will need to submit that one as well. This is mandatory. In order to send the post-authorization information, you will need to connect to the post-authorization backfill API endpoint. If due to your position in the payments ecosystem you cannot send pre-authorization data, you can score transactions after the transaction got authorized. You just need to send all the information (pre-authorization information and post-authorization information) within the same transaction to the fraud score API endpoint.
  6. Can I integrate with the merchant initiated fraud detection product without the payment fraud detection product?
    • Yes, you can! You will still need to follow the steps related to the payment fraud detection product, but you won’t need to purchase both products.