Disputes

Either side of a trade can open a dispute when the trade is stuck. A common case is a buyer who says they paid while the seller says nothing arrived. This page covers when a customer can open a dispute, what the trade shows afterwards, and how the dispute ends.

When a customer can open a dispute

A dispute can be opened only while the trade is CREATED or PAID. Whether it can be opened right away depends on the customer’s side of the trade.

The length of the dispute window is fixed for each trade when it is created. When the customer opens a dispute, their open trade on that side is released. A dispute opened by the merchant does not release it.

1. Prepare the dispute

Customer disputes use the openDispute action. Like every trade action, you prepare it, the customer’s wallet signs it and you submit it. See Trade actions and Sign and track transactions.

Call POST /v1/trades/{tradeId}/actions/{action}/execution with the openDispute action. The body is optional. If you send one, it can carry a reason:

Any other value is rejected with 400 VALIDATION_ERROR.

The reason is not written on chain. Sinbad stores it with the prepared transaction and shows it on the trade after you report the matching signed transaction and Sinbad verifies it. If you never report the transaction, dispute.reason can stay null, so report every signed transaction.

2. Handle TOO_EARLY and INVALID_STATE

If you prepare openDispute before the dispute window has passed, the call fails with 409 CONFLICT and details.reason: "TOO_EARLY". details.availableAt holds the time, in ISO 8601 format, when the action becomes available. Wait until then and prepare again.

In any other state that does not allow the action, the call fails with 409 CONFLICT and details.reason: "INVALID_STATE", plus details.action and details.chainStatus. Do not retry an INVALID_STATE response unchanged.

availableActions on the trade is only a hint. The real check happens when you prepare the action. See Errors and recovery.

3. Read the dispute on the trade

Once the dispute transaction is confirmed, the trade moves to DISPUTED and carries a dispute object:

Before any dispute, dispute is null. After a dispute ends, the object stays on the trade with resolution filled in.

The trade can show DISPUTED later than the transaction receipt confirms. Do not submit the action again because the status has not changed yet. Chat and payment proof stay available while the trade is DISPUTED. See Trade lifecycle, Chat and images and Payment proof. You can also follow the dispute with Webhooks.

4. Resolve by mutual resolution

While the trade is DISPUTED, the customer can close it with the mutualResolveDispute action. It is one transaction, signed by the customer only. The other side does not sign. Prepare, sign and submit it like any other trade action.

Who receives the funds depends on the customer’s side:

5. If the two sides do not agree

If neither side resolves the dispute, contact Sinbad support with the trade ID and the request ID. Sinbad support can release the funds to the buyer (BUYER_RELEASE, trade RELEASED) or refund the seller who locked them (FULL_REFUND, trade CANCELED). Follow the trade and the signed trade.updated events for the confirmed outcome.

Agree the escalation contact and the response expectations with Sinbad during onboarding. Sinbad does not promise a fixed resolution time.