Chargeback Disputes API Integration

Authentication

We will provide you with a secret key you can use to authenticate with our endpoints. Authentication is done via the X-API-KEY header.

Error responses:

Status	Body	When
401	An API key is required for authentication (plain text)	X-API-KEY header missing
403	Invalid API key provided (plain text)	Key doesn't exist, or the lookup failed
403	Key has invalid permissions (plain text)	Key exists but isn't authorized for this operation

Request Proof

To request proof for use in chargeback disputes, create a ProofRequest

method: PUT

endpoint: https://api.dyneti.com/disputes/proofRequest

body:

["scan-id-1", "scan-id-2", ...]

response:

{
	"id": "proof-request-id"
}

example:

curl -X PUT https://api.dyneti.com/disputes/proofRequest \
     -H "X-API-KEY: your-secret-key-here" \
     -H "Content-Type: application/json" \ 
     -d '["scan-id-1", "scan-id-2", "scan-id-3"]'

There is no maximum number of scan IDs per request. You can send a single scan ID per proofRequest (e.g., one per chargeback) or batch many together — there's no functional or performance downside either way.

Error responses:

Status	Body	When
400	{"error": "Invalid request. Empty body"}	Body missing or an empty array.
400	{}	Body present but not valid JSON
400	{"error": "Invalid request. At least one of the provided scan IDs is not valid"}	Body contains at least an entry that's not a valid UUIDv4

Check Proof Request Status

method: GET

endpoint: https://api.dyneti.com/disputes/proof/<proof_request_id>

example:

curl -X GET https://api.dyneti.com/disputes/proof/your-proof-request-id-here \
     -H "X-API-KEY: your-secret-key-here"

If the request is not yet complete, the status will be pending:

{
	"status": "pending"
}

You can poll the request until the status is complete. We recommend an interval of a few hours.

If the request is complete, the status will be complete and the scans field will be present:

{
	"status": "complete",
	"scans": [
		{
			"scanId": "scan-id-1",
			"groundTruth": "valid",
			"image": "https://api.dyneti.com/disputes/image/scan-id-1.jpg"
		},
{
			"scanId": "invalid-scan-id-1",
			"groundTruth": "invalid" 
		},
		...
	]
	
}

Here, groundTruth "valid" means that this is a good candidate scan for a chargeback dispute (e.g. a friendly fraud case). On the other hand, groundTruth "invalid" means that the scan corresponds to actual fraud and thus this scan is not a good candidate for a chargeback dispute.

Note: scans marked as “invalid” will not include an image url.

Error responses:

Status	Body	When
404	{"error": "Proof request not found"}	proofRequestId doesn't exist
403	{"error": "Forbidden"}	Proof request exists but belongs to a different account

Retrieve Dispute Image

Use this endpoint to fetch the image for a scan that was returned with a groundTruth of "valid" in a completed proof request. Requires the X-API-KEY header, same as all other endpoints. The response is the raw JPEG, returned with Content-Disposition: attachment; filename={scanId}.jpg (i.e., it downloads as a file rather than rendering inline — don't drop the URL directly into an <img> tag).

method: GET

endpoint: https://api.dyneti.com/disputes/image/<scanId>.jpg

example:

curl -H "X-API-KEY: your-secret-key-here" \
  https://api.dyneti.com/disputes/image/<scan-id>.jpg \
  -o scan.jpg

Error responses:

Status	Body	When
400	{"error": "Invalid request. Provided scan ID is not valid"}	scanId isn't a valid UUIDv4
400	Bad Request (plaintext)	Error verifying scan ownership
403	{"error": "Forbidden"}	Scan was labeled fraudulent — image is not retrievable.
404	{"error": "Image not found"}	Scan hasn't been labeled yet, or doesn't belong to this account
404	Not Found (plaintext)	Scan was labeled, but the underlying image could not be located