Disputes
A cardholder's dispute of a debit card purchase is a consumer error-resolution case on the deposit account. Credit card lines have a billing-error case of their own, and recoveries from a network are recorded as scheme cases.
The dispute object
A dispute is a Regulation E error notice on a consumer deposit account, worked by staff. It covers a cleared card purchase the same way it covers an ACH entry or an instant payment. Wires and credit accounts are refused. Writes need a staff token with compliance:write and an authentication within five minutes.
POST /disputes records the notice: customer_id, account_id, transaction_ref, error_kind, reason, notice_method (oral or written), received_at, transaction_date, the three amounts claimed (principal_amount, fees_amount, interest_amount) and an evidence_ref.
error_kindisunauthorized_eft,incorrect_eft,omitted_eft,bookkeepingordocumentation.original_journal_keynames the posted journal, and itssource_refmust equaltransaction_ref. Onlyomitted_eftanddocumentationcases may go without one.- The customer must be a person who owns the account, and the account's product must be listed in the policy.
The case captures its deadlines when it is opened. initial_due is 10 bank business days after the notice, or 20 when the transaction fell within 30 days of the account's first deposit. investigation_due is 45 calendar days, or 90 for a new account, a point_of_sale transaction or one outside_state.
States
state.status | Meaning |
|---|---|
investigating | Open. No determination yet. |
determined | A resolution was approved. The correction or the results notice is still outstanding. |
awaiting_recovery | The provisional credit was larger than the confirmed error, and the difference has not been recovered or waived. |
closed | Corrected, the results notice recorded, and the provisional notice recorded if a provisional credit was made. |
GET /disputes/deadlines lists what is due on each case and whether it is overdue.
Provisional credit and resolution
Money moves only through an action that one staff member proposes and another approves. POST /disputes/{id}/actions takes a kind, amounts, a reason and evidence_keys. Each key is intake, for the notice itself, or the idempotency key of evidence already recorded on the case. One action may be pending at a time. The decision needs operations:approve, cannot come from the proposer, and posts the journal when it approves.
kind | What it does |
|---|---|
provisional | Credits the customer the full amount claimed, once, before the determination. |
resolve | Records the outcome: error, partial_error, no_error or documentation. Credits the customer whatever the confirmed amount exceeds the provisional credit by. |
recover | Debits the part of the provisional credit that was not confirmed, on the date a recorded recovery notice named. That date must be at least five bank business days after the notice. The debit never overrides a debit block or creates an overdraft. |
waive_recovery | Writes the outstanding recovery off to expense instead. |
POST /disputes/{id}/notices records that a provisional, results or recovery notice was sent. It does not send anything. Each completed action publishes compliance.dispute.action_completed.
The dispute policy
Intake is off until the compliance service is given a policy file through its COMPLIANCE_DISPUTE_POLICY_FILE setting. Without one, POST /disputes answers 409 conflict. The file is JSON: an id, the legal_entity, the suspense_gl_code and expense_gl_code the postings use, the product_codes covered, max_claim_amount, and the bank's calendar as timezone, business_days, closed_dates, valid_from and valid_through. Each case keeps the policy it was opened under.
Credit cards and the networks
A written billing-error notice about a draw on a consumer credit card line is a billing-error case on the facility. It needs a billing policy file on the lending service. The case protects the disputed amount from collection until a reviewed resolution of error, different_error or no_error, the result notice, and the grace period after it.
A scheme case records the bank's recovery from a network against one cleared purchase. It moves through the stages submitted, chargeback, representment, pre_arbitration, arbitration and closed, posts the recovery and the cash received, and never issues a second credit to the customer. The core has no connection to a network's dispute system: it does not send a chargeback, receive a representment or evaluate scheme rules, and a case advances only on receipts signed by a processor key the bank has configured, which no simulator supplies today.