Dispute and transaction lifecycle

A dispute is a cardholder's claim that one or more transactions are wrong: unauthorized, charged twice, never delivered, not as described. Casap takes the claim, investigates it, recovers money from the other side where the rules allow, and decides. The dispute has one status. Each transaction inside it has its own path, and that path is where the detail lives.

Dispute and transactions

One dispute holds one or more disputed transactions. The cardholder makes one claim, such as a lost card with six charges on it or a subscription billed three times, and Casap takes it once: one questionnaire, one thread of communication. The network side works per transaction. Each one has its own case, its own evidence, its own deadline, and its own decision, so each disputed transaction carries its own state and outcome. The dispute closes when every one of them has a final decision.

Dispute

status	Meaning
DISPUTE_STATUS_OPEN	At least one transaction is still in flight.
DISPUTE_STATUS_CLOSED	Every transaction has a final decision.

Transaction before the dispute

A transaction is what the cardholder disputes. Casap reads it from your core or receives it from you, and keeps two things about it: whether it has settled, and whether it can still be disputed.

State	Meaning
TRANSACTION_STATUS_PENDING	Authorized, not yet posted. The amount can still change or drop off.
TRANSACTION_STATUS_SETTLED	Posted to the account. The amount is final.

Only a settled transaction can be disputed. A cardholder who picks a pending one gets TRANSACTION_NOT_SETTLED from the Eligibility Check, and the right answer is to try again after it posts.

List Disputable Transactions returns the transactions a cardholder can dispute right now. Eligibility Check then confirms a specific selection and names anything wrong with it: a transaction older than your organization's window for online disputes, one already in an open dispute, a selection that mixes rails or spans more than one card, or a type your organization's rules exclude. The codes are listed under Errors. Pass the check and the selection is accepted exactly as sent.

You send transactions by the transactionIds your core knows them by. Casap answers with a uuid per disputed transaction, and every webhook action names that uuid so you can match it back to your own record. A dispute covers the full settled amount unless you say otherwise; see Disputing part of a transaction.

Transaction inside the dispute

Once a transaction is in a dispute, its settlement status never changes again. It carries a second status, the disputed-transaction state, and that state is the lifecycle most people mean when they say "the dispute lifecycle".

State	What is happening
DISPUTED_TRANSACTION_STATUS_OPEN	The claim is recorded. Casap is checking it against the transaction and the cardholder's answers.
DISPUTED_TRANSACTION_STATUS_INVESTIGATING	Casap is gathering evidence, contacting the merchant where useful, and watching the regulatory clock. An ACH return, where the window allows one, happens in this state.
DISPUTED_TRANSACTION_STATUS_CHARGEBACK	Casap has filed with the card network and is working the case through representment and arbitration. Only card rails reach this state, and only when the evidence supports a filing.
DISPUTED_TRANSACTION_STATUS_FINAL_DECISION	Casap has decided. Credits are being settled.
DISPUTED_TRANSACTION_STATUS_CLOSED	Nothing remains to do.

Decision

Outcome	Meaning	Money
RECORD_FINAL_DECISION_TYPE_ACCEPTED	The cardholder was right, in whole or in part.	Any provisional credit becomes permanent, or a final credit is issued for the accepted amount.
RECORD_FINAL_DECISION_TYPE_DENIED	The claim did not hold.	Any provisional credit is reversed after the cardholder has been told.
RECORD_FINAL_DECISION_TYPE_CANCELED	The cardholder withdrew, or the merchant made it right before a decision.	Any provisional credit is reversed; nothing further is owed.

Provisional credit

While a card or ACH investigation runs, the regulation may require the cardholder to have the disputed amount back in the meantime. Casap decides when that is due and asks your systems to issue it through the Issue provisional credit action. At the decision it either stays, becomes a final credit, or is reversed, each as its own action.

Clocks

Regulation E governs debit cards, ATM and ACH; Regulation Z governs credit cards; the networks add their own filing windows. Casap tracks every clock and times its requests to you so that each one is met. You act when asked, and the dispute's resolutionDeadline tells you when the decision is due.

What the cardholder sees

The timeline on a dispute carries only cardholder-facing events: created, investigating, provisional credit, chargeback, merchant contact, information requested, evidence submitted, final decision, closed. Internal work, agent notes and requests aimed at your institution never appear there.