Dispute Events
POST https://api.fraudio.com/v1/transactions/dispute-events
Endpoint Overview
Our Dispute Events endpoint collects information related to fraud, such as from the payment dispute process and fraud notifications. Please refer to the list of accepted report types. These are considered to be Critical & Required for the Payment Fraud product:
- Fraud notifications are alerts issued by card networks, such as Visa's TC40 and Mastercard's SAFE files, indicating potential fraudulent activities identified in card transactions.
- Chargebacks refer to the sequential stages in a chargeback dispute process, including the 1st chargeback, 2nd chargeback, pre-arbitration, chargeback reversal, and information supplied, each representing different phases of resolution between a cardholder and a merchant.
The dispute event 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",
"statusid": "pending",
"amount": 1.1,
"currency": "978",
"currencyunit": "major"
}
]
}
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. Please note: 1st chargebacks and fraud notifications are the priority here, especially during integration! Accepted values are: - 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.- chargeback reversal: The disputed amount is transferred back to the merchant's account.- pre-arbitration: A stage in a chargeback dispute where the issuer, unconvinced with the merchant's provided evidence, escalates the case for further review, serving as an intermediate step before potential full arbitration.- 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. |
| amount | Double | Supplementary | Supplementary | Supplementary | The transaction amount in the unit specified by the 'currencyunit' field. Note: The unit used in this field should be explicitly stated in the 'currencyunit' field. |
| currency | String | Supplementary | Supplementary | Supplementary | The 3-digit ISO code for the currency used in the transaction. |
| currencyunit | String | Supplementary | Supplementary | Supplementary | This field defines the unit of currency used in the 'amount' field. Accepts only major (e.g., 12.30) or minor (e.g., 1230) unit values. This choice should align with the unit used in the 'amount' field. |
| statusid | String | Supplementary | Supplementary | Supplementary | The Status ID for a dispute or chargeback event is a unique identifier indicating the current status of the process, such as pending, lost, or won. It tracks the event's progression from initiation to resolution. |
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/dispute-events' \
-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","statusid": "pending","amount": 1.1,"currency": "978","currencyunit": "major"}]}'
import json
import os
import requests
dispute_events_endpoint = 'https://api.fraudio.com/v1/transactions/dispute-events'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json'}
dispute_event = {"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","statusid": "pending","amount": 1.1,"currency": "978","currencyunit": "major"}]}
r = requests.post(dispute_events_endpoint, data=json.dumps(dispute_event), 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 DisputeEvents
{
public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException
{
String disputeEventsEndpoint = "https://api.fraudio.com/v1/transactions/dispute-events";
String accessToken = System.getenv("ACCESS_TOKEN");
String disputeEvent = "{\"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\",\"statusid\": \"pending\",\"amount\":1.1,\"currency\":\"978\",\"currencyunit\":\"major\"}]}";
HttpRequest request = HttpRequest.newBuilder()
.uri(new URI(disputeEventsEndpoint))
.header("Authorization", String.format("Bearer %s", accessToken))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(disputeEvent))
.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 $dispute_events_endpoint = 'https://api.fraudio.com/v1/transactions/dispute-events';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $dispute_event = '{"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","statusid": "pending","amount": 1.1,"currency": "978","currencyunit": "major"}]}';
my $req = HTTP::Request -> new(POST => $dispute_events_endpoint);
$req -> header('Authorization' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($dispute_event);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";
<?php
$dispute_events_endpoint = 'https://api.fraudio.com/v1/transactions/dispute-events';
$access_token = $_SERVER["ACCESS_TOKEN"];
$dispute_event = '{"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","statusid": "pending","amount": 1.1,"currency": "978","currencyunit": "major"}]}';
$options = [
'http' => [
'header' => "Authorization: Bearer $access_token" .
"Content-Type: application/json",
'method' => 'POST',
'content' => $dispute_event
]
];
$context = stream_context_create($options);
$result = file_get_contents($dispute_events_endpoint, false, $context);
print $result;
?>