Evidence API

save time and effort by using our evidence api endpoint https //docs forter com/reference/evidence 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 https //docs forter com/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 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 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 condition format example processorcasenumber the processor case id that the payment processor assigns to each claim no condition forter can directly match evidence to the claim string cb 43433343219 processorchargeid the unique identifier associated with the processor charge chargeid must be provided to forter as part of the chargeback recovery integration string 0073000000000096401767 orderid the id of of the order that the evidence is linked to orderid must be provided to forter as part of the fraud management integration 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 file validations integration test request response file size is too large { "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" } data points validations 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" } ] } chargeback claims matching logic matching rule match claims by order number match claims by case number match claims by case number and order number chargeback validations validation no chargeback exists for specified order the status of the chargeback is not open chargeback has expired file evidence example 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" }' data points evidence example 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"] }' post file evidence example 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); }); post data points evidence example 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); }); files success response example { "status" "success", "message" "evidence uploaded" } data points success response example { "status" "success", "evidenceid" "evidence 67890", "message" "data points evidence successfully processed", "chargebacks" \[ { "processorchargeid" "0073000000000096401767", "processorcasenumber" "cb 43433343219", "orderid" "o6996685178152213554" } ] } data points error response example { "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" } ] } files error response example { "status" "failed", "message" "schema validation failed" }