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
Description | Field Name | Format | Example |
---|---|---|---|
Processor Case ID the payment processor assigns to each claim. | processorCaseNumber | String | CB-43433343219 |
The unique identifier associated with the Processor charge. | processorChargeId | String | 0073000000000096401767 |
The id of of the order that the evidence is linked to. | orderId | String | O6996685178152213554 |
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 Name | Condition |
---|---|
processorCaseNumber | No condition. Forter can directly match evidence to the claim |
processorChargeId | chargeID must be provided to Forter as part of the Chargeback Recovery Integration |
orderId | orderID 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 Test | Request | Response |
---|---|---|
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 Test | Condition |
---|---|
Match claims by order number | |
Match claims by case number | |
Match claims by case number and order number |
Testing Part #3: Chargeback Validation
Integration Test | Condition |
---|---|
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
}
Updated 3 days ago