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.
| Status | Terminal | Description |
|---|---|---|
STARTING | No | Just created; platform is preparing the first stage |
ACTIVE | No | Current stage is being processed, including waiting for the deposit |
WAITING | No | Between stages, for example while a refund is prepared |
PAUSED | No | Held by Manteca while in WAITING state |
COMPLETED | Yes | All stages executed successfully |
CANCELLED | Yes | Cancelled; 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
cancellationReasonfield. When a synthetic isCANCELLED, iteratestagesand read theerrorsarray 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
- Webhook:
SYNTHETIC_STATUS_UPDATE - Query:
GET /crypto/v2/synthetics - Query by ID:
GET /crypto/v2/synthetics/{syntheticAnyId}
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 Type | Description |
|---|---|
DEPOSIT | Wait for an inbound crypto or fiat deposit |
ORDER | Execute a buy or sell order on the exchange |
WITHDRAW | Send funds to the destination (fiat bank or crypto address) |
ORDER_REVERSAL | Reverse a failed order to recover funds |
REFUND | Return funds to the originating user |
TRIGGER | Wait for an external trigger signal |
BILL_PAYMENT | Execute a bill payment |
TRANSFER | Move funds between a virtual account and a bank destination |
INTERNAL | A 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
| Status | Terminal | Description |
|---|---|---|
PENDING | No | Created; funds claimed; conversion pending |
COMPLETED | Yes* | Conversion done; resulting amount credited to user balance |
CANCELLED | Yes | Reverted; 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
- Webhook:
ORDER_STATUS_UPDATE - Query:
GET /crypto/v2/orders - Query by ID:
GET /crypto/v2/orders/{orderAnyId}
Withdraw Statuses
The v2 API exposes three statuses for withdrawals in the pretty output:
| Status | Terminal | Description |
|---|---|---|
PENDING | No | Transfer created; funds debited; submitted to the bank |
EXECUTED | No* | Transfer completed successfully |
CANCELLED | Yes | Transfer 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
- Webhook:
WITHDRAW_STATUS_UPDATE - Supplementary webhook:
SYSTEM_NOTICE(recoverable delays and incidents) - Query:
GET /crypto/v2/withdraws - Query by ID:
GET /crypto/v2/withdraws/{withdrawAnyId}
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
- Webhook:
DEPOSIT_DETECTED - Query:
GET /crypto/v2/deposits - Query by ID:
GET /crypto/v2/deposits/{depositAnyId}
Quick Reference Matrix
| Entity | Primary Webhook | Terminal Statuses | Primary Query |
|---|---|---|---|
| Synthetic | SYNTHETIC_STATUS_UPDATE | COMPLETED, CANCELLED | GET /crypto/v2/synthetics |
| Order | ORDER_STATUS_UPDATE | COMPLETED, CANCELLED | GET /crypto/v2/orders |
| Withdraw | WITHDRAW_STATUS_UPDATE | CANCELLED (EXECUTED for crypto) | GET /crypto/v2/withdraws |
| Deposit | DEPOSIT_DETECTED | None | GET /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.
Updated 27 days ago