Close a dispute

Use this endpoint to close a dispute with a resolution. The dispute can be marked as won or lost based on the outcome.

POST /v1/disputes/{disputeId}/close

Close a dispute

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/disputes/{disputeId}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "resolution": "Counterparty acknowledged the error and issued correction",
  "won": true
}
'

200

Example

{
  "category": "BANK_FEE_ERROR",
  "createdAt": "2025-01-15T10:30:00Z",
  "description": "Transaction amount differs from expected",
  "exceptionId": "550e8400-e29b-41d4-a716-446655440001",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "openedBy": "[e-mail]",
  "state": "OPEN",
  "updatedAt": "2025-01-15T10:30:00Z",
  "evidence": [
    {
      "comment": "Bank statement attached",
      "disputeId": "550e8400-e29b-41d4-a716-446655440001",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "submittedAt": "2025-01-15T10:30:00Z",
      "submittedBy": "[e-mail]",
      "fileUrl": "https://storage.example.com/evidence/doc123.pdf"
    }
  ],
  "reopenReason": "New evidence discovered",
  "resolution": "Counterparty confirmed error"
}

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Encabezados

X-Request-Id · string

A unique identifier for tracing the request across services.

X-Idempotency · string

Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with X-Idempotency-Replayed: true. A malformed key returns 400, a key whose first request is still in progress returns 409 (MTCH-0018), a key whose earlier attempt already ran but whose answer cannot be replayed returns 409 (MTCH-0022), and an idempotency storage failure returns 500. POST, PUT, PATCH and DELETE requests accept the header. These refusals are problem documents.

Parámetros de ruta

disputeId · string<uuid> · requerido

Dispute ID Dispute ID (UUID)

Ejemplo:

"550e8400-e29b-41d4-a716-446655440001"

Cuerpo

application/json

Close dispute payload

resolution · string · requerido

Resolution description

Required string length: 1 - 5000

Ejemplo:

"Counterparty acknowledged the error and issued correction"

won · boolean · requerido

Whether the dispute was won

Ejemplo:

true

Respuesta

200

application/json

Indicates that the request was successful and the response contains the expected data.

category · enum<string> · requerido

Dispute category: BANK_FEE_ERROR (incorrect fee), UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, AMOUNT_MISMATCH, or OTHER

Opciones disponibles: BANK_FEE_ERROR, UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, AMOUNT_MISMATCH, OTHER

Ejemplo:

"BANK_FEE_ERROR"

createdAt · string · requerido

Creation timestamp as an RFC 3339 timestamp

Ejemplo:

"2025-01-15T10:30:00Z"

description · string · requerido

Description of the dispute

Ejemplo:

"Transaction amount differs from expected"

exceptionId · string · requerido

Identifier of the exception this dispute is for (UUID)

Ejemplo:

"550e8400-e29b-41d4-a716-446655440001"

id · string · requerido

Unique identifier for the dispute (UUID)

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

openedBy · string · requerido

User who opened the dispute

Ejemplo:

"[e-mail]"

state · enum<string> · requerido

Dispute state: DRAFT, OPEN, PENDING_EVIDENCE (awaiting evidence), WON, or LOST

Opciones disponibles: DRAFT, OPEN, PENDING_EVIDENCE, WON, LOST

Ejemplo:

"OPEN"

updatedAt · string · requerido

Last update timestamp as an RFC 3339 timestamp

Ejemplo:

"2025-01-15T10:30:00Z"

evidence · object[] | null

Evidence items submitted for this dispute (max 50)

Maximum array length: 50

Show child attributes

reopenReason · string

Reason recorded when the dispute was reopened

Ejemplo:

"New evidence discovered"

resolution · string

Resolution description recorded when the dispute was closed

Ejemplo:

"Counterparty confirmed error"