Chargeback Recovery Evidence API Overview

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.


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

Integration Guide

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

Field NameDescriptionFormatExample
processorCaseNumberProcessor Case ID the payment processor assigns to each claim.StringCB-43433343219
processorChargeIdThe unique identifier associated with the Processor charge.String0073000000000096401767
orderIdThe id of of the order that the evidence is linked to.StringO6996685178152213554

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.

Limitations and Validations:

  • Bulk upload requests may be throttled

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>/dipsute-evidence/example-16451.pdf"}

POST evidence example (Node.js - Axios):

var axios = require('axios');
var data = JSON.stringify({
			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

.then(function (response) {
.catch(function (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