Disputes and appeals (Appeals)

Disputed situations can arise in P2P acquiring: for example, a client claims the transfer was made, but the P2P trader reports that nothing arrived on their card.

To resolve such conflicts, Syncra V2 provides the Appeal Service: the merchant opens an appeal on a deal, attaches evidence files, and communicates with the platform arbitrator in the dispute chat.

All endpoints in this section run under the merchant's HMAC pair; appeal creation and the chat are also available from the cabinet (a cabinet-JWT session, the same contract — the initiator is resolved from authentication).

Dispute resolution workflow

1. Initiating a dispute. The merchant creates an appeal, stating the reason and attaching evidence files (UUIDs of pre-uploaded files).
2. Arbitration. Syncra arbitrators verify the authenticity of the evidence, cross-check the transfer time and payment details, and issue a decision.

Appeal statuses

The canonical lifecycle is domain.AppealStatus (5 values). The full table with the V1 mapping is in the Status mapping reference.

Crediting an overdue payment on resolution (Settle-as-Received)

A typical dispute case: the client transferred less than declared (partial) or transferred late — the deal managed to expire into EXPIRED while received_amount > 0. The money is at the trader's, the deal is dead. Resurrect mode is forbidden: EXPIRED is terminal and never changes. Instead, the operator closes the dispute by creating a settlement — a new deal that credits the amount actually received:

POST /api/v1/p2p/appeals/{appeal_id}/settlement

This is a cabinet operator action (the arbitration panel). The body: received_amount_override (optional, for a manual amount correction — then reason is required), reason, idempotency_key (UUID). The full semantics are described in PayIn → Late payment settlement.

Properties of resolving via a settlement:

• the appeal resolves as SATISFIED, and resolution_note carries a reference to the settlement deal (parent_deal_id → the expired original, origin_appeal_id → the appeal);
• one appeal → at most one settlement (a UNIQUE constraint at the database level): a repeated call returns the already-created record (replay), not an error;
• the settlement walks the full standard path (escrow → verify → complete); the rate is a new one, taken at the resolve moment;
• the settlement emits the regular deal.created … deal.completed webhooks (V1 and V2); the original stays EXPIRED forever with its own received_amount.

Refusals: the parent is not EXPIRED or the appeal is already closed → 409; received_amount = 0 without an override → 400; an override without reason → 400.

Creating an appeal

POST /api/v1/p2p/merchant/appeals

Request parameters (JSON Body)

Request example

{
  "deal_id": "7ac148fe-19a3-45bb-b992-019fac55b721",
  "reason": "The client transferred 2,500.00 RUB, but the payment was not credited within 30 minutes",
  "file_ids": ["f3a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c"]
}

Response example (200 OK)

{
  "appeal": {
    "appeal_id": "a82d77a0-0d3a-4422-b91c-7cb052a21def",
    "deal_id": "7ac148fe-19a3-45bb-b992-019fac55b721",
    "status": "OPEN",
    "reason": "The client transferred 2,500.00 RUB, but the payment was not credited within 30 minutes",
    "resolution_note": "",
    "created_at": "2026-07-12T17:25:00Z",
    "resolved_at": "",
    "updated_at": "2026-07-12T17:25:00Z"
  }
}

Creation errors (live staging responses)

400 INVALID_ARGUMENT — reason shorter than 10 characters:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "{\"code\":3,\"message\":\"reason is required (at least 10 characters)\",\"details\":[]}",
  "instance": "/api/v1/p2p-engine"
}

400 FAILED_PRECONDITION — the deal already has an active appeal (no duplicate threads: a repeat is forbidden while the appeal is OPEN, IN_PROGRESS, or REOPENED; the terminal SATISFIED/REJECTED do not block a new one):

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "{\"code\":9,\"message\":\"deal 359fb026-6dd7-4f7a-bfa7-aa54a5afb6cb already has an active appeal (aa1fac74-33b3-41ce-ae47-445bc3dcd37d, status OPEN) — continue the existing thread\",\"details\":[]}",
  "instance": "/api/v1/p2p-engine"
}

404 NOT_FOUND — a nonexistent deal_id (deal not found); 403 PERMISSION_DENIED — another merchant's deal (cannot access another merchant's resources).

Retrieving appeal information

GET /api/v1/p2p/merchant/appeals/{appeal_id}

Response example (200 OK, live staging response)

{
  "appeal": {
    "appeal_id": "aa1fac74-33b3-41ce-ae47-445bc3dcd37d",
    "deal_id": "359fb026-6dd7-4f7a-bfa7-aa54a5afb6cb",
    "status": "OPEN",
    "reason": "E2E merchant appeals full-cycle test: payer claims transfer completed but escrow never confirmed",
    "resolution_note": "",
    "created_at": "2026-08-23T19:04:44Z",
    "resolved_at": "",
    "updated_at": "2026-08-23T19:04:44Z"
  }
}

Another merchant's appeal → 403, a nonexistent one → 404 (appeal not found).

Appeal listing

GET /api/v1/p2p/merchant/appeals

Query parameters

Response example (200 OK)

{
  "data": [
    {
      "appeal_id": "aa1fac74-33b3-41ce-ae47-445bc3dcd37d",
      "deal_id": "359fb026-6dd7-4f7a-bfa7-aa54a5afb6cb",
      "status": "OPEN",
      "reason": "E2E merchant appeals full-cycle test: payer claims transfer completed but escrow never confirmed",
      "resolution_note": "",
      "created_at": "2026-08-23T19:04:44Z",
      "resolved_at": "",
      "updated_at": "2026-08-23T19:04:44Z"
    }
  ],
  "next_page_token": ""
}

Appeal chat

Within an appeal, the merchant can exchange text messages with the platform arbitrator. Also available from the cabinet (JWT).

Sending a chat message

POST /api/v1/p2p/merchant/appeals/{appeal_id}/messages

Request parameters

Request example

{
  "body": "Here is the bank statement confirming the debit.",
  "file_ids": []
}

Response example (200 OK, live staging response)

{
  "message": {
    "message_id": "a7b598e0-2074-4873-91ee-954ec588bcfc",
    "appeal_id": "aa1fac74-33b3-41ce-ae47-445bc3dcd37d",
    "sender_role": "MERCHANT",
    "body": "Here is the bank statement confirming the debit.",
    "file_ids": [],
    "created_at": "2026-08-23T21:48:24Z"
  }
}

sender_role is resolved from authentication (MERCHANT for the API/cabinet, ADMIN — arbitrator messages, TRADER — the trader's).

Retrieving message history

GET /api/v1/p2p/merchant/appeals/{appeal_id}/messages

Response example (200 OK)

{
  "data": [
    {
      "message_id": "b33d77a0-0d3a-4422-b91c-7cb052a21aaa",
      "appeal_id": "a82d77a0-0d3a-4422-b91c-7cb052a21def",
      "sender_role": "MERCHANT",
      "body": "Here is the bank statement.",
      "file_ids": [],
      "created_at": "2026-07-12T17:27:00Z"
    },
    {
      "message_id": "b33d77a0-0d3a-4422-b91c-7cb052a21bbb",
      "appeal_id": "a82d77a0-0d3a-4422-b91c-7cb052a21def",
      "sender_role": "ADMIN",
      "body": "Evidence received. Starting the review.",
      "file_ids": [],
      "created_at": "2026-07-12T17:27:05Z"
    }
  ],
  "next_page_token": ""
}

Decommissioned RDR flow (deprecated 2026-09-28)

Until 2026-09-28 the platform contained a separate card-dispute flow (Visa VROL / Ethoca): an ingested dispute was matched against an RDR rule, moved the deal to REFUND_PENDING, and launched a refund saga. The flow existed outside the P2P money model (saga money never moved within orders) and was decommissioned by the owner's decision. What changed:

The HTTP code 400 is the grpc-gateway equivalent of gRPC FailedPrecondition: the request is valid and understood, but the addressed subsystem has been dismantled.

If an external dispute webhook still arrives (the provider retries delivery), the platform does not stay silent: the reject is accompanied by an ERROR log and an operator alert p2p.dispute.rejected_decommissioned (Telegram ERROR channel; a 30-minute dedup by tenant + external_ref — repeated sender retries within the window do not create an alert storm) so that the operators ask the provider to stop sending.

Integrator migration: remove the dispute-API calls — disputes are not supported by the platform. Disputed deals go through the appeal flow (this page). The deal webhook flow is unchanged: the deal.refund_pending → deal.cancelled pair and V1 16 → 12 work as documented (the transit semantics of REFUND_PENDING); a rejected appeal, a third-party flag, or a reconciliation (recon) rule moves a deal into the transit — RDR rules no longer exist as a trigger source.