Dispute identifiers
Every dispute has two IDs: the Chargeflow dispute ID (id) that every API call takes, and source_id, the dispute ID on your processor. Store the mapping between them.
You have a dispute ID from Stripe, PayPal, or another processor and want to call the Chargeflow API with it. That call fails: the API only accepts the Chargeflow dispute ID. This page shows where to find it and how to keep the two IDs mapped.
The two IDs
| Field | What it is | Example | Accepted in API calls |
|---|---|---|---|
id | The Chargeflow dispute ID, a 24-character hex string | 66e6ea9ecd94925a9f8060d9 | Yes, as {disputeId} |
source_id | The dispute's ID on the processor (source) | du_123456789 | No |
Every dispute endpoint takes the Chargeflow ID in the path, for example GET /public/2025-04-01/disputes/{disputeId}. There is no endpoint that looks a dispute up by source_id.
Symptom: 400 or 404 on a dispute call
Passing a processor ID such as du_123456789 as {disputeId} fails, because it does not match the
24-character hex pattern or any Chargeflow dispute. Look up the Chargeflow id in your mapping
table and retry with it.
Where both IDs appear together
You see id and source_id side by side in two places:
- The
dispute.createdwebhook, fired when Chargeflow ingests a new dispute. Both IDs are ondata. - The list disputes response (
GET /public/2025-04-01/disputes). Both IDs are on each item indisputes[].
{
"type": "dispute.created",
"data": {
"id": "66e6ea9ecd94925a9f8060d9",
"source": "stripe",
"source_id": "du_123456789",
"amount": 100,
"currency": "USD",
"status": "needs_response"
}
}Store the mapping on your side
Keep a table keyed by both IDs, so any system that only knows the processor's ID can resolve the Chargeflow one:
| Column | Source |
|---|---|
chargeflow_dispute_id | data.id / disputes[].id |
source | data.source / disputes[].source |
source_dispute_id | data.source_id / disputes[].source_id |
Index (source, source_dispute_id) as unique: two processors can issue the same dispute ID string. Fill the table from the webhook and backfill it from list disputes, as shown in the enrichment integration guide.