Minctrl Docs
Cookbook

Chargeback representment

Turn an inbound dispute into a filed representment packet or a clean refund with the chargeback-representment example — a disputes manager signs every fight-vs-refund call and every network filing.

Scenario. An inbound chargeback is ingested and classified by network reason code. The run scores winnability and assembles a compelling-evidence packet concurrently. A disputes manager signs the fight-vs-refund decision before the response is filed to the card network — and signs again at every irreversible network filing downstream.

Example: chargeback-representment · Parks at gate step-id: signoff (gate:fight-vs-refund-signoff). A clear loss ("risk": "clear loss") routes to accept-signoff (gate:accept-chargeback-signoff) instead, and a low-value dispute ("risk": "low-value") gets an automatic goodwill refund without a fight-vs-refund gate.

1. Import the example

curl -s -o chargeback-representment.process.json https://minctrl.com/examples/chargeback-representment.process.json
jq -n --slurpfile doc chargeback-representment.process.json '{document: $doc[0]}' \
  | curl -s -X POST "$API/process-templates/import" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @- | jq '{slug, version, executable_violations}'

The example is now a process in your company under the slug chargeback-representment (see Example processes for registering first).

2. Start the run

RUN=$(curl -s -X POST "$API/process-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "chargeback-representment",
    "draft": true,
    "inputs": {
      "dispute_id": "CB-88231",
      "reason_code": "10.4",
      "amount": 249.00,
      "network": "visa",
      "risk": "high-value"
    }
  }')
RUN_ID=$(echo "$RUN" | jq -r .id)

The run classifies the dispute, scores winnability, assembles the evidence packet, runs QC, and parks at the fight-vs-refund gate. risk is the routing input the resolver matches against the branch labels: "high-value" routes the compliant packet to the fight-vs-refund gate.

3. Read where it parked

curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN"

status is awaiting_human and trace.parked_step is signoff. Had you started with "risk": "clear loss", it would be accept-signoff; resume with whichever step-id the run parked on.

4. Resume — the disputes manager signs

curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gate": "signoff",
    "decision": "approved"
  }'

An approved fight decision proceeds to file the response to the network (shadowed). The signoff gate has a single way forward, so a denied verdict resolves to no branch and the run stays parked at signoff; a dispute you mean to concede goes through accept-signoff.

5. Outcome — parks again

After the response is filed, the run tracks network responses, assembles the pre-arbitration rebuttal, and parks again at prearb-signoff (gate:prearb-signoff) before the next irreversible network filing. Each irreversible filing is fronted by its own manager gate, so expect this run to park more than once.

In the simulated run the monitoring branch takes its first edge (pre-arbitration) on every lap, so signing prearb-signoff brings the run back to the same gate (trace.parked_visit: 2) rather than on to arb-signoff; the low-value goodwill-refund path reaches prearb-signoff the same way. With a live network connector the branch follows the issuer's actual response.

Governance note

The submit, prearb-submit, arbitration-file, and accept-chargeback steps are reversible: false — a filing to a card network can't be recalled — and stay shadowed until a connector opts in. Every one is protected by a manager gate (signoff → prearb-signoff → arb-signoff) so no irreversible network filing fires without a signed human verdict.

On this page