# Delivery complaints and responses

Use this free workflow when a settled 402Mob purchase did not produce the expected delivery. The buyer and original payment recipient sign statements; 402Mob retains their history. A complaint is an allegation, not a finding of fault. It does not reverse payment.

```text
settled operation
       |
signed read -> operation binding
       |
buyer signs binding + complaint ----> seller responds
       |                           |
       +------ buyer closes <------+
              resolved / unresolved

payment state   | delivery state   | complaint state
     separate records; silence never means acceptance
```

## Before opening

Keep the operation ID returned by checkout. For fresh work use `ticket.payment.operationId` from the HTTP/MCP ticket response, or `payment.operationId` on the SDK ticket object, not the ticket ID. If payment is `pending`, recover that same operation first; do not pay again or call it settled non-delivery.

Only the payer wallet can open or close. Only the original operation's payment-recipient wallet can respond. Either wallet can read the private case. These actions require an EIP-191 signer and an HTTP POST client or connected hosted MCP client. A merchant API key alone does not authorize them. Contract-wallet EIP-1271 signatures and transaction-proof alternatives are not supported in this first version.

One case is allowed per operation. Open it while the operation is settled and within its existing retention window (normally seven days). There need not be a delivered result. Existing `accepted`/`disputed` receipts remain separate records and do not automatically create a case.

## 1. Read the operation binding privately

First request a read challenge:

`POST /v1/operations/{operationId}/dispute-challenges`

```json
{"wallet":"0xYOUR_BUYER_ADDRESS","action":"read"}
```

Check the exact message: it must contain this service’s origin, your operation ID, your requested statement, nonce and expiry, and the fixed consent text limiting authority to a statement or private read. A read challenge contains `Binding: null`. Sign that message with EIP-191 and submit the returned `challengeId`, `challengeToken` and signature to `/v1/operations/{operationId}/dispute-actions`. Keep the returned `binding` object and, if present, `dispute.revision`.

The authenticated response supplies the payer, recipient, request hash, Work Ticket and quote references, result hash, transaction, amount, asset and network. Check those details against the purchase you intend to discuss. `resultHashAtOpen` in this current binding is the result hash observed at the read; the case’s saved opening binding remains unchanged after later delivery.

Challenge creation returns HTTP 201 for any schema-valid operation UUID and request, including unknown operations or unrelated wallets. It uses only caller input: no private metadata, case existence or eligibility is returned. Operation, wallet role, expiry, revision and binding checks occur after signature verification on submission. HTTP 201 is not confirmation that a case can be opened.

## 2. Buyer requests an opening challenge

`POST /v1/operations/{operationId}/dispute-challenges`

```js
const request = {
  binding: evidence.binding, // Full object returned by the latest signed read.
  "wallet": "0xYOUR_BUYER_ADDRESS",
  "action": "open",
  "expectedRevision": 0,
  "reason": "not_delivered",
  "detail": "Payment settled, but I cannot retrieve the promised work result.",
  "evidenceHashes": []
};
```

Here `evidence` is the authenticated read response. Send `JSON.stringify(request)` as the HTTP body. Replace the address and operation ID with actual values. Reasons are `not_delivered`, `unreadable`, and `terms_mismatch`. `detail` is required, trimmed, and limited to 2,000 Unicode code points; `evidenceHashes` is required and accepts up to eight lowercase SHA-256 hex strings. Hashes are references supplied by the participant, not evidence that 402Mob fetched or verified. Do not put private keys, bearer tokens or payment authorizations in a statement.

The response contains `challengeId`, an opaque `challengeToken`, the exact `message` to sign, `expiresAt`, and the `submit` path. Return `challengeToken` unchanged with the signature. Challenge issuance is stateless: unsigned requests do not reserve database rows or consume a shared case quota. Normal per-client request rate limits still apply. A challenge expires after two minutes. It is not a recorded complaint or an eligibility check. Write requests require the full `binding` object from the signed read; the service echoes that caller-supplied binding into the message and checks it against the current operation only after signing. If it changed, HTTP 409 `dispute_binding_conflict` requires a fresh read and a newly signed statement. Its message binds the operation, statement, original payer/recipient, request hash, payment reference and, for fresh work, the quote terms hash. A request hash is not a certification of seller promises. Preserve the offer or accepted quote independently.

## 3. Sign and submit

Sign the returned message with the buyer wallet using EIP-191, then:

`POST /v1/operations/{operationId}/dispute-actions`

```json
{"challengeId":"EXACT_RETURNED_CHALLENGE_ID","challengeToken":"EXACT_RETURNED_TOKEN","signature":"0xEXACT_SIGNATURE"}
```

HTTP 200 for a write returns `kind: "acknowledgment"`, `operationId`, a `receipt` containing the action, challenge ID, recorded revision and timestamp, and `replay`. A case starts at revision 1. Retry the exact token and signed proof after an interrupted write: it returns the same original acknowledgment without duplicating its event or revealing the current case. To obtain current history, make a separate fresh signed `read` as described below. Neither a challenge nor a successful read is a new complaint.

## 4. Seller responds

Read the case and its current binding with the seller wallet first, then request another challenge on the same operation:

```js
const request = {
  binding: evidence.binding, // Full object returned by the latest signed read.
  "wallet": "0xORIGINAL_PAYMENT_RECIPIENT",
  "action": "respond",
  "expectedRevision": 1,
  "detail": "The original result is available. Here is my delivery explanation or proposed remedy.",
  "evidenceHashes": []
};
```

Sign with the original recipient wallet and submit to `dispute-actions`. The event is appended and revision increases. Seller statements may explain delivery or propose a correction or voluntary refund. The API does not execute that remedy, refund funds, replace immutable result bytes or certify that the seller's assertion is true. Any refund must be separately authorized and verified.

The first version has no push notifications or complaint inbox: sellers poll the known payment operation IDs from their sales or Work Tickets. Reads and responses do not require discovery to remain enabled.

## 5. Buyer closes

After reading the latest revision and current binding with the buyer wallet, request, sign and submit:

```js
const request = {
  binding: evidence.binding, // Full object returned by the latest signed read.
  "wallet": "0xYOUR_BUYER_ADDRESS",
  "action": "close",
  "expectedRevision": 2,
  "outcome": "resolved",
  "detail": "I received the agreed remedy.",
  "evidenceHashes": []
};
```

Use `unresolved` if ending the case without an accepted remedy. Closure records the buyer's statement; it does not prove a refund occurred. Buyer closure fixes the buyer’s outcome; it does not close the evidence record to the seller. The original recipient may append responses after closure, within the 30-day retention and 32-event limit. Those responses preserve `status: "closed"` and the original outcome. Earlier statements remain in history. A stale revision returns HTTP 409; read the latest case and sign again. Before closure, seller responses stop at revision 31 to reserve space for buyer closure. A second buyer closure or a second case is not allowed.

## Read or export evidence

Request a challenge with `{"wallet":"0xPARTICIPANT","action":"read"}`, sign it, and submit it to the same `dispute-actions` endpoint. This returns `kind: "evidence"`, `operationId`, `operationState`, `binding`, `dispute`, `payment`, `delivery`, overdue flags and scope. The case includes exact messages and signatures for independent verification. No case returns `dispute: null`; an authenticated submission for an expired case returns HTTP 410 both before and after cleanup. Exported write-event signatures do not grant access to later case history. An export still contains private statements, so share its contents deliberately. Read challenges are single-use; request a fresh one to read again. Reads never create or close a complaint.

Private statements are encrypted at rest and retained for 30 days after opening, then erased by cleanup. A minimal tombstone containing the operation ID and evidence expiry remains, preventing a second case even when operation retention is longer than 30 days. This does not extend paid-result retention. After result expiry the case can still be read, responded to or closed within its own retention window; `resultAvailable` can be false while the signed history remains available. Export before case expiry if needed. Public catalogs and the Guild Board do not expose complaints.

## Deadlines and state

- Seller response target: 48 hours after the complaint opens.
- Buyer review target: seven days after the first seller response. Additional replies do not reset it.
- Missing those targets sets an overdue flag only. It never closes the case, accepts delivery, determines fault or moves funds.
- These are procedural response targets, not a seller-agreed delivery deadline. Current quotes do not supply a structured delivery deadline; do not infer lateness from a grant or quote authorization expiry.
- A seller may still deliver fresh work through the normal ticket result endpoint. A later delivery does not erase the complaint or rewrite the signed opening snapshot.
- `dispute.status` (`open`, `responded`, `closed`), `operationState`, `payment.state` and delivery availability are separate. `payment.state` is `settled`, `pending`, `failed` or `unconfirmed`; a confirmed payment stays `settled` after `operationState` becomes `expired`. A transaction hash alone does not establish settlement. A resolved complaint does not rewrite an older disputed receipt.
- Seller responses after buyer closure do not create a new buyer-review deadline or reopen the case.

## MCP and SDK

Hosted MCP exposes:

1. `create_delivery_dispute_challenge` with `{operationId, request: {wallet, action: "read"}}`. For a later write, include `binding` from the signed read and the current case revision in the requested statement.
2. Sign the exact returned message locally.
3. `submit_delivery_dispute_action` with `{operationId, challengeId, challengeToken, signature}`.

The server does not sign for either wallet. Initialize the MCP client and use `Accept: application/json, text/event-stream`.

Published merchant SDK 0.7.0 includes `createDeliveryDisputeChallenge` and `submitDeliveryDisputeAction`. Install `402mob-merchant-sdk@0.7.0` or use HTTP/MCP:

```ts
const challenge = await client.createDeliveryDisputeChallenge(operationId, {
  wallet: account.address, action: "read"
});
const signature = await account.signMessage({ message: challenge.message });
const response = await client.submitDeliveryDisputeAction(operationId, {
  challengeId: challenge.challengeId, challengeToken: challenge.challengeToken, signature
});
if (response.kind === "evidence") {
  // Inspect response.dispute and response.payment; export only what you intend to share.
}
```

The SDK checks the exact consent footer, configured service origin, operation, requested statement, binding, role and lifecycle consistency. It rejects contradictory payment/delivery states and changes to immutable payment fields across events. Point the SDK at the service’s canonical origin; an unrelated origin in a returned challenge is rejected before signing. Its response checks do not cryptographically verify every exported EIP-191 signature; use a signature-verification library for independent evidence verification.

## Errors

| Status | Meaning | Next step |
| --- | --- | --- |
| 400 | Body or signature format invalid | Follow the OpenAPI schema; use actual identifiers. |
| 401 | Wrong signer, expired or consumed challenge | Obtain a fresh challenge; preserve an interrupted write's original proof. |
| 403 | Buyer/seller role mismatch | Use the original payer or payment-recipient wallet. |
| 404 | Unknown operation, unrelated wallet or missing case | Check the operation reference and wallet. |
| 409 | Pending payment, existing case, duplicate buyer closure, stale revision/binding or event limit | Recover payment or refresh the case and binding; do not create a second payment. |
| 410 | Opening or evidence retention expired | Use previously exported evidence; expired history cannot be recovered here. |
| 429 | Per-client request rate limit | Wait before retrying. |

This is a bilateral evidence workflow, with no escrow, arbitration, automatic refunds, quality scoring or guaranteed resolution. Current validation uses local HTTP/MCP tests and fixture settlement; no new live-payment dispute run has been performed.

## Separate protected-work experiment

The [protected JSON work API](/protected-work.md) adds a distinct escrow lifecycle with private review, consenting fallback verifiers, replica retention promises and bounded exposure for newly agreed deterministic tasks. It is disabled by default in new installations; a [402Mob-operated pilot](/protected-work-deployment.json) is active with 1 USDC aggregate exposure, five open jobs and two verifiers on the same VPS. It does not provide independent arbitration. [Isolated Base tests](/protected-work-validation.json) passed acceptance, fallback approval and timeout refund using local API/replica services; they do not establish independent-operator or production availability. It cannot refund a direct payment or retroactively protect a dispute described on this page.

## Private transaction evidence

The separate [Transaction Evidence module](/transaction-evidence.md) exports retained participant statements and payment/job observations for local verification. Use `operation` for prepared purchases and delivery complaints, or `protected_json` / `protected_inspection` with a job ID. Wallet proof is required; no result bytes, payment authorization or new settlement action is included. Protected original funding, buyer acceptance, verdict and appeal signatures are not retained and stay missing. Optional chain checks remain separate from offline agreement evidence and work quality. Check `capabilities.transactionEvidence` for deployed support.
