Evidence API

Save time and effort by using our Evidence API endpoint to automatically send post-order evidence for chargeback disputes. You also have the flexibility to manually upload evidence via the Forter Portal.

Integration Steps

Create a dedicated folder for evidence files in S3

Create a dedicated folder called dispute-evidence in the AWS S3 folder assigned to your site, which you will use to securely transfer all of your chargeback evidence.

Upload evidence files to S3

Upload file-based evidence securely to the dispute-evidence folder in S3. For details on types and formats, refer to Evidence Glossary. Use descriptive file names and avoid spaces when possible (use hyphens or underscores).

Send request to Evidence API

If the evidence is contained within a file uploaded to S3, follow up with a request to /v3/disputes/evidence/file (reference) that includes the path to the file and supporting details in order to match the file to the correct dispute.

If the evidence is in the form of structured data rather than a file upload, send this in a request to /v3/disputes/evidence/datapoints (reference).

Both methods can be used independently or combined based on your evidence requirements.

Forter will match evidence to claims that are in first cycle and open. Evidence for claims in other statuses (e.g., expired, won, lost, etc.) will not be matched nor added to the claim.

Receive response

Forter will return a response of success or failure. A successful response will include the evidenceId of the created document. A failure response will include error messages. For data points submissions, invalid data points will be returned in the invalidEvidenceDatapoints field.

Key API Fields

To add evidence to the appropriate representment, each evidence needs to be associated to its corresponding claim. The evidence may be associated to one or more chargeback disputes, based on the identifiers provided. Forter requires at least one of the identifiers to match the evidence to the claim. The identifiers must meet the following conditions:

Field Name	Description	Format	Example
processorCaseNumber	The Processor Case ID that the payment processor assigns to each claim.	String	CB-43433343219
processorChargeId	The unique identifier associated with the processor charge.	String	0073000000000096401767
orderId	The id of of the order that the evidence is linked to.	String	O6996685178152213554

Note If you are planning on using orderID and your orders can result in more than one charge (e.g., multiple charges for multiple shipments under one order, or multiple airfare charges under one reservation), Forter may append multiple evidence files to a claim.

API Endpoints

The Evidence API provides two endpoints for different evidence submission methods:

POST /v3/disputes/evidence/file - Evidence upload endpoint for file-based evidence

POST /v3/disputes/evidence/datapoints - Submit structured evidence data

File Format Requirements

Supported file formats:

PDF - Preferred format for documents

JPEG/JPG - Image evidence

PNG - Image evidence with transparency support

Integration Tests

Integration Test	Request	Response
File size is too large (triggered for attachments over 1MB in size)	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"PROOF_OF_DELIVERY", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/large-file-exceeds-limit.pdf" }	{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }
The evidence file format is not supported	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/etechTest123.txt" }	{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }
Number of evidence of the same type per claim is above the threshold	{ "orderId":"ORD-12345678", "processorCaseNumber":"CB-87654321", "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/cp1.pdf" }	{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }
Wrong evidence prefix location	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"PROOF_OF_DELIVERY", "filePath":"s3://out-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/example-16451.pdf" }	{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }
File does not exist	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/does-not-exist.pdf" }	{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }
File does not conform to naming requirements	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "evidenceType":"INVOICE", "filePath":"s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/invalid@file@name" }	{ "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" }

Integration Test	Request	Response
Invalid data point structure	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "proofsOfRefund":[ { "invalidField":"invalid-value" } ] }	{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"proofsOfRefund[0].invalidField", "failureReason":"Field is not supported for this data point type" } ] }
Missing required data point fields	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "proofsOfDelivery":[ { "date":"2024-01-15" } ] }	{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"proofsOfDelivery[0].trackingNumber", "failureReason":"Required field is missing" } ] }
Data points exceed maximum array size	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "airlineTicketNumbers":["TKT001","TKT002",...,"TKT051"] }	{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"airlineTicketNumbers", "failureReason":"Array size exceeds maximum allowed limit of 50 items" } ] }
Data points exceed maximum array size (FedEx-only fedexAccountNumber field)	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "fedexAccountNumber":["ACCT001","ACCT002",...,"ACCT051"] }	{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"fedexAccountNumber", "failureReason":"Array size exceeds maximum allowed limit of 50 items" } ] }
Data points exceed maximum array size (other field)	{ "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "other":["note 1","note 2",...,"note 1001"] }	{ "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"other", "failureReason":"Array size exceeds maximum allowed limit of 1000 items" } ] }

curl --location --request POST 'https://{forterBaseUrl}:8443/v3/disputes/evidence/file' \
--header 'api-version: 2.1' \
--header 'x-forter-siteid: forterSiteId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic abc123' \
--data-raw '{
 "processorCaseNumber" : "CB-43433343219",
 "processorChargeId" : "0073000000000096401767",
 "orderId" : "O6996685178152213554",
 "evidenceType": "CONTRACT_PAGE",
 "filePath": "s3://forter-file-transfer/<your-folder>/dispute-evidence/example-16451.pdf"
}'

curl --location --request POST 'https://{forterBaseUrl}:8443/v3/disputes/evidence/datapoints' \
--header 'api-version: 2.1' \
--header 'x-forter-siteid: forterSiteId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic abc123' \
--data-raw '{
 "processorCaseNumber" : "CB-43433343219",
 "processorChargeId" : "0073000000000096401767",
 "orderId" : "O6996685178152213554",
 "proofsOfRefund": [
   {
     "refundTransactionId": "REF-12345",
     "refundAmount": 99.99,
     "refundCurrency": "USD",
     "refundDate": "2024-01-15",
     "refundAuthorizationCode": "B44233",
     "refundChargeId": "111111111"
   }
 ],
 "proofsOfDelivery": [
   {
     "trackingNumber": "1Z123456789",
     "carrier": "UPS", 
     "date": "2024-01-20"
   }
 ],
 "airlineTicketNumbers": ["1234567890123", "1234567890124"]
}'

var axios = require('axios');
var data = JSON.stringify({
  "evidenceType": "CONTRACT_PAGE",
  "filePath": "s3://forter-file-transfer/<your-folder>/dispute-evidence/example-16451.pdf",
  "processorCaseNumber": "CB-43433343219",
  "processorChargeId": "0073000000000096401767",
  "orderId": "O6996685178152213554"
});

var config = {
  method: 'post',
  url: 'https://{forterBaseUrl}/v3/disputes/evidence/file',
  headers: { 
    'api-version': '2.1', 
    'x-forter-siteid': 'forterSiteId', 
    'Content-Type': 'application/json',
    'Authorization': 'Basic abc123'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

var axios = require('axios');
var data = JSON.stringify({
  "processorCaseNumber": "CB-43433343219",
  "processorChargeId": "0073000000000096401767",
  "orderId": "O6996685178152213554",
  "proofsOfRefund": [
    {
      "refundTransactionId": "REF-12345",
      "refundAmount": 99.99,
      "refundCurrency": "USD",
      "refundDate": "2024-01-15",
      "refundAuthorizationCode": "B44233",
      "refundChargeId": "111111111"
    }
  ],
  "proofsOfDelivery": [
    {
      "trackingNumber": "1Z123456789",
      "carrier": "UPS",
      "date": "2024-01-20"
    }
  ],
  "airlineTicketNumbers": ["1234567890123", "1234567890124"]
});

var config = {
  method: 'post',
  url: 'https://{forterBaseUrl}/v3/disputes/evidence/datapoints',
  headers: { 
    'api-version': '2.1', 
    'x-forter-siteid': 'forterSiteId', 
    'Content-Type': 'application/json',
    'Authorization': 'Basic abc123'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

{
  "status": "SUCCESS",
  "message": "EVIDENCE_UPLOADED"
}

{
  "status": "SUCCESS",
  "evidenceId": "evidence_67890",
  "message": "Data points evidence successfully processed",
  "chargebacks": [
    {
      "processorChargeId": "0073000000000096401767",
      "processorCaseNumber": "CB-43433343219",
      "orderId": "O6996685178152213554"
    }
  ]
}

{
  "status": "FAILED",
  "message": "Invalid datapoints provided",
  "invalidEvidenceDatapoints": [
    {
      "datapointPath": "proofsOfRefund[0].refundAmount",
      "failureReason": "Field must be a positive number"
    },
    {
      "datapointPath": "proofsOfDelivery[0].trackingNumber",
      "failureReason": "Required field is missing"
    }
  ]
}

{
  "status": "FAILED",
  "message": "SCHEMA_VALIDATION_FAILED"
}