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)

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.

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

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.

Request

POST /chargeback/:id/upload
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    uploadFilenames: [String]
  }
}

Response

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

Each signed putUrl is valid for five minutes.

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.

Request

GET /chargeback/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

{
  data: {
    confidence: Number,
    defenseRequirements: [{ requirement: String, satisfied: Boolean }],
    evidenceProvided: [String],
    evidenceSuggested: [String],
    id: String,
    merchantAttachments: [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. Poll the same path with GET until the letter is ready, or register a web hook.

Request

POST /chargeback/:id/letter
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

Response

Processing

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

Complete

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

Initialize Agent with Direct Upload

POST /chargeback/upload
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    uploadFilenames: [String]
  }
}

{
  data: {
    id: String,
    putUrls: [
      {
        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.