Chargebacks

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

Endpoint Overview

Our Chargebacks endpoint collects fraud labels. These labels are crucial for the Payment Fraud product as they are used as labels to train 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.

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. 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	Important	Important	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

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

Python

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

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

Perl

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

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