fluxa

Disputes

A dispute is a customer-initiated chargeback against one of your orders. Disputes only ever arise in custodial/fiat flows; under non-custodial on-chain stablecoin settlement there are no chargebacks. List your disputes and submit a rebuttal to move a dispute that needs_response into under_review.

Chargebacks exist only in custodial/fiat flows, which are operator-internal. Under non-custodial on-chain stablecoin settlement, the net settles on-chain directly to your own wallet and cannot be reversed by the customer, so disputes do not arise for direct-settlement orders. If you settle on-chain, this list will be empty.

The dispute model

  • Name
    id
    Type
    string
    Description

    The dispute id.

  • Name
    order_id
    Type
    string
    Description

    The disputed order.

  • Name
    reason
    Type
    string
    Description

    The reason given for the chargeback.

  • Name
    amount
    Type
    string
    Description

    The disputed amount, as a decimal string.

  • Name
    currency
    Type
    string
    Description

    The dispute currency.

  • Name
    status
    Type
    string
    Description

    needs_response, under_review, won, or lost.

  • Name
    customer
    Type
    string
    Description

    The customer identifier, when known.

  • Name
    evidence_due
    Type
    timestamp
    Description

    Deadline to respond, or null.

  • Name
    evidence
    Type
    string
    Description

    Your submitted rebuttal text.

  • Name
    evidence_files
    Type
    array
    Description

    References to uploaded evidence attachments (time-limited URLs on read).

  • Name
    created_at
    Type
    timestamp
    Description

    When the dispute was opened.

GET/api/v1/disputes

List disputes

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Return your disputes as a plain data array. Any attachment references are presigned into short-lived URLs.

Request

GET
/api/v1/disputes
curl "$BASE/api/v1/disputes" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Response

{
  "data": [
    {
      "id": "dsp_1",
      "order_id": "ord_2Zx9Qw8sUaM2",
      "reason": "product_not_received",
      "amount": "49.90",
      "currency": "USD",
      "status": "needs_response",
      "evidence_due": "2026-06-18T00:00:00Z",
      "created_at": "2026-06-11T09:00:00Z"
    }
  ]
}
POST/api/v1/disputes/:id/evidence

Submit evidence

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Submit a rebuttal for a dispute. The optional evidence text is persisted, and a dispute in needs_response moves to under_review. The full dispute is returned.

Optional attributes

  • Name
    evidence
    Type
    string
    Description

    Free-text rebuttal describing why the charge is legitimate.

Request

POST
/api/v1/disputes/dsp_1/evidence
curl "$BASE/api/v1/disputes/dsp_1/evidence" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "evidence": "Tracking 1Z999 shows delivery on 2026-06-09." }'

Response

{
  "id": "dsp_1",
  "order_id": "ord_2Zx9Qw8sUaM2",
  "status": "under_review",
  "evidence": "Tracking 1Z999 shows delivery on 2026-06-09.",
  "amount": "49.90",
  "currency": "USD"
}