# Evidence API Save time and effort by using our [Evidence API endpoint](https://docs.forter.com/reference/evidence "Evidence API endpoint") to automatically send post-order evidence for chargeback disputes. You also have the flexibility to manually upload evidence via the Forter Portal. ## [Integration Steps](https://docs.forter.com/evidence-api#integration-steps) Integration Steps 1. **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](https://portal.forter.com/app/integration/credentials/ "AWS S3 folder assigned to your site"), which you will use to securely transfer all of your chargeback evidence. 2. **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 "Evidence Glossary"). Use descriptive file names and avoid spaces when possible (use hyphens or underscores). 3. **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 [(reference)](https://docs.forter.com/reference/evidence-file-upload "(reference)") 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 [(reference)](https://docs.forter.com/reference/evidence "(reference)"). 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. 4. **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](https://docs.forter.com/evidence-api#key-api-fields) 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** | **Format** | **Example** | |---------------------------|--------------------------------------------------------------------|------------|------------------------------| | processorCaseNumber | The Processor Case ID that the payment processor assigns to each claim. | String | CB-43433343219 | | processorChargeId | The unique identifier associated with the processor charge. | String | 0073000000000096401767 | | orderId | The id of of the order that the evidence is linked to. | 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](https://docs.forter.com/evidence-api#api-endpoints) 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](https://docs.forter.com/evidence-api#file-format-requirements) File Format Requirements Supported file formats: - **PDF** - Preferred format for documents - **JPEG/JPG** - Image evidence - **PNG** - Image evidence with transparency support ## [Integration Tests](https://docs.forter.com/evidence-api#integration-tests) Integration Tests ### [File Validations](https://docs.forter.com/evidence-api#file-validations) File Validations | **Integration Test** | **Request** | **Response** | |-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| | File size is too large (triggered for attachments over 1MB in size) | { "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](https://docs.forter.com/evidence-api#data-points-validations) 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" } ] } | | Data points exceed maximum array size (FedEx-only fedexAccountNumber field) | { "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "fedexAccountNumber":["ACCT001","ACCT002",...,"ACCT051"] } | { "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"fedexAccountNumber", "failureReason":"Array size exceeds maximum allowed limit of 50 items" } ] } | | Data points exceed maximum array size (other field) | { "orderId":"test-order-id", "processorCaseNumber":"test-case-number", "other":["note 1","note 2",...,"note 1001"] } | { "status":"FAILED", "message":"Invalid datapoints provided", "invalidEvidenceDatapoints":[ { "datapointPath":"other", "failureReason":"Array size exceeds maximum allowed limit of 1000 items" } ] } | File evidence example ```bash 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//dispute-evidence/example-16451.pdf" }' ``` Data points evidence example ```bash 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 ```javascript var axios = require('axios'); var data = JSON.stringify({ "evidenceType":"CONTRACT_PAGE", "filePath":"s3://forter-file-transfer//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 ```javascript 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 ```json { "status":"SUCCESS", "message":"EVIDENCE_UPLOADED" } ``` Data points success response example ```json { "status":"SUCCESS", "evidenceId":"evidence_67890", "message":"Data points evidence successfully processed", "chargebacks":[ { "processorChargeId":"0073000000000096401767", "processorCaseNumber":"CB-43433343219", "orderId":"O6996685178152213554" } ] } ``` Data points error response example ```json { "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 ```json { "status":"FAILED", "message":"SCHEMA_VALIDATION_FAILED" } ```