Operation Lifecycle Statuses

Operation Lifecycle Statuses

Complete status reference for every entity type in ramp operations. Use this page for event-driven processing, polling fallbacks, and reconciliation logic.


Synthetic Statuses

A synthetic is the orchestration entity that chains stages (deposit → order → withdraw) into a single tracked ramp operation.

StatusTerminalDescription
STARTINGNoJust created; platform is preparing the first stage
ACTIVENoCurrent stage is being processed, including waiting for the deposit
WAITINGNoBetween stages, for example while a refund is prepared
PAUSEDNoHeld by Manteca while in WAITING state
COMPLETEDYesAll stages executed successfully
CANCELLEDYesCancelled; reason available in the failing stage's errors array

When a stage within the synthetic encounters an internal failure, the synthetic remains ACTIVE while the platform retries. It only moves to CANCELLED if recovery is not possible. A deposit stage that receives no deposit within 30 minutes moves the synthetic to CANCELLED with no errors.

Where the failure reason lives. A synthetic has no cancellationReason field. When a synthetic is CANCELLED, iterate stages and read the errors array of the stage that failed. See Failures after creation for how to interpret the entries and for the automatic refund behaviour.


Synthetic State Transitions

STARTING
    │
    ▼
ACTIVE ──────────────────────────────────────┐
    │                                        │
    ▼                                        │
WAITING ◄────────────────────────────────────┘
    │         ▲
    │         │  (resume)
    ▼         │
  PAUSED ─────┘
    │
    ▼
COMPLETED   CANCELLED
(terminal)  (terminal)

Any non-terminal status can transition to CANCELLED.

Monitor Synthetics


Synthetic Stage Types

Each synthetic is composed of one or more stages executed in sequence. The current stage drives the synthetic's ACTIVE or WAITING status.

Stage TypeDescription
DEPOSITWait for an inbound crypto or fiat deposit
ORDERExecute a buy or sell order on the exchange
WITHDRAWSend funds to the destination (fiat bank or crypto address)
ORDER_REVERSALReverse a failed order to recover funds
REFUNDReturn funds to the originating user
TRIGGERWait for an external trigger signal
BILL_PAYMENTExecute a bill payment
TRANSFERMove funds between a virtual account and a bank destination
INTERNALA platform-internal step. Returned as { "stageType": "INTERNAL" } with no further detail: safe to skip when walking the stages

The fields on each stage depend on its stageType; see the stages property of GET /crypto/v2/synthetics/{syntheticAnyId} for the per-type shape.

Every stage can also carry an errors array: the failure messages recorded for that stage, in order of appearance. It is absent while the stage is healthy. This is where the reason for a CANCELLED synthetic lives.


Order Statuses

StatusTerminalDescription
PENDINGNoCreated; funds claimed; conversion pending
COMPLETEDYes*Conversion done; resulting amount credited to user balance
CANCELLEDYesReverted; claimed funds refunded to user balance

Order execution is synchronous: a successful POST /crypto/v2/orders returns the order already in COMPLETED. If execution fails, the request returns an error and no order is created.

* The only transition out of COMPLETED is to CANCELLED, when an order is reverted (for example, the automatic refund of a failed ramp operation).

Order State Transitions

PENDING ──────► COMPLETED ──────► CANCELLED
                                  (reversal only,
                                   terminal)

Monitor Orders


Withdraw Statuses

The v2 API exposes three statuses for withdrawals in the pretty output:

StatusTerminalDescription
PENDINGNoTransfer created; funds debited; submitted to the bank
EXECUTEDNo*Transfer completed successfully
CANCELLEDYesTransfer cancelled; funds automatically returned to balance. Check statusMessage for the reason.

* Not terminal for fiat withdrawals: EXECUTED moves to CANCELLED if the receiving bank returns the transfer.

Intermediate processing steps (reviews, retries) are handled by the platform and are reported as PENDING.

Withdraw State Transitions

PENDING
    │
    ├──────────────────────────► EXECUTED
    │                               │
    │                               │ returned by the receiving bank
    │                               │ (fiat only)
    │                               ▼
    └──────────────────────────► CANCELLED
                                 (terminal)

When a withdraw reaches CANCELLED, check the statusMessage field for post-execution error codes. See Ramps Error Handling: Post-Execution Errors.

Funds are automatically returned to the user's balance on CANCELLED.

A fiat withdrawal can reach CANCELLED after EXECUTED. If the receiving bank returns the whole transfer, the withdrawal moves to CANCELLED and the amount goes back to the user's balance. If it returns only part of it, the withdrawal stays in EXECUTED, filledAmount drops by the returned amount, and that amount goes back to the user's balance; no WITHDRAW_STATUS_UPDATE is sent for a partial return.

Monitor Withdraws


Deposits

Deposits do not have a status machine in the v2 API. The primary signal is the DEPOSIT_DETECTED webhook. It is sent once per deposit, crypto or fiat, when the deposit is already assigned to the user and credited to their balance. Its payload carries no status.

Monitor Deposits


Quick Reference Matrix

EntityPrimary WebhookTerminal StatusesPrimary Query
SyntheticSYNTHETIC_STATUS_UPDATECOMPLETED, CANCELLEDGET /crypto/v2/synthetics
OrderORDER_STATUS_UPDATECOMPLETED, CANCELLEDGET /crypto/v2/orders
WithdrawWITHDRAW_STATUS_UPDATECANCELLED (EXECUTED for crypto)GET /crypto/v2/withdraws
DepositDEPOSIT_DETECTEDNoneGET /crypto/v2/deposits

Integration Recommendations

Webhook-first, query-fallback. Process the webhook immediately, then re-fetch the entity by ID to confirm state. Persist the latest status snapshot. Discard stale transitions using timestamp or version checks.

Treat terminal statuses as idempotent close points. Once an entity reaches a terminal status, no further transitions will occur. Close your internal record and stop polling.

Use SYSTEM_NOTICE for operational visibility. This webhook signals recoverable delays and retries before a final status is emitted. It is not a success or failure signal: treat it as informational.



Did this page help you?