Integrate with Forter's Evidence API

With Forter's Chargeback Recovery Evidence API, you can automate the evidence upload workflow for chargeback representment by sending post-order evidence to complete representments. Post order evidence can also be provided through the Forter Portal.

Step 6: Provide Additional Compelling Evidence for Disputes

Authentication

The Evidence API will adopt the standard authentication parameters as described in the Forter API Reference Overview - Security and Authentication

Step 1: Upload Evidence Files to s3 Bucket

You can make post-order evidence available to Forter by uploading file-based evidence securely via File Account Transfer to S3. For details on evidenceFormat for each evidenceType refer to the Chargeback Recovery Evidence Glossary

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. Evidence for expired claims will not be matched.

Step 2: Send Request to Evidence API

Send a request to the Evidence API with the parameters included in the API Reference. Your request provides Forter with the path to the evidence file that was uploaded to S3.

Step 3: Receive the 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.

API Reference

Forter exposes API, /v2/dispute-evidence with the following parameters.

Note: You can find the evidence keys in the Chargeback Recovery Evidence Glossary

DescriptionField NameFormatExample
Processor Case ID the payment processor assigns to each claim.processorCaseNumberStringCB-43433343219
The unique identifier associated with the Processor charge.processorChargeIdString0073000000000096401767
The id of of the order that the evidence is linked to.orderIdStringO6996685178152213554

Matching Evidence to Claims

To add evidence to the appropriate representment, each evidence needs to be associated to its corresponding claim. Depending on your internal system setup for each evidenceType (e.g., proof of refund, proof of delivery, etc.), the evidence may be associated to one or more of the following unique identifiers specified in the API reference. Forter requires at least one of the identifiers to match the evidence to the claim. The identifier must meet the following conditions:

Field NameCondition
processorCaseNumberNo condition. Forter can directly match evidence to the claim
processorChargeIdchargeID must be provided to Forter as part of the Chargeback Recovery Integration
orderIdorderID must be provided to Forter as part of the Fraud Management Integration

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.

Integration Testing and Validations:

Testing Part #1: File Validations

Integration TestRequestResponse
File size is too large
The evidence file format is not supported"{
""orderId"": ""test-order-id"",
""processorCaseNumber"": ""test-case-number"",
""contractPageFiles"": [
{
""file"": {
""filePath"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/etechTest123.txt""
}

} ]

`
}"
"{
""status"": ""failed"",
""message"": ""Failed to upload evidences"",
""errors"": [
{
""message"": ""Evidence file format is not supported."",
""errorName"": ""UNSUPPORTED_EVIDENCE_FORMAT"",
""attributes"": {
""orderId"": null,
""processorChargeId"": null,
""processorCaseNumber"": null,
""disputeBefore"": null,
""status"": null,
""evidenceFileName"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/etechTest123.txt""
}
}
],
""errorsCount"": 1
}"
Number of evidence of the same type per claim is above the threshold"{
""orderId"": ""TOO_MANY"",
""processorCaseNumber"": ""TOO_MANY"",
""contractPageFiles"": [
{
""file"": {
""filePath"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/cp1.pdf""
}
},
{
""file"": {
""filePath"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/cp2.pdf""
}
}
]
}"
"{
""status"": ""failed"",
""message"": ""Failed to upload evidences"",
""errors"": [
{
""message"": ""Failed upload because number of evidence of the same type per claim is above the threshold."",
""errorName"": ""TOO_MANY_EVIDENCE_IN_SAME_TYPE_FOR_CLAIM"",
""attributes"": {
""orderId"": null,
""processorChargeId"": null,
""processorCaseNumber"": null,
""disputeBefore"": null,
""status"": null,
""evidenceFileName"": null
}
}
],
""errorsCount"": 1
}"
Wrong evidence prefix location"{
""orderId"": ""test-order-id"",
""processorCaseNumber"": ""test-case-number"",
""contractPageFiles"": [
{
""file"": {
""filePath"": ""s3://out-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/example-16451.pdf""
}

} ]

`
}"
"{
""status"": ""failed"",
""message"": ""Failed to upload evidences"",
""errors"": [
{
""message"": ""Can not upload because incorrect evidence prefix location."",
""errorName"": ""INCORRECT_EVIDENCE_PREFIX_LOCATION"",
""attributes"": {
""orderId"": null,
""processorChargeId"": null,
""processorCaseNumber"": null,
""disputeBefore"": null,
""status"": null,
""evidenceFileName"": ""s3://out-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/example-16451.pdf""
}
}
],
""errorsCount"": 1
}"
File does not exist"{
""orderId"": ""test-order-id"",
""processorCaseNumber"": ""test-case-number"",
""contractPageFiles"": [
{
""file"": {
""filePath"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/does-not-exist.pdf""
}

} ]

`
}"
"{
""status"": ""FAILURE"",
""errors"": [
{
""message"": ""Can not upload because the evidence file does not exist."",
""errorName"": ""EVIDENCE_DOES_NOT_EXIST"",
""attributes"":{ ""evidenceFileName"": {evidenceFileName: ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/example-16451.tiff""}
}
],
}"
File does not conform to naming requirements"{
""orderId"": ""test-order-id"",
""processorCaseNumber"": ""test-case-number"",
""contractPageFiles"": [
{
""file"": {
""filePath"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/invalid@file@name""
}

} ]

`
}"
"{
""status"": ""failed"",
""message"": ""Failed to upload evidences"",
""errors"": [
{
""message"": ""Can not upload because the evidence file has an invalid name"",
""errorName"": ""INVALID_EVIDENCE_FILENAME"",
""attributes"": {
""orderId"": null,
""processorChargeId"": null,
""processorCaseNumber"": null,
""disputeBefore"": null,
""status"": null,
""evidenceFileName"": ""s3://forter-file-transfer/0955be59-a7e7-4e43-81de/dispute-evidence/invalid@file@name""
}
}
],
""errorsCount"": 1
}"

Testing Part #2: Claims Matching

Integration TestCondition
Match claims by order number
Match claims by case number
Match claims by case number and order number

Testing Part #3: Chargeback Validation

Integration TestCondition
No chargeback exists for specified order
The status of the chargeback is not open
Chargeback has expired

POST evidence example curl command:

curl --location --request POST 'https://{forterBaseUrl}:8443/v2/dispute-evidence' \
--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",
 "contractPageFiles": [
   {
     file: {"filePath": "s3://forter-file-transfer/<your-folder>/dispute-evidence/example-16451.pdf"}
   },
 ]
}'

POST evidence example (Node.js - Axios):

var axios = require('axios');
var data = JSON.stringify({
  "contractPageFiles":[
	 	{
			file: {"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}/v2/dispute-evidence,
  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);
});

A successful response will look like this:

{
  "status": "success",
  "chargebacks": [
        {
            "processorChargeId": "0073000000000096401767",
            "processorCaseNumber": "CB-43433343219",
            "orderId": "O6996685178152213554"
        }
    ],
}

A failure response will look like:

{
  "status": "failed",
  "message": "error_messages",
  "errors": [{"message": "error_messages", "errorName": "error_name", "attributes" {} }],
  "errorsCount": 1
}