Get operation state

Read the latest state of an operation by either its server-issued operation_id or the merchant_operation_id used when it was created. Useful when you missed a webhook or the create response and want to reconcile the operation, or to poll while building an integration. The lookup is always scoped to the shop identified by X-API-Key.

Endpoint

POST /v1/get_operation_state
Content-Type: application/json
X-API-Key: 01234567-89ab-4cde-8f01-23456789abcd

Request

Send exactly one of these fields. Supplying both or neither returns 400. Both forms return the same successful operation and receipt-evidence shape. For backward compatibility, the original operation_id lookup keeps returning 503 when receipt evidence cannot be materialized. The additive merchant_operation_id recovery lookup can still return the authoritative operation with receipt_evidence_status: "unavailable".

Example

curl -X POST https://api.casheradminmatch.com/v1/get_operation_state \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 01234567-89ab-4cde-8f01-23456789abcd" \
  -d '{"operation_id": "f6c2e7d4-3e5b-4f1f-8a02-9d6c7e8a1b22"}'

Response

200 OK with the operation object. When status is manual_check, the object contains manual_check_reason: potential_fake or not_terminal. It is omitted for every other status. The upstream reason is optional internally for rolling compatibility; if it is missing, the API conservatively returns potential_fake. The response also contains an additive receipts array:

{
  "operation_id": "f6c2e7d4-3e5b-4f1f-8a02-9d6c7e8a1b22",
  "status": "completed",
  "receipt_evidence_status": "complete",
  "receipts": [
    {
      "id": "b07f94d8-e13e-5fbb-9695-87088c0ddbce",
      "amount": 5000,
      "completed_at": "2026-07-16T12:34:56Z",
      "receipt_url": "https://storage.example/..."
    },
    {
      "id": "20ebd58a-fdf7-5002-b41b-a3d21464086c",
      "amount": 5000,
      "completed_at": "2026-07-16T12:35:10Z",
      "receipt_url": null
    }
  ]
}

Each item is one completed physical contribution to the operation. A payout assembled from multiple provider legs or matching payments therefore returns multiple items. receipt_url is a short-lived HTTPS download link when the provider has a file; it is null when the contribution has no downloadable receipt. Items are ordered by completed_at, then id.

receipts is empty until the parent operation is completed, including when some provider legs have already completed. This keeps the decomposition stable and prevents integrations from treating an in-progress partial result as final. The field is additive and existing response fields are unchanged.

receipt_evidence_status explains whether the array is authoritative:

• not_ready — the parent operation is still mutable, so no decomposition is returned;
• partial — every positive route leg is represented, but one or more items is a synthetic legacy contribution. Such an item has the route leg's authoritative amount and receipt_url: null; retrying will not necessarily turn it into provider file evidence;
• complete — every positive route leg is decomposed by real provider evidence and each provider's items add up exactly to that leg's physical fact;
• unavailable — operation state is authoritative, but provider receipt evidence or URL signing is temporarily unavailable. Retry later; no partial list is returned.

Polling guidance

Webhooks are the canonical signal for terminal status. Poll only as a fallback — for example, when building integration tooling or recovering from a missed delivery. There is no ETag or version field; each call returns the current state at read time.

Errors

• 400 — no identifier supplied (or both), or operation_id is not a UUID.
• 401 — X-API-Key missing or invalid.
• 404 — no operation with that identifier in this shop's scope.
• 503 — receipt evidence could not be materialized for the original operation_id lookup; retry with backoff.

For the additive merchant_operation_id recovery lookup, receipt-provider outages do not hide the operation state. They return 200 with receipt_evidence_status: "unavailable" and an empty receipts array.