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

Field	Type	Required	Notes
`operation_id`	string (UUID)	conditional	The server-issued ID returned by `/v1/payment` or `/v1/payout`.
`merchant_operation_id`	string	conditional	The opaque idempotency key supplied to `/v1/payment` or `/v1/payout`; useful if the create response was lost.

Send exactly one of these fields. Supplying both or neither returns 400. Both forms return the operation and its receipt information. If receipts are unavailable, the response still includes the operation with receipt_evidence_status: "unavailable". An operation_id lookup can instead return 503 if a download link cannot be generated; a merchant_operation_id lookup returns the operation with unavailable receipts.

Example

curl -X POST https://api.alva.co.nl/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. If the reason is unknown, the API returns potential_fake. The receipts array lists the completed transfers:

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

An operation paid in several transfers has several items. amount is a decimal string, not an integer in minor units. receipt_url is null when the contribution has no downloadable file. Items are ordered by completed_at, then id.

For files stored by InOut, the download link depends on the lookup identifier:

An operation_id lookup returns a signed link valid for 15 minutes. Fetch a fresh operation state if it expires.
A merchant_operation_id lookup returns a link on the API host under /v1/receipts/file. Download it from your server with the same shop's X-API-Key; opening it directly in a browser without the header returns 401.

Provider-hosted HTTPS links are returned directly; their expiry is controlled by the provider. Send your API key only to the InOut API host, never to a provider or storage host. Do not expose the API key to the payer's browser.

receipts is empty until the operation is completed, even if individual transfers have already completed.

receipt_evidence_status explains whether the array is authoritative:

not_ready — no transfer breakdown is available yet; the array is empty;
partial — the breakdown includes an aggregate amount without individual transfer evidence. Such an item has receipt_url: null; retrying does not guarantee that a file will appear;
complete — the breakdown is supported by transfer evidence and its amounts have been verified. Some transfers may still have no downloadable file;
unavailable — the breakdown or download links could not be prepared. The operation state is available, but the array is empty. Retry later.

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 — a stored receipt link could not be generated for the operation_id lookup; retry with backoff.

Receipt-provider outages and receipt evidence that no longer matches the operation never hide the operation state. Both lookup forms return 200 with receipt_evidence_status: "unavailable" and an empty receipts array.