> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rampnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Status

> Every order and payment status, how an order moves between them, and what to do in each

<Note>
  This page is the single reference for order statuses. Webhooks carry the status in `payload.orderStatus`. [Get Order](/api-reference/onramp-&-offramp-intent/get-an-order-by-external-id) returns it in `status`. The values are the same.
</Note>

## Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> unknown: POST /ext/ramp_order/checkout
    unknown --> created: customer confirms on hosted page
    created --> payment_processing: payment started
    created --> processing: payment accepted
    payment_processing --> processing: payment accepted
    created --> payment_failed: payment declined
    payment_processing --> payment_failed: payment declined
    created --> expired: not paid in time
    payment_processing --> expired: payment expired
    processing --> completed: delivered / paid out
    processing --> failed: delivery / payout failed
    failed --> processing: retried by Rampnow operations
    failed --> blocked: compliance block
    payment_failed --> processing: late payment accepted
    expired --> processing: late payment accepted
    completed --> [*]
    blocked --> [*]
```

## Order statuses

| Status | Meaning | Webhook | Final | What you should do |
| - | - | - | - | - |
| `unknown` | Order created with `/checkout`, but the customer hasn't confirmed it on the hosted page yet. It has no time limit in this state. | No | No | Nothing. The order is visible only by polling. Wait for `created`. |
| `created` | The customer confirmed the order. Rampnow is waiting for the fiat payment (buy) or the crypto deposit (sell). Unpaid orders expire after 15 minutes. | Yes | No | Show "waiting for payment". |
| `payment_processing` | The payment is clearing (buy), or the deposit address is issued and the deposit is being detected and confirmed (sell). | No | No | Nothing. Only visible by polling. |
| `processing` | Payment accepted. Buy: crypto is being sent to the destination wallet. Sell: the deposit is converted and the fiat payout is in progress. | Yes | No | Show "in progress". |
| `completed` | Crypto delivered (buy) or fiat paid out (sell). | Yes | Yes | Mark the order successful. Reconcile on `dstFillAmount`, not `dstAmount`. |
| `failed` | Delivery (buy) or payout (sell) failed. The Rampnow operations team investigates and either retries the order, which moves it back to `processing`, or blocks and refunds it. | Yes | No | Don't close or refund on your side. Show "delayed" and keep listening. |
| `payment_failed` | The card or bank payment was declined, failed or canceled (buy), or the deposit didn't match the order (sell). | Yes | Yes\* | Tell the user the payment failed. A retry needs a new order. |
| `expired` | The order wasn't paid within its window. | Yes | Yes\* | Tell the user the order expired. A retry needs a new order. |
| `blocked` | Stopped by compliance screening. Funds are refunded where applicable, and `paymentStatus` becomes `refunded`. | Yes | Yes | Mark the order failed. Don't retry the same order. |
| `canceled` | Reserved. Not currently emitted for ramp orders. | — | Yes | Handle as final if you receive it. |
| `partially_failed` | Reserved. Not currently emitted for ramp orders. | — | Yes | Handle as final if you receive it. |

\* `payment_failed` and `expired` are final for your user experience, but a payment that is accepted late (for example a bank transfer that arrives after the window) moves the order to `processing`. Keep handling webhooks for these orders.

<Warning>
  New statuses may be added. Treat any value you don't recognise as "in progress" and log it, rather than failing.
</Warning>

## Payment statuses

`paymentStatus` tracks the payment leg: the fiat payment for a buy, the crypto deposit for a sell. It drives the order status as shown below. A webhook is only sent when the **order** status changes, so payment-only changes don't produce a webhook.

| Payment status | Meaning | Order status |
| - | - | - |
| `unknown` | No payment yet | unchanged |
| `created` | Payment created with the payment provider | `payment_processing` |
| `pending` | Waiting for the customer to pay. On a sell, the deposit address is issued | `payment_processing` |
| `authorized` | Payment authorised. On a sell, the deposit is seen on-chain but not yet confirmed | `payment_processing` |
| `received` | Funds received. On a sell, the deposit is confirmed and being converted | `payment_processing` |
| `review` | Payment held for manual review (for example a payer name mismatch) | `payment_processing` |
| `processing_failed` | Conversion of the received funds failed and is being retried | `payment_processing` |
| `accepted` | Payment final and accepted | `processing` |
| `rejected` | Payment rejected. On a sell, the deposit amount didn't match | `payment_failed` |
| `failed` | Payment failed | `payment_failed` |
| `canceled` | Payment canceled | `payment_failed` |
| `expired` | Payment not completed in time | `expired` |
| `refunded` | Payment refunded to the customer | unchanged |
| `chargebacked` | Card payment charged back | unchanged |

## Buy vs sell

| | Buy (onramp) | Sell (offramp) |
| - | - | - |
| Payment leg | Fiat payment by card or bank | Crypto deposit to the address shown on the hosted page |
| Payment window | 15 minutes after the customer confirms, unless a payment has started. Pending bank transfers can stay open up to 7 days | The deposit address is valid for 25 minutes after it is issued |
| `processing` means | Payment accepted, crypto being delivered | Deposit converted, fiat payout in progress |
| `completed` means | Crypto delivered to the destination wallet | Fiat paid out to the bank account |
| `dstFillAmount` | Crypto amount delivered on-chain | Fiat amount paid out |
| `transactionHash` | On-chain transaction hash(es) of the delivery | Payout provider's reference (for example a bank trace number), not the deposit hash |
| `walletAddress` | Destination crypto address | Destination IBAN, or the account number when there is no IBAN |

## Handling rules

* **Status is the current state, not a transition.** Each webhook carries the order's status at the time it was sent. Two quick changes can produce two events with the same status. Store the latest status per order and ignore events whose `payload.updateTime` is older than the one you have.
* **De-duplicate webhooks on `eventUid`.** Retries of the same event reuse it. See [Webhooks](/api-reference/webhook).
* **Don't treat the `returnUrl` redirect as proof of success.** Confirm the status from a webhook or by [polling the order](/api-reference/onramp-&-offramp-intent/get-an-order-by-external-id).
* **Field names differ by source.** Webhooks use `orderStatus`. Get Order uses `status`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.