Chargeback Agent API

The Chargeback Agent API accepts dispute documents and returns a recommendation, recommended actions, and a formal response letter. Requests authenticate with a secret key.

Agent Lifecycle

The chargeback agent workflow consists of four main steps:

1. Initialize agent with a chargeback case (POST)
2. Attach documents to the case (POST, PUT)
3. Agent recommendation (GET)
4. Generate response letter (POST)
5. Read response letter (GET)

Attaching documents and reviewing the recommendation is iterative: each recommendation reports its confidence and suggests further evidence to attach until the case is ready.

Once the recommendation is ready, downloading the PDF is a two-step process:

1. Request download (GET)
2. Download document (GET)

Initialize Agent with Chargeback Case

Initialize an agent session by posting the chargeback case details. The response provides the case id used by every subsequent call.

Request

POST /chargeback
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    amountCents: Number,
    cardNetwork: String,
    cardholderName: String,
    currency: String,
    disputeDate: String,
    dueDate: String,
    maskedCardNumber: String,
    merchantIdentifier: String,
    reasonCode: String,
    reasonDescription: String,
    referenceNumber: String,
    transactionDate: String
  }
}

Response

The response returns the case with its id and status alongside the submitted details, plus the defenseRequirements the reason code calls for — available immediately, before any document is attached. evidenceSuggested and evidenceProvided are category-level projections of that checklist: a category counts provided as soon as one of its requirements is satisfied, and the rest stay suggested — the item-level detail lives in defenseRequirements and recommendedActions.

{
  data: {
    amountCents: Number,
    cardNetwork: String,
    cardholderName: String,
    currency: String,
    defenseRequirements: [{ requirement: String, satisfied: Boolean }],
    disputeDate: String,
    dueDate: String,
    evidenceProvided: [String],
    evidenceSuggested: [String],
    id: String,
    maskedCardNumber: String,
    merchantIdentifier: String,
    reasonCode: String,
    reasonDescription: String,
    referenceNumber: String,
    status: "pending",
    transactionDate: String
  }
}

Evidence Categories

evidenceProvided and evidenceSuggested draw from a closed vocabulary. Every value is one of the strings below, lower-cased so it reads inside a sentence — "attach the delivery confirmation." Capitalize the first letter when presenting a value as a heading or list item. Both arrays are returned in presentation order, the order shown here, and a category appears in exactly one of them.

Update Case Details

Update a case by posting the fields to change. Only fields present in data are updated; omitted fields are unchanged. Accepts the same fields as initialize.

Request

POST /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    dueDate: String
  }
}

Response

The response returns the updated case, in the same shape as initialize.

Delete Case

Delete a case and its attached documents. Deleted cases and their documents cannot be retrieved.

Request

DELETE /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

{
  data: {
    id: String,
    status: "deleted"
  }
}

Attach Documents to Case

Attach documents by posting their uploadFilenames, then sending each file's contents to its returned signed putUrl, exactly as in document upload. Each attached document is assessed in the next recommendation.

Documents are attached to cases initialized with POST /chargeback. A session initialized with direct upload takes its documents at initialization and answers this endpoint with a 400.

Request

POST /chargeback/:id/upload
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    uploadFilenames: [String]
  }
}

Response

{
  data: {
    id: String,
    putUrls: [
      {
        evidenceId: String,
        putUrl: String,
        uploadFilename: String
      }
    ]
  }
}

Each signed putUrl is valid for fifteen minutes. Each evidenceId identifies the attached document and is the identifier used to delete evidence.

Delete Evidence from Case

Delete a single attached document by its evidenceId. The case and its remaining documents are unchanged. Deleted documents cannot be retrieved.

Removing evidence triggers a fresh assessment automatically, about thirty seconds after the last deletion so a burst of deletions is assessed once. The recommendation shows status: "processing" while the agent reassesses and completes with the remaining evidence. Any response letter already written is retired at the same time, since it argued from the deleted document: GET /chargeback/:id/letter answers 404 until the response letter is requested again, which rewrites it from the remaining evidence.

Request

DELETE /chargeback/:id/evidence/:evidenceId
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

{
  data: {
    id: String,
    status: "deleted"
  }
}

Agent Recommendation

Once each document is uploaded the agent assesses the material presented to provide a recommendation and recommended actions. The API response shows status: "processing" while the Agent is working. This process takes several minutes.

The submitted case fields are returned at every status, so the case is readable at any time. While the agent works the response carries the case fields with the current status; once complete the recommendation fields join them.

Request

GET /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

Processing

{
  data: {
    amountCents: Number,
    cardNetwork: String,
    currency: String,
    // ...the case fields as submitted...
    defenseRequirements: [{ requirement: String, satisfied: Boolean }],
    evidenceProvided: [String],
    evidenceSuggested: [String],
    id: String,
    status: "processing"
  }
}

Complete

{
  data: {
    amountCents: Number,
    cardNetwork: String,
    currency: String,
    // ...the case fields as submitted...
    confidence: Number,
    defenseRequirements: [{ requirement: String, satisfied: Boolean }],
    evidenceProvided: [String],
    evidenceSuggested: [String],
    id: String,
    merchantAttachments: [{ evidenceId: String, uploadFilename: String }],
    merchantIdentifier: String,
    priority: String,
    recommendation: String,
    recommendedActions: [String],
    referenceNumber: String,
    status: String
  }
}

If processing fails the response carries an error message instead of a recommendation.

{
  data: {
    id: String,
    message: String,
    status: "error"
  }
}

Generate Response Letter

Once the recommendation is satisfactory, request a formal response letter. The API response shows status: "processing" while the agent is working. This process takes several minutes. Read the letter until it is ready, or register a web hook.

A letter is written only when it is requested. Requesting it again rewrites it from the case as it then stands, so a case whose evidence has changed produces a new letter rather than the earlier one. While the new letter generates the response shows status: "processing" and the earlier letter is no longer returned.

Request

POST /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

{
  data: {
    id: String,
    status: "processing"
  }
}

Read Response Letter

Poll the requested letter until it is ready. A letter that has never been requested, or one retired by deleting evidence, answers 404.

Request

GET /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

Processing

{
  data: {
    id: String,
    status: "processing"
  }
}

Complete

{
  data: {
    id: String,
    responseLetter: String,
    status: "complete"
  }
}

Not requested

HTTP 404
{
  errors: [
    {
      status: 404,
      title: String,
      detail: String
    }
  ]
}

Initialize Agent with Direct Upload

POST /chargeback/upload
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    uploadFilename: String
  }
}

{
  data: {
    id: String,
    putUrls: [
      {
        evidenceId: String,
        putUrl: String,
        uploadFilename: String
      }
    ]
  }
}

PUT ${putUrl}
Content-Type: ${contentType}

curl -X PUT -T file.pdf
"https://bucket.s3.amazonaws.com/file.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=..."

Document Export

GET /chargeback/:id/download
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    id: String,
    status: "processing"
  }
}

{
  data: {
    id: String,
    getUrl: String
  }
}

curl -L -o file.pdf
"https://bucket.s3.amazonaws.com/file.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=..."

Web Hooks

Web hooks may be registered as an alternative to polling the agent status. The event body will contain the same data attribute as the HTTP response, along with metadata and security headers for authentication.

Event Metadata

Along with the data attribute, the event body will contain a metadata attribute describing the web hook event.

{
  metadata: {
    attempt: Number,
    event: "chargeback:copilot",
    id: String,
    timestamp: Number,
    type: "webhook",
    webhook: String
  },
  data: {
    // …
  }
}

Acknowledgement

Web hooks interpret the HTTP response code as acknowledgement of receipt.

Undeliverable Messages

Undeliverable messages will be reattempted for up to one hour. Messages that fail to deliver after one hour will be recorded for remediation. Findustry AI will reach out to discuss improving delivery rates.

Authentication

Web hook deliveries are signed with an HMAC signature in the X-Webhook-Signature header. See Web Hooks authentication.