Disputes Intake API-Pilot Client Usage

Global Usage Summary

Disputes Intake API Lifecycle

The Disputes Intake API exposes a guided, state-driven workflow for creating, reviewing, and submitting dispute claims.

Endpoints are intended to be called in a specific order, with clear transitions between Draft and Hard Case states.

End-to-End Lifecycle Overview

Phase-by-Phase Usage Details

1. Retrieve Transactions

Endpoint: POST /transactions

Purpose:

Returns transactions within a date range that may be eligible for dispute.

Key Characteristics:

• Does not create claim state
• Supports identifying transactions via arn, authCode, or both
• Read-only discovery step

2. Create Draft Claim

Endpoint: POST /claim

Purpose:
Creates a Draft Case, with behavior dependent on the dispute scenario:

• Lost or Damaged Card (No Fraud / Unauthorized Activity):

  • Creates a Draft Case without any Case Items

• Lost/Stolen Card with Potential Fraud or Transaction Disputes:

  • Creates a Draft Case with one or more Case Items derived from disputed transactions

Important:
- Draft cases are not worked by the resolution process
- Draft cases can still be:
- Modified
- Canceled
- Finalized at a later step

3–6. Claim Questionnaire Flow

The questionnaire is a stateful, step-by-step flow managed entirely by the backend.

Retrieve Current Question

• GET /claim/question

Submit an Answer

• POST /claim/question
• Returns the next question
• Eliminates the need for additional GET calls

Undo Last Answer

• POST /claim/question/undo
• Returns the previous question to answer next

Completion Signal

• POST /claim/question returns: "questionnaire": null
• Indicates all questions have been answered

7. Review Questionnaire Answers (Optional)

Endpoint: GET /claim/question/review
Purpose:
Provides a read-only summary of all answered questionnaire fields prior to submission.

Used to:
- Display a review screen
- Confirm accuracy before finalization

8. Add Notes (Optional)

Endpoint: POST /claim/operation/note

Purpose:
Adds informational notes to:
- Draft cases
- Finalized (Hard) cases

Notes:
- Does not modify claim state
- Can be added at any time

9. Add Documents (Optional)

Endpoint: POST /claim/operation/document

Purpose:
Adds relevant documents to:
- Draft cases
- Finalized (Hard) cases

Notes:
- Does not modify claim state
- Can be added at any time

10. Cancel Draft Claim or Items (Optional)

Endpoint: POST /claim/cancel

Purpose:
Cancels:
- One or more Draft Case Items, or
- One or more Draft Cases

Rules:
- Only draft claims can be canceled
- Hard Cases cannot be undone or removed

11. Finalize Claim (Submit)

Endpoint: POST /claim/finalize

Purpose:
Converts a Draft Case → Hard Case.

Impact:
- Claim is officially submitted for dispute processing
- Claim becomes immutable
- No further cancellation or questionnaire edits allowed

Draft vs Hard Case Summary