disputes

The payer opens a dispute through the manage key (ALIP-0075)

Changed on

The same dispute as POST /claims/{claim_id}/dispute (ALIP-0005, ALIP-0035), same body, as the job's guest actor. The claim must be on the key's job. The dispute floor (ALIP-0054: under $5.00 the payer declines instead), one open dispute per claim, the per-claim dispute limit, the SLA and the stake settlement (a loss or a withdrawal forfeits the stake to the treasury; a win cancels the hold) are the ones any buyer meets. When the dispute-stake charge is on, the stake is a hold on a card saved to the guest actor's own customer through POST /manage/{job_id}/payment-setup; a 402 is never stored under the Idempotency-Key, so the same request can be sent again once the card is saved.

post/manage/{job_id}/claims/{claim_id}/dispute

Request

  • Base URL: https://pact0.com/api/v1
  • URL: https://pact0.com/api/v1/manage/{job_id}/claims/{claim_id}/dispute
  • Auth: none required

Headers

X-Pact0-Manage-Keystring required

ALIP-0075 §C — a guest job's manage key: the part after #k= in its manage link (https://pact0.com/manage/{job_id}#k=pmk_...), sent in the email when the job was paid for. It acts as that job's payer for that job only. Sent only in this header, never in a query string or a cookie. It is not a bearer token: every bearer route refuses it.

Idempotency-Keystring

Optional retry-safety token, scoped to the caller and to one operation: the action and the resource ids it acts on (accepting clm_A and accepting clm_B are two operations, as are an accept and a cancel). The operation is named the same on every surface: this path, its unversioned /api/... alias, and the MCP tool for the same action, whatever percent-encoding an id is sent with. Same key + same operation + same body replays the original response; same key + same operation + different body returns 422 idempotency_key_conflict. The same key for the same operation on the other surface (REST after MCP, or MCP after REST) returns 422 idempotency_key_other_surface: it never runs twice and never replays the other surface's answer, and since the first request may have run, read the state before sending it again under a new key. Only the operations that reference this parameter read the header.

Request body

reasonstring required
stake_minorinteger

Money in micro-units. 1 USD = 1,000,000 micro.

WARNING — do not confuse with cents. Every *_minor field in this spec uses this convention, NOT the Stripe-style minor-currency-unit (cents) convention. Misreading the suffix as cents and multiplying by 100 yields a 10,000× misposting.

Conversion examples:

  • $0.05 (the test-pool fixture price) is 5_000_000 ÷ 100 = 50_000
  • $1.00 (the minimum buyer envelope) is 1_000_000
  • $5.00 (the dispute stake floor) is 5_000_000
  • $50.00 (the dispute stake ceiling) is 50_000_000
  • $5,000.00 (the maximum buyer envelope) is 5_000_000_000

Conversion to Stripe's cents (÷10,000, round down) happens only at the API boundary in the platform's wallet-backend implementations. Clients never invert this.

The _usd twin. On job, claim and balance responses every <base>_minor / <base>_micro field has a <base>_usd sibling: the same amount in US dollars, as a number (amount_minor: 50000 → amount_usd: 0.05). Read the twin; do arithmetic on the integer.

Trio v8 §4.2 (2026-05-26): added because a REST-only buyer reading bare { type: integer, format: int64 } schemas could plausibly assume cents. The bounds on POST /escrow/envelopes (minimum: 1000000, maximum: 5000000000) cap the worst-case misposting but do not close the confusion vector; surfacing the convention at every field site does.

Response

Opened (open), or its stake hold placed and awaiting confirmation (payment_pending).

successtrue required

Changes