Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Cancel a pending wire transfer
Withdraws a payment declaration the TENANT itself opened and no longer wants reconciled — in
the UI this is the "Cancel transfer" action shown only while a wire transfer sits in
pending-manual-approval. The ledger entry moves to the terminal failed state with
failureReason cancelled. It settles nothing and reverses nothing: a pending declaration was
already granting no wallet credit and paying no invoice, so the terminal flip is the whole
effect. It is the tenant-side twin of the operator's reject action, and deliberately uses a
different failureReason so a withdrawal stays distinguishable from a
money-never-arrived ruling.
Validation: transaction must exist in the scope (else NOT_FOUND); the entry must be one the
tenant declared — payment or wire-transfer-pending; a charge is a DEBT the platform is
owed rather than the tenant's declaration and is refused with CONFLICT (flipping it failed
would assert the charge never happened while the customer still owes it, and cancelling a
commitment upfront would strand the commitment), as are the settling credit-applied and
refund movements; current status must permit cancel — only pending-manual-approval (and
pending) entries are cancellable, and cancelling a completed or failed entry maps to
CONFLICT (re-cancelling an operator-rejected entry would overwrite its reason and launder the
ruling); caller must hold contributor/admin/owner or billing role, otherwise FORBIDDEN. Guards
are evaluated before any mutation, so a refusal leaves the entry and its invoice unchanged.
Async & state: returns 202 with a SUCCEEDED Operation; the withdrawal is applied inline in
one commit. State machine: pending-manual-approval (or pending) → terminal failed with
failureReason cancelled. The change is emitted as a resource.updated SSE frame with kind
billing.transaction patching status/failureReason.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scope/transaction;
409 CONFLICT when the entry type is not a tenant declaration or the current status does not
permit cancel; 429 repeated cancel attempts rate-limited; 500 internal.
Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted
and a sent one is ignored. Each successful call returns a new already-SUCCEEDED Operation;
repeating the cancel after it succeeded answers 409 CONFLICT because the entry is already
failed (no longer awaiting resolution), so the withdrawal is never applied twice. This
operation does not check If-Match; a sent one is ignored.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
transactionId*stringTransaction ledger entry identifier.
Cancellation accepted; track via the returned operation.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"resourceKind?|Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.
resourceId?|Identifier of the target resource; null until the resource is allocated.
resourceName?|Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).
principalId?|Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.
sourceIp?|Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).
progressPercent?|Best-effort progress; null when the action does not report progress.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.
startedAt?|When the worker began executing; null while PENDING.
finishedAt?|When a terminal state was reached; null while transitional.
createdAt*stringupdatedAt*stringcurl -X POST "https://example.com/scopes/string/billing/transactions/string/actions/cancel"{ "id": "string", "action": "string", "state": "PENDING", "resourceKind": "string", "resourceId": "string", "resourceName": "string", "principalId": "string", "sourceIp": "string", "progressPercent": 0, "error": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "warning": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "startedAt": "string", "finishedAt": "string", "createdAt": "string", "updatedAt": "string"}