Chargeback Agent API

Upload dispute documents and receive a recommendation, recommended actions, and a formal response letter. Requests authenticate by secret key.

Agent Lifecycle

A case moves through these 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)

Repeat the attach and recommendation steps until the case is ready. Each recommendation reports its confidence and suggests further evidence to attach.

When the recommendation is ready, download the PDF in two steps:

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

Initialize Chargeback Case

Initialize an agent session with chargeback case details. The response carries the case id for later requests. No field is required, and a complete request body gives the best results.

A blank field is treated as omitted. null and an empty string mean the same thing. On initialize the field stays unset, and on update the field is cleared.

Request

POST /chargeback
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  data: {
    agent: Boolean | Object,
    amount: 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

The response returns the submitted details with the case id and status. The reason code defenseRequirements are available immediately. Each requirement changes to satisfied: true as evidence arrives. Meet as many requirements as possible to maximize success.

evidenceSuggested and evidenceProvided describe the evidence types that meet defense requirements, in merchant-friendly terms. recommendedActions lists more specific actions.

{
  data: {
    amount: 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. The field is accepted on the request and never returned.

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

Evidence Categories

evidenceProvided and evidenceSuggested use the lowercase values below.

Update Case Details

Post only the fields to change. Fields omitted from data stay unchanged. The request accepts the same fields as initialize, except agent, which answers 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. Clearing referenceNumber answers 400 Bad Request.

Request

POST /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  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_nnnnn

Response

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

Attach Documents to Case

Post the uploadFilenames, then send each file's contents to its signed putUrl, as in document upload. The next recommendation assesses each attached document.

Attach documents to cases initialized with POST /chargeback. A session initialized with direct upload takes its documents at initialization, and this endpoint answers 400 Bad Request for it.

Request

POST /chargeback/:id/upload
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  data: {
    uploadFilenames: [String]
  }
}

Response

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

Each signed putUrl is valid for five minutes. Each evidenceId identifies the attached document for evidence deletion.

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.

The agent reassesses the case about thirty seconds after the last deletion, so a burst of deletions is assessed once. The recommendation shows status: "processing" during reassessment and completes with the remaining evidence.

Deleting evidence also retires any response letter already written, because the letter argued from the deleted document. GET /chargeback/:id/letter answers 404 Not Found until the next response letter request, which rewrites the letter from the remaining evidence. To replace a letter and keep the evidence, discard the letter instead.

Request

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

Response

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

Agent Recommendation

After each document upload, the agent assesses the case and provides a recommendation and recommended actions. The response shows status: "processing" while the agent works. Assessment takes several minutes.

Every status returns the submitted case fields and the current status. On completion, the response adds the recommendation fields.

Request

GET /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

Processing

{
  data: {
    amount: 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: {
    amount: 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
  }
}

When processing fails, the response carries a message in place of the recommendation.

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

Generate Response Letter

When the recommendation is satisfactory, request a formal response letter. The response shows status: "processing" while the agent works. Writing takes several minutes. Read the letter until it is ready, or register a web hook.

The agent writes a letter once, and only on request. A repeat request returns the existing letter. To replace a letter, discard it first.

This request takes no body. A request with a body answers 400 Bad Request.

Request

POST /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

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. The request answers 404 Not Found when the letter was never requested, or was retired by discarding it or by deleting evidence.

Request

GET /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

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, then request a letter to write a new one. The attached documents stay attached to the case.

Discarding a letter in progress abandons it, and the agent delivers no letter from that work. A case with no letter to discard answers 404 Not Found, as reading the letter does. This request takes no body. A request with a body answers 400 Bad Request.

Request

DELETE /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

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

Direct Upload and Download

Initialize with Direct Upload

POST /chargeback/upload
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  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_nnnnn

{
  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

Register a web hook in place of polling the agent status. The event body carries the same data as the HTTP response, plus metadata. Security headers authenticate each delivery.

Event Metadata

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

Acknowledgment

Undeliverable Messages

Findustry AI retries an undeliverable message for up to one hour. When a message still fails after one hour, Findustry AI contacts the organization to discuss delivery rates.

Authentication

Each web hook delivery carries an HMAC signature in the X-Webhook-Signature header. See Web Hooks authentication.