Submit platform disputes

Create dispute records in Chargeflow from your platform - request fields, dispute reason values, and how to enrich or generate evidence afterward.

Use this endpoint to create dispute records in Chargeflow directly from your platform. This is useful when Chargeflow is not automatically ingesting disputes from a connected PSP, for example when your platform is the authoritative source of dispute data, or when you're operating in a bring-your-own-disputes model.

Create a dispute

POST /public/2025-04-01/platform/disputes

Request fields

Field	Type	Required	Description
`account_id`	string	Yes	The Chargeflow account ID of the merchant this dispute belongs to.
`source_id`	string	Yes	Your PSP's dispute ID, the unique identifier from the processor where the dispute originated.
`created_at`	ISO 8601 datetime	Yes	When the dispute was created at the processor.
`reason`	enum	Yes	The dispute reason code. See below for valid values.
`due_by`	ISO 8601 datetime	Yes	The evidence submission deadline.
`amount`	number	Yes	Disputed amount in the transaction currency. Must be ≤ the transaction amount.
`currency`	string	Yes	Three-letter ISO 4217 currency code in uppercase (e.g., `USD`).
`status`	enum	Yes	Current dispute status. Must be `needs_response`, `under_review`, `won`, or `lost`.
`stage`	enum	No	Dispute stage. One of: `Chargeback`, `Inquiry`, `Pre_arbitration`, `Arbitration`. Defaults to `Chargeback`.
`transaction`	object	No	Transaction details. Recommended for stronger evidence. See below.
`subscription`	object	No	Subscription details, if the disputed charge is subscription-related.
`order`	object	No	Order details including products, customer, shipping address, and fulfillment tracking.

Dispute reason values

Value	Description
`fraud`	Unauthorized transaction claim.
`not_received`	Customer claims goods or services were not received.
`not_as_described`	Customer claims goods or services differed from what was promised.
`canceled_recurring_billing`	Customer claims a recurring charge continued after cancellation.
`duplicate_charge`	Customer claims they were charged more than once for the same item.
`credit_not_processed`	Customer claims a refund was not applied.
`other`	Any reason not covered by the above.

Example request

Terminal

curl -X POST https://api.chargeflow.io/public/2025-04-01/platform/disputes \
  -H "x-api-key: YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "66e6ea9ecd94925a9f8060d9",
    "source_id": "du_123456789",
    "created_at": "2025-04-15T08:30:00Z",
    "reason": "fraud",
    "due_by": "2025-04-29T23:59:00Z",
    "amount": 249.99,
    "currency": "USD",
    "status": "needs_response",
    "stage": "Chargeback",
    "transaction": {
      "source_id": "tx_1234567890",
      "account_id": "66e6ea9ecd94925a9f8060d9",
      "created_at": "2025-04-10T14:22:00Z",
      "type": "paid",
      "amount": 249.99,
      "currency": "USD",
      "payment_method": {
        "type": "card",
        "brand": "visa",
        "last4": "4242",
        "country": "US"
      }
    }
  }'

Tip

Always include transaction data when available. Card verification results (3DS, AVS, CVC) are among the most impactful fields for fraud disputes.

After creating the dispute

Once the dispute record exists in Chargeflow you can:

Generate evidence via the EaaS Generate Evidence API, referencing the returned dispute ID.
Enrich the dispute with additional order or communication context before generating evidence.

Next steps

Generate & regenerate evidenceTurn the dispute into a bank-ready PDF.Monitor integration healthConfirm your platform key stays valid.