Merchant Evaluations

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

Endpoint Overview

Our Merchant Evaluations endpoint collects the outcomes of your investigations of merchants. These merchant evaluations are very important for the Merchant Fraud and AML product as they are used as labels and feedback mechanism to train and update our Machine Learning models.

Merchant evaluations are only applicable under the following circumstances:

• you are using the Merchant Fraud product and/or the AML product
• you have a risk team that evaluates merchant accounts

The merchant evaluations can be sent either individually or in batch.

Request Parameters

Request parameters in JSON format

{"data":
  [
    {
      "merchant": "eec1d18f-a714-491d-9721-4600ba7c44c3",
      "evaluation": "fraudster",
      "timestamp": 1646063615,
      "comment": "Money launderer."
    }
  ]
}

Request parameters: Field Reference Table

Field	Data Type	Payment Fraud (Issuer)	Payment Fraud (Acquirer / Processor)	Merchant Fraud / AML	Description
timestamp	Double	n.a.	n.a.	Important	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	n.a.	n.a.	Important	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.
evaluation	String	n.a.	n.a.	Important	Outcome of the latest evaluation of the merchant. Valid values are: - fraudster - suspicious - legitimate
comment	String	n.a.	n.a.	Important	The comment field is a free-form text field that can be used to provide additional information about merchant evaluations. This is information that is not yet covered by the categories that are defined as values for the evaluation field. So after having done an investigation on merchants, analysts often provide comments on why the merchant was closed down (or not). Example values are "suspected money launderer, large number of transactions from High Risk countries", or "blocked due to large number of refunds".

Response Parameters

200 OK Response

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

Status Code	Status Message	Description	Schema
200	OK	Standard response for successful HTTP requests.	200 OK - Post-auth response
4xx, 500, 501, 502, 503, 504	error	Various error messages for unsuccessful HTTP requests.	Problem response

Code samples

Shell

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"}]}'

Python

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())

Java

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);
    }
}

Perl

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

<?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" .
                     "Content-Type: application/json",
        'method'  => 'POST',
        'content' => $merchant_evaluation
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($merchants_risk_evaluations_endpoint, false, $context);
  print $result;
?>