Fraud Notifications Enrichment
Chargebacks
(Please note that the Fraud Notifications Enrichment endpoint was previously named the Chargebacks endpoint)
POST https://api.fraudio.com/v1/transactions/fraud-notifications-enrichment
Endpoint Overview
Our Fraud Notifications Enrichment endpoint collects fraud labels. These labels are considered to be Critical & Required for the Payment Fraud product, as they are used as labels to train our machine learning models. We distinguish between fraud notifications and chargebacks:
- Fraud notifications are reports from the (cardholder's) bank that flag fraudulent activity.
- Chargeback events represent the different stages of a chargeback.
The fraud labels can be sent either individually or in batch.
A note on fraud labels
It is sufficient to send only fraud notifications and the first stage of chargebacks (1st chargeback).
Whilst sending other chargeback stages is helpful, doing so is optional, not a requirement. Even if you do have this additional data, we recommend that you send these two labels first.
Request Parameters
Request parameters in JSON format
{
"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"
}
]
}
Request parameters: Field Reference Table
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| transactionid | String | Critical & Required | Critical & Required | Supplementary | The unique identifier of the transaction event. Every transaction event, so auth, capture, auth_capture, etc., has its own unique ID. |
| timestamp | Double | Critical & Required | Critical & Required | Supplementary | The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted. |
| reporttype | String | Critical & Required | Critical & Required | Supplementary | The type of fraud report. Some possible values are fraud notification, 1st chargeback, information supplied, reversed chargeback, pre-arbitration, 2nd chargeback. Please note: 1st chargebacks and fraud notifications are the priority here, especially during integration! 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. |
| merchant | String | Critical & Required | Critical & Required | Supplementary | 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. |
| chargebackreason | String | Critical & Required | Critical & Required | Supplementary | Reason for the chargeback. |
| fraudimportdate | Double | Important | Important | Supplementary | Timestamp when a dispute was opened. |
| chargebackid | String | Supplementary | Supplementary | Supplementary | External ID of this chargeback, unique for the customer. |
| fraudreason | String | Supplementary | Supplementary | Supplementary | Reason why the transaction was fraudulent. |
Response Parameters
| Status Code | Status Message | Description | Schema |
|---|---|---|---|
| 200 | OK | Standard response for successful HTTP requests. | 200 OK - Data Collection Response |
4xx, 500, 501, 502, 503, 504 | error | Various error messages for unsuccessful HTTP requests. | Problem response |
Code samples
- Shell
- Python
- Java
- Perl
- PHP
curl -X POST 'https://api.fraudio.com/v1/transactions/fraud-notifications-enrichment' \
-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/fraud-notifications-enrichment'
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/fraud-notifications-enrichment";
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/fraud-notifications-enrichment';
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/fraud-notifications-enrichment';
$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" .
"Content-Type: application/json",
'method' => 'POST',
'content' => $chargeback
]
];
$context = stream_context_create($options);
$result = file_get_contents($chargebacks_endpoint, false, $context);
print $result;
?>