Raise a Dispute on Escrow — POST /api/escrow/dispute

If a release cannot be agreed upon, either the depositor or beneficiary can raise a dispute by calling this endpoint. This locks the escrow state to DISPUTED on-chain, preventing any release or further confirmation until the dispute is resolved. A FlareHQ arbiter will review the case. If you supplied a webhookUrl at creation time, FlareHQ will also POST an escrow.disputed event to your endpoint.

Only ACTIVE escrows can be disputed. If the escrow is already RELEASED or DISPUTED, the API returns a 400 error.

Endpoint

POST https://flarehq.xyz/api/escrow/dispute

Authentication

Pass your merchant bearer token in the Authorization header.

Authorization: Bearer fhq_sec_...

Request Body

string

required

The escrow reference ID from POST /api/escrow/create — e.g. "escrow_m5k2r1_a4b8c2".

string

required

The SCA wallet address raising the dispute. Must be the depositor or beneficiary of this escrow. The caller must be a wallet your merchant account controls.

string

required

A human-readable description of the dispute — e.g. "Service was not delivered within the agreed timeframe". Stored in the FlareHQ database and included in the webhook payload. Defaults to "No reason provided" if sent as an empty string.

Response

boolean

true when the dispute transaction was confirmed on-chain.

object

The updated escrow record.

Show escrow fields

string

Always "DISPUTED" on a successful response.

string

The reason string saved to the escrow record.

string

The callerSCA address that raised the dispute.

string

On-chain transaction hash for the dispute transaction.

string

The on-chain transaction hash for this dispute.

string

ArcScan link — https://testnet.arcscan.app/tx/{txHash}.

string

Confirms the dispute has been raised and is pending admin review.

Examples

curl -X POST https://flarehq.xyz/api/escrow/dispute \
  -H "Authorization: Bearer fhq_sec_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "escrow_m5k2r1_a4b8c2",
    "callerSCA": "0xDepositorSCAWalletAddress",
    "reason":    "Service was not delivered within the agreed 48-hour window"
  }'

const response = await fetch("https://flarehq.xyz/api/escrow/dispute", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fhq_sec_YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: "escrow_m5k2r1_a4b8c2",
    callerSCA: "0xDepositorSCAWalletAddress",
    reason:    "Service was not delivered within the agreed 48-hour window",
  }),
});

const data = await response.json();
console.log(data.escrow.status); // "DISPUTED"

Success Response

{
  "success": true,
  "escrow": {
    "reference":      "escrow_m5k2r1_a4b8c2",
    "status":         "DISPUTED",
    "disputeReason":  "Service was not delivered within the agreed 48-hour window",
    "disputedBy":     "0xDepositorSCAWalletAddress",
    "disputeTxHash":  "0x111aaa222bbb333ccc444ddd555eee666fff777888999000aaabbbccc111222"
  },
  "txHash":      "0x111aaa222bbb333ccc444ddd555eee666fff777888999000aaabbbccc111222",
  "explorerUrl": "https://testnet.arcscan.app/tx/0x111aaa222bbb333...",
  "message":     "Dispute raised. FlareHQ admin will review and resolve."
}

Error — Escrow Not Active

{
  "success": false,
  "error": "Escrow is RELEASED — cannot dispute."
}

Webhook Payload (`escrow.disputed`)

When a webhookUrl was registered at escrow creation, FlareHQ delivers the following event:

{
  "event":      "escrow.disputed",
  "reference":  "escrow_m5k2r1_a4b8c2",
  "amount":     200,
  "currency":   "USDC",
  "disputedBy": "0xDepositorSCAWalletAddress",
  "reason":     "Service was not delivered within the agreed 48-hour window",
  "txHash":     "0x111aaa222bbb333ccc444ddd555eee666fff777888999000aaabbbccc111222",
  "disputedAt": "2025-07-14T16:45:00.000Z",
  "explorerUrl": "https://testnet.arcscan.app/tx/0x111aaa222bbb333..."
}

Once an escrow is DISPUTED, neither party can initiate a release. The FlareHQ arbiter has sole authority to resolve the dispute and direct the funds. Plan your integration flow accordingly.

Overview

Payments

Escrow

Streaming

x402

Agents

Raise a Dispute on Escrow — POST /api/escrow/dispute

Endpoint

Authentication

Request Body

Response

Examples

Success Response

Error — Escrow Not Active

Webhook Payload (`escrow.disputed`)

​Endpoint

​Authentication

​Request Body

​Response

​Examples

​Success Response

​Error — Escrow Not Active

​Webhook Payload (escrow.disputed)

Endpoint

Authentication

Request Body

Response

Examples

Success Response

Error — Escrow Not Active

Webhook Payload (`escrow.disputed`)