Generate evidence in seconds

Call the Generate Evidence API

POST /public/2025-04-01/evidence accepts either an existing Chargeflow dispute_id or a full inline dispute object. You do not need to create the dispute separately first. Provide exactly one of the two.

The dispute must be in needs_response status, otherwise the call returns 422_dispute_invalid_state.

Option A: reference an existing dispute:

curl -X POST https://api.chargeflow.io/public/2025-04-01/evidence \
  -H "x-api-key: YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "66e6ea9ecd94925a9f8060d9",
    "dispute": {
      "dispute_id": "66e6ea9ecd94925a9f8060d9"
    }
  }'

Option B: submit the dispute data inline:

curl -X POST https://api.chargeflow.io/public/2025-04-01/evidence \
  -H "x-api-key: YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "66e6ea9ecd94925a9f8060d9",
    "dispute": {
      "dispute_data": {
        "source_id": "du_123456789",
        "created_at": "2024-02-10T12:00:00Z",
        "reason": "fraud",
        "due_by": "2024-02-20T12:00:00Z",
        "amount": 150.00,
        "currency": "USD",
        "status": "needs_response",
        "transaction": {
          "source_id": "tx_1234567890",
          "created_at": "2024-02-08T10:00:00Z",
          "type": "paid",
          "amount": 150.00,
          "currency": "USD"
        }
      }
    }
  }'

The API responds immediately with in_progress. Generation is asynchronous, so the PDF is not in this response.

{
  "id": "ev_abc123456789",
  "account_id": "acct_9876543210",
  "ext_account_id": "ext_acct_54321",
  "dispute": "dp_1122334455",
  "created_at": "2025-07-29T14:35:00Z",
  "status": "in_progress",
  "file_url": null,
  "file_version": 1
}

Wait for the evidence.ready webhook

Do not poll in a tight loop. Chargeflow pushes the result to your webhook endpoint when the PDF is ready (evidence.ready) or if generation fails (evidence.error). Generation typically completes in about 30 seconds, with a maximum of around 3 minutes.

evidence.ready payload:

{
  "event": {
    "id": "evt_XXXXXXXXXXXXXXXX",
    "type": "evidence.ready",
    "created_at": "2025-07-29T12:34:56Z"
  },
  "evidence": {
    "id": "ev_abc123456789",
    "account_id": "acct_9876543210",
    "ext_account_id": "ext_acct_54321",
    "dispute": "dp_1122334455",
    "created_at": "2025-07-29T14:35:00Z",
    "status": "completed",
    "file_url": "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf",
    "file_version": 1
  }
}

Acknowledge with a 2XX quickly, then download or store the PDF asynchronously.

app.post('/webhook', express.json(), (req, res) => {
  const event = req.body;
  res.json({ received: true }); // acknowledge first

  if (event.event?.type === 'evidence.ready') {
    const { id, file_url } = event.evidence;
    // Download the PDF and submit it to your PSP
    saveEvidencePdf(id, file_url);
  }

  if (event.event?.type === 'evidence.error') {
    // event.error_code and event.error_message explain what failed
    console.error(event.error_code, event.error_message);
  }
});

The evidence.error payload includes error_code and error_message, for example 422_dispute_invalid_state with "Dispute status must be needs_response". See How It Works for both payload shapes.

Fetch the latest evidence link

The download link expires 7 days after it is issued. If you need a fresh link later, read the evidence record by its id with GET /public/2025-04-01/evidence/{evidenceId}.

curl -X GET https://api.chargeflow.io/public/2025-04-01/evidence/ev_abc123456789 \
  -H "x-api-key: YOUR_PLATFORM_API_KEY"

The response carries the current status, file_url, and file_version:

{
  "id": "ev_abc123456789",
  "account_id": "acct_9876543210",
  "ext_account_id": "ext_acct_54321",
  "dispute": "dp_1122334455",
  "created_at": "2025-07-29T14:35:00Z",
  "status": "completed",
  "file_url": "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf",
  "file_version": 1
}

Regenerate when new data arrives (optional)

While the dispute is still in needs_response, you can regenerate the package to fold in new data such as tracking, fulfillment, or added communication logs. Call the same Generate Evidence endpoint again. Each regeneration increments file_version.

curl -X POST https://api.chargeflow.io/public/2025-04-01/evidence \
  -H "x-api-key: YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "66e6ea9ecd94925a9f8060d9",
    "dispute": { "dispute_id": "66e6ea9ecd94925a9f8060d9" }
  }'

Report the outcome

When the dispute resolves (won or lost), share the outcome with Chargeflow so the AI keeps improving win rates across your merchants. There is no public endpoint for this yet.