Sign in

v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB
Exception

Open a dispute

Use this endpoint to open a new dispute for an exception. Disputes are used to formally challenge or investigate discrepancies with external parties.

post/v1/exceptions/{exceptionId}/disputes

Path parameters

exceptionIdstring required

Exception ID

Headers

X-Request-Idstring

A unique identifier for tracing the request across services.

X-Idempotency-Keystring

Optional idempotency key for safe retries. Also accepts Idempotency-Key as an alternative header name. If the same key is sent again and the original request was already processed, the cached response is returned with X-Idempotency-Replayed: true.

See Retries and idempotency for details.

Request body

categorystring required

Category of the dispute

descriptionstring required

Detailed description of the dispute

Example request

{
  "category": "AMOUNT_MISMATCH",
  "description": "Transaction amount differs from invoice"
}

Response

Indicates that the resource was successfully created.

The response includes the X-Idempotency-Replayed header.

If the value is false, the request was just processed. If the value is true, the response is a replay of a previously processed request.

See Retries and idempotency for more details.

category'BANK_FEE_ERROR' | 'UNRECOGNIZED_CHARGE' | 'DUPLICATE_TRANSACTION' | 'OTHER'

Category of the dispute

createdAtstring

Creation timestamp in RFC3339 format

descriptionstring

Description of the dispute

exceptionIdstring

Exception ID this dispute is for

idstring

Unique identifier for the dispute

openedBystring

User who opened the dispute

reopenReasonstring

Reason for reopening if reopened

resolutionstring

Resolution description when closed

state'DRAFT' | 'OPEN' | 'PENDING_EVIDENCE' | 'WON' | 'LOST'

Current state

updatedAtstring

Last update timestamp in RFC3339 format

Example response

{
  "category": "BANK_FEE_ERROR",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "description": "Transaction amount differs from expected",
  "evidence": [
    {
      "comment": "Bank statement attached",
      "disputeId": "019c96a0-10d2-7193-8841-0d7347efd09a",
      "fileUrl": "https://storage.example.com/evidence/doc123.pdf",
      "id": "019c96a0-0c0d-7915-84b9-e497bfee9916",
      "submittedAt": "2025-01-15T10:30:00.000Z",
      "submittedBy": "user@example.com"
    }
  ],
  "exceptionId": "019c96a0-10d2-7134-ba5f-664142ee7052",
  "id": "019c96a0-10d2-7193-8841-0d7347efd09a",
  "openedBy": "user@example.com",
  "reopenReason": "New evidence discovered",
  "resolution": "Counterparty confirmed error",
  "state": "OPEN",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}