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 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 types and formats, refer to evidence glossary https //docs forter com/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 send request to evidence api send a request to the evidence api with either file evidence upload paths to evidence files that were uploaded to s3 using the /v3/disputes/evidence/file endpoint data points evidence submit structured evidence data directly using the /v3/disputes/evidence/datapoints endpoint both methods can be used independently or combined based on your evidence requirements 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 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 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 description condition format example processorcasenumber processor case id 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 directly without requiring file uploads 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 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" "test order id", "processorchargeid" null, "processorcasenumber" "test case number", "disputebefore" null, "status" "open", "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" "ord 12345678", "processorcasenumber" "cb 87654321", "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" "ord 12345678", "processorchargeid" null, "processorcasenumber" "cb 87654321", "disputebefore" null, "status" "open", "evidencefilename" "s3 //forter file transfer/0955be59 a7e7 4e43 81de/dispute evidence/cp1 pdf" } } ], "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" "test order id", "processorchargeid" null, "processorcasenumber" "test case number", "disputebefore" null, "status" "open", "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" "failed", "message" "failed to upload evidences", "errors" \[ { "message" "can not upload because the evidence file does not exist ", "errorname" "evidence does not exist", "attributes" { "evidencefilename" "s3 //forter file transfer/0955be59 a7e7 4e43 81de/dispute evidence/does not exist pdf" } } ], "errorscount" 1 } 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" "test order id", "processorchargeid" null, "processorcasenumber" "test case number", "disputebefore" null, "status" "open", "evidencefilename" "s3 //forter file transfer/0955be59 a7e7 4e43 81de/dispute evidence/invalid\@file\@name" } } ], "errorscount" 1 } 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" \[ { "field" "proofsofrefund\[0] invalidfield", "message" "field is not supported for this data point type" } ] } missing required data point fields { "orderid" "test order id", "processorcasenumber" "test case number", "proofsofdelivery" \[ { "deliverydate" "2024 01 15" } ] } { "status" "failed", "message" "invalid datapoints provided", "invalidevidencedatapoints" \[ { "field" "proofsofdelivery\[0] trackingnumber", "message" "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" \[ { "field" "airlineticketnumbers", "message" "array size exceeds maximum allowed limit of 50 items" } ] } claims matching integration test condition match claims by order number match claims by case number match claims by case number and order number chargeback validation integration test condition no chargeback exists for specified order the status of the chargeback is not open chargeback has expired 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", "files" \[ { "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" \[ { "refundid" "ref 12345", "refundamount" 99 99, "refunddate" "2024 01 15t10 30 00z", "refundreason" "customer cancellation" } ], "proofsofdelivery" \[ { "trackingnumber" "1z123456789", "deliverydate" "2024 01 20t14 30 00z", "deliveryaddress" "123 main st, city, state 12345", "carriername" "ups" } ], "airlineticketnumbers" \["1234567890123", "1234567890124"] }' post file evidence example var axios = require('axios'); var data = json stringify({ "evidencetype" "contract page", "files" \[ { "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" \[ { "refundid" "ref 12345", "refundamount" 99 99, "refunddate" "2024 01 15t10 30 00z", "refundreason" "customer cancellation" } ], "proofsofdelivery" \[ { "trackingnumber" "1z123456789", "deliverydate" "2024 01 20t14 30 00z", "deliveryaddress" "123 main st, city, state 12345", "carriername" "ups" } ], "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", "evidenceid" "evidence 12345", "chargebacks" \[ { "processorchargeid" "0073000000000096401767", "processorcasenumber" "cb 43433343219", "orderid" "o6996685178152213554" } ] } 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" \[ { "field" "proofsofrefund\[0] refundamount", "message" "field must be a positive number" }, { "field" "proofsofdelivery\[0] trackingnumber", "message" "required field is missing" } ] } files error response example { "status" "failed", "message" "failed to upload evidences", "errors" \[ { "message" "evidence file format is not supported ", "errorname" "unsupported evidence format", "attributes" { "orderid" "o6996685178152213554", "processorchargeid" "0073000000000096401767", "processorcasenumber" "cb 43433343219", "evidencefilename" "s3 //forter file transfer/\<your folder>/dispute evidence/example txt" } } ], "errorscount" 1 }