Integrate with Forter's Evidence API
- Guide you through any API, S3, or portal-based workflows to submit evidence when requested
Save time and effort by using our Evidence API to automatically send post-order evidence for chargeback disputes. You also have the flexibility to manually upload evidence via the Forter Portal
Authentication
The Evidence API will adopt the standard authentication parameters as described in the Forter API Reference Overview - Security and Authentication
Steps to Integrate
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 Evidence API: Supported Evidence Types
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 Evidence API: Supported Evidence Types
| 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 | | |
| Number of evidence of the same type per claim is above the threshold | | |
| Wrong evidence prefix location | | |
| File does not exist | | |
| File does not conform to naming requirements | | |
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"}
},
]
}'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);
});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 16 days ago