Statement Processing API

Upload payment processor statements and receive an analysis summary, authenticity score, period totals, and an Excel workup of the analyzed documents. Requests authenticate by secret key.

Statement Processing Lifecycle

Statement processing takes three steps:

Initialize the task (POST)
Upload documents (PUT)
Read the result (GET or web hook)

Initialize Statement Processing Task

Post the uploadFilenames of the documents to upload. The response carries a signed putUrl for each file.

Request

POST /statement/initialize
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  data: {
    uploadFilenames: [String]
  }
}

Field	Type	Required	Description
`uploadFilenames`	Array of Strings (filenames)	Yes	Filenames to upload. Duplicates are allowed

Response

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

Field	Type	Description
`id`	String (uuid)	Statement processing task ID
`putUrls`	Array of Objects	`putUrl` and `uploadFilename` pairs
`putUrls.putUrl`	String (url)	Signed URL for document `PUT`. Valid for five minutes
`putUrls.uploadFilename`	String (filename)	Member of `uploadFilenames`

Document Upload

Send each file to its putUrl with PUT.

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

Upload with curl:

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=..."

Statement Results

Read the analysis. It starts when the documents finish uploading and takes several minutes. The response carries status: "processing" while the agent works.

Request

GET /statement/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

{
  data: {
    analysisSummary: String,
    authenticityScore: Number,
    documents: [{}],
    id: String,
    periodEnd: Date,
    periodStart: Date,
    processor: String,
    status: String,
    totalChargebackAmount: Number,
    totalFeesAmount: Number,
    totalNetAmount: Number,
    totalRefundAmount: Number,
    totalSalesAmount: Number
  }
}

Field	Type	Description
`analysisSummary`	String	Summary of analysis and document authenticity
`authenticityScore`	Number (0-100)	How genuine the statement appears. Higher is more authentic
`documents`	Array of Objects	Detail for each analyzed document
`id`	String (uuid)	Statement processing task ID
`periodEnd`	Date (ISO 8601)	Latest statement date
`periodStart`	Date (ISO 8601)	Earliest statement date
`processor`	String	Statement payment processor, when analysis identifies it
`status`	String (enum)	`pending`, `queued`, `processing`, `complete`, `reopened`, or `error`
`totalChargebackAmount`	Number (dollars)	Chargebacks across all statements
`totalFeesAmount`	Number (dollars)	Fees across all statements
`totalNetAmount`	Number (dollars)	Net across all statements
`totalRefundAmount`	Number (dollars)	Refunds across all statements
`totalSalesAmount`	Number (dollars)	Sales across all statements

Web Hooks

Register a web hook in place of polling the statement results. The event body carries the same data as the GET response, plus metadata.

Event Metadata

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

Field	Type	Description
`attempt`	Number (integer)	Delivery attempt count, starting at `1`
`event`	String	`statement:processed`
`id`	String (uuid)	Event ID, unchanged across attempts. Idempotency token to prevent duplicate processing
`timestamp`	Number (milliseconds)	Attempt time. Changes with each attempt
`type`	String	`webhook`
`webhook`	String (uuid)	Endpoint receiving delivery

Acknowledgment

Code	Description	Result	Retried
`2XX`	Success	Delivered	No
`401`	Unauthorized	Failed authentication	No
`429`	Too many requests	Rate limited	Yes, with backoff
`5XX`	Server error	Receiver failed	Yes, with backoff
`504`	Gateway Timeout	No response after `15` seconds, or unreachable host	Yes, with backoff
`*`	Unknown error	Client error, including `3XX`	No

Undeliverable Messages

Retries stop one hour after the first attempt. Findustry AI contacts the organization to improve delivery rates.

Authentication

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

Registration

Contact support@findustryai.com to certify a web hook endpoint and enable events.

Request Download

Request the Excel workup of the analyzed documents. The response carries status: "processing" for several minutes while the agent works, then a getUrl.

Request

GET /statement/:id/download
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

Processing

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

Complete

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

Field	Type	Description
`getUrl`	String (url)	Signed URL for workup. Valid for five minutes
`id`	String (uuid)	Statement processing task ID
`status`	String	`processing` until workup is ready

Document Download

Download the workup from getUrl.

Download with curl:

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