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 Chargeback Case

Initialize an agent session with chargeback case details. The response includes a case id used in subsequent calls. A complete request body provides optimal performance, though no individual field is required. Blank fields are treated as omitted. null and an empty string mean the same thing: on initialize the field is left unset, and on update it is cleared.

Request

POST /chargeback
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    agent: Boolean | Object,
    amountCents: Number,
    cardNetwork: String,
    cardholderName: String,
    currency: String,
    disputeDate: String,
    dueDate: String,
    maskedCardNumber: String,
    merchantIdentifier: String,
    merchantName: String,
    merchantUrl: String,
    reasonCode: String,
    reasonDescription: String,
    referenceNumber: String,
    transactionDate: String
  }
}

Response

Returns the case with its id and status alongside the submitted details. Reason code defenseRequirements are available immediately. Requirement will be marked `satisfied: true` as evidence is provided. Cases should meet as many requirements as possible to maximize success. evidenceSuggested and evidenceProvided are merchant-friendly descriptions of evidence types meeting defense requirements. More specific actions are suggested in 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,
    merchantName: String,
    merchantUrl: String,
    reasonCode: String,
    reasonDescription: String,
    referenceNumber: String,
    status: "pending",
    transactionDate: String
  }
}

Agent Settings

The agent field controls agent behavior for the case.

{
  data: {
    agent: {
      researchTransactionDetails: Boolean,
      submitDisputeToProcessor: Boolean,
      useMerchantMemories: Boolean,
      writeResponseLetter: Boolean
    }
  }
}

Evidence Categories

evidenceProvided and evidenceSuggested use a controlled vocabulary, listed below. Each item is all lower-case.

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, except agent (Returns 400 Bad Request).

A blank field clears the value on the case. null and an empty string mean the same thing. Every field can be cleared except referenceNumber, which a case must keep (Returns 400 Bad Request).

Request

POST /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    dueDate: String,
    merchantUrl: 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. To replace a letter without changing the evidence behind it, discard the letter instead.

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, and it is written once. Requesting it again does not start a new letter, but returns the existing one. To replace a letter, discard it first.

This request takes no body. A request that carries one answers 400 Bad Request.

Request

POST /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

First request

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

Requested again, letter ready

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

Read Response Letter

Poll the requested letter until it is ready. A letter that has never been requested, or one retired by discarding it or 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
    }
  ]
}

Discard Response Letter

Discard the response letter for a case so that requesting a letter writes a new one. The attached documents remain attached to the case. After deleting the letter, request a letter to prepare a new one.

Discarding a letter that is still being written abandons that work: the letter it would have produced is not delivered. A case with no letter to discard answers 404, the same answer reading the letter gives. This request takes no body. A request that carries one answers 400 Bad Request.

Request

DELETE /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

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

Direct Upload and Download

Initialize 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.