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

# Orders API introduction

> Create and follow on-ramp and off-ramp orders on the Uphold platform. Orders are defined by their origin, destination and denomination, with quotes, requirements and statuses.

The orders group of endpoints allows you to quote, create and retrieve on-ramp and off-ramp orders from the platform. Each order moves value between fiat and crypto in a single operation.

## Order types

| Type | Direction | Origin | Destination |
| - | - | - | - |
| `on-ramp` | Fiat to crypto | An external account or an alternative payment method (APM). | A crypto address or a crypto external account. |
| `off-ramp` | Crypto to fiat | A crypto address, identified by its asset and network. | An external account, such as a debit card. |

## Order nodes

Every order is defined by three fundamental properties:

* `origin`: Defines the origin node of the order, where the funds come from.
* `destination`: Defines the destination node of the order, where the funds go to.
* `denomination`: Defines what and how much is being moved. See [Denomination](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md#denomination).

The `origin` and `destination` are each represented by a node. The following node types are supported:

> [accordion] External account
>
> External accounts refer to the user's [external accounts](https://developer.uphold.com/rest-apis/core-api/external-accounts/introduction.md), referenced by their `id`. The `via` property of the node says the rail it is used through:
>
> * `card`: A card, with the `network` of the card. When creating an order, its `confirmationUrl` is the URL to send the user to for confirming the authorization, such as a 3DS challenge.
> * `apm`: A saved APM account, which also carries a `confirmationUrl` when the user must confirm the payment.
> * `crypto`: A saved crypto address of the user, as the destination of an on-ramp order. Its `network` and `execution` are those of a crypto address node.

> [accordion] APM
>
> Alternative Payment Method (APM) nodes represent payment methods such as Apple Pay, Google Pay and PayPal, identified by their `method`. They can be used as the origin of an on-ramp order, and need the matching `authorize:*` [requirement](#requirements) when creating the order.

> [accordion] Crypto address
>
> Crypto addresses enable the use of crypto wallet addresses as order nodes. A quote request defines it with the `asset` and `network` and, as the destination of an on-ramp order, the `address` and the `reference`: the additional identifier (such as a memo or destination tag) that some networks require.
>
> Once the funds are moved, the `execution.mode` of the node says how:
>
> * `onchain`: Processed directly on the blockchain network, with the `transactionHash`.
> * `offchain`: Processed within Uphold, with the `accountId` and `accountOwnerId` it was made to.
> * `simulated`: Simulated without affecting the blockchain, with a simulated `transactionHash`.

## Creating a quote-based order

An order is always created from a quote, in two steps:

1. [Create a quote](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) with the `type`, `origin`, `destination` and `denomination` of the order. The quote returns the rates, the `fees` and the `requirements` that must be met to create the order.
2. [Create the order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md) with the `quoteId`, before the quote `expiresAt`. Provide the data for each `authorize:*` requirement of the quote in `params.requirements`, such as `authorize:3ds` with a `returnUrl`, and resolve the `travel-rule` requirement before creating the order. Optionally, attach your own [`metadata`](#metadata) to the order. If the metadata cannot be saved, the order is still created, and the response describes the issue in `errors.metadata`.

A quote has a `refreshAt` time and an `expiresAt` time, after which it can no longer be used to create an order. There is no endpoint to refresh a quote: to refresh it, create a new one. Use `refreshAt` to decide when to do so in your UI, while the user hasn't confirmed the quote.

If the rate moves too far from the rate of the quote before you create the order, the order fails with the `operation_not_allowed` error and the `quote-rate-variance-not-allowed` reason. Create a new quote.

A quote can only be used once. Creating an order from an expired or already used quote fails with a `404` `entity_not_found` error.

### Anatomy of a quote request

The supported [node types](#order-nodes) differ between `origin` and `destination`, and between order types:

* **On-ramp origin**: external-account apm
* **On-ramp destination**: crypto-address external-account
* **Off-ramp origin**: crypto-address
* **Off-ramp destination**: external-account

**Crypto external accounts (on-ramp destination only):** A `crypto` external account can only be the destination of an on-ramp order, and must support `withdraw` on the requested network. Otherwise, the quote is rejected with a `409` `transaction_node_invalid` error. If you omit `network`, the network of the account is used. Reference it by `id` to have it returned as an external account: a raw `crypto-address` destination is always returned as a `crypto-address` node.

This model allows you to create orders between different types of nodes in a unified manner, such as from a card to a crypto address, or from a crypto address to a card.

Like Core transactions, an order handles different classes of assets in the origin and destination: you can pay in USD with a card and receive BTC at a crypto address, or send ETH from an external wallet and be paid out in USD to a card.

### Fees

The `fees` of a quote and of its order list each fee charged on the order's transactions, with its `type` (`deposit`, `exchange`, `network` or `withdrawal`), its `code`, the `asset` and `amount` it is charged in, the `percentage` it was calculated from, if any, and the `beneficiary` that receives it (`uphold` or `partner`). See [How target affects fee handling](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md#example-how-target-affects-fee-handling) for how the `target` of the `denomination` decides whether fees are added to the amount paid by the origin or deducted from the amount received by the destination.

### Requirements

A quote lists the `requirements` that must be met to create the order. If the array is empty, you can create the order directly. Otherwise, resolve each requirement.

Every item has a `name` and a `quoteId`. The `quoteId` is the id of the quote of the leg the requirement belongs to, such as the deposit quote to authorize. Use it to resolve the requirement:

```json theme={null}
{ "name": "authorize:3ds", "quoteId": "<deposit-quote-id>" }
```

Then provide the data for each `authorize:*` requirement in `params.requirements` when creating the order. The `travel-rule` requirement is met by resolving its request for information before creating the order.

| Requirement | How to resolve |
| - | - |
| `travel-rule` | Resolve the request for information (RFI) with the `quoteId` of the requirement. See [Requests for information](#requests-for-information-rfis). |
| `authorize:apple-pay`, `authorize:google-pay`, `authorize:paypal` | Authorize the payment with the [Payment Widget's](https://developer.uphold.com/widgets/payment/introduction.md) `order:authorize-deposit` flow, which also creates the order. |
| `authorize:3ds` | Pass a `returnUrl` as the requirement when creating the order, along with the [user context](https://developer.uphold.com/rest-apis/headers.md#user-context) headers. |

## Order legs

An order is a single operation, but it runs as up to three legs: a [deposit](#deposit), which collects the funds from the `origin`, a [withdrawal](#withdrawal), which sends them to the `destination`, and, if the order cannot be completed, a [refund](#refunds), which returns the deposited funds.

### Deposit

The deposit collects the funds from the `origin` into an internal on-ramp or off-ramp account of the user. How it's made decides how firm the price is, which requirements the quote has, and how the order starts:

| | Pull deposit | Push deposit |
| - | - | - |
| How it's made | Uphold collects the funds from the origin itself, such as by charging a card or through an APM. | The user sends the funds from outside Uphold, such as crypto from an external wallet. |
| Pricing | `locked` | `estimated` |
| Requirements | `authorize:3ds` for a card, or the `authorize:*` requirement of the APM. | None for the deposit. |
| First status | `processing`, since the deposit is collected when the order is created. | `pending`, until the funds arrive. |
| Expiry | None. | The order is `expired` if the funds don't arrive within 24 hours. |

#### Pricing

The `pricing` of a quote and of its order tells you how firm the rate is:

* `locked`: The rate is held for the order.
* `estimated`: The rate is an estimate, and the final amounts are set once the deposit arrives, because a push deposit can take a while to arrive.

### Withdrawal

The withdrawal sends the funds from the internal account to the `destination`: a crypto withdrawal for an on-ramp order, or a payout to a payment method of the user, such as a debit card, for an off-ramp order. A crypto withdrawal may need Travel Rule information, in which case the quote lists the `travel-rule` requirement.

#### Requests for information (RFIs)

When the quote lists the `travel-rule` requirement, the order cannot be created until the related request for information (RFI) is resolved. Use the `quoteId` of the requirement to resolve it, either:

* **Through the widget:** call [Create session](https://developer.uphold.com/rest-apis/widgets-api/travel-rule/create-session.md) of the Travel Rule Widget with the `withdrawal-form` flow and `data.quoteId` set to the `quoteId` of the requirement. The widget collects the data from the user and resolves the RFI.
* **Through the API:** call [List requests for information](https://developer.uphold.com/rest-apis/core-api/requests-for-information/list-requests-for-information.md) with the `quoteId` as `reference` to find the RFI, and resolve it with [Update request for information](https://developer.uphold.com/rest-apis/core-api/requests-for-information/update-request-for-information.md).

Create the order once the RFI has the status `ok`. Creating it before then fails with a `409` `operation_not_allowed` error, with the reason `pending-requests-for-information`.

Check out the travel rule withdrawal guides [via widget](https://developer.uphold.com/developer-guides/travel-rule/withdrawal/via-widget.md) and [via API](https://developer.uphold.com/developer-guides/travel-rule/withdrawal/via-api.md) for a detailed walkthrough.

See [Proof types](https://developer.uphold.com/developer-guides/travel-rule/overview.md#proof-types) for the proofs a user may need to provide.

### Refunds

If the withdrawal is rejected or fails, Uphold usually refunds the deposit by reverting it, so the user does not lose the funds. Depending on why the withdrawal failed, such as the outcome of a compliance review, the deposit may not be refunded. The `timeline` then records `refund-skipped`.

While the refund is in progress, the order is `processing`, or `on-hold` while the refund is on hold, and its `timeline` records the `refund-*` events. The order is `failed` only once the refund is done, so wait for it to reach a final status before letting the user try again:

| Outcome | Timeline event | Order status |
| - | - | - |
| The deposit was refunded. | `refund-completed` | `failed` |
| The refund failed. | `refund-failed`, with its `reason`. | `failed` |
| The deposit could not be reverted. | `refund-commit-failed`, with its `error`. | `failed` |
| The deposit is not refunded, depending on why the withdrawal failed. | `refund-skipped` | `failed` |

When the deposit itself fails or expires, nothing was collected, so there is nothing to refund. When the refund fails, is skipped, or cannot be committed, the deposit is left unrefunded, so contact support.

## Order lifecycle

The `status` and `timeline` of an order follow its legs as they run.

### Statuses

The `status` of an order can have the following values:

* `pending`: The order is waiting for a push deposit, which the user has to send. An order with a pull deposit, such as a card charge, starts in `processing`, since the deposit is collected when the order is created.
* `processing`: The deposit or the withdrawal is being processed, or the refund is, if the order failed after the deposit.
* `on-hold`: A leg of the order is on hold, for example while it is under review. The order goes back to `processing` once it is released.
* `completed`: The withdrawal has completed and the funds have reached the `destination`.
* `failed`: The order did not complete. The `timeline` says which leg failed and whether the deposit was refunded.
* `expired`: The push deposit was not received within 24 hours. Only orders with a push deposit expire.

An order that is `completed`, `failed` or `expired` is final.

### Timeline

The `timeline` records the events of each leg, in the order they happen, each with its `timestamp`:

| Leg | Events |
| - | - |
| Deposit | `deposit-requested`, `deposit-processing`, `deposit-on-hold`, `deposit-completed`, `deposit-failed`, `deposit-expired` |
| Withdrawal | `withdrawal-processing`, `withdrawal-on-hold`, `withdrawal-sent`, `withdrawal-completed`, `withdrawal-failed`, `withdrawal-commit-failed` |
| Refund | `refund-address-requested`, `refund-address-completed`, `refund-processing`, `refund-on-hold`, `refund-sent`, `refund-completed`, `refund-failed`, `refund-commit-failed`, `refund-skipped` |

The `on-hold` and `failed` events carry their `reason`, and the `commit-failed` events carry the `error` that prevented the leg from starting. A leg that is released from hold goes back to processing, so its `processing` event happens again.

### Following an order

Rather than polling [Get order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/get-order.md), subscribe to the webhooks to follow an order:

| Webhook | Description |
| - | - |
| [Order created](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-created.md) | A new order has been created. |
| [Order status changed](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-status-changed.md) | The status of an order has changed. |
| [Order timeline updated](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-timeline-updated.md) | A new event has been added to the timeline of an order. |

See [Webhooks](https://developer.uphold.com/rest-apis/webhooks.md) for how to receive and verify them.

## Order amount errors

[Create quote](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) and [Create order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md) return the `transaction_amount_invalid` error when the specified amount violates a platform rule. The `rule` in the `details` says which one, and the `limit` object provides the amounts involved:

| Rule | Scenario |
| - | - |
| `minimum-limit-not-met` | The amount is below the minimum of a single order, in `limit.minimumAmount`. |
| `maximum-limit-exceeded` | The amount is above the maximum of a single order, in `limit.maximumAmount`. |
| `amount-exceeds-daily-limit`, `amount-exceeds-weekly-limit`, `amount-exceeds-monthly-limit` | The amount exceeds the periodic limit of the user. The `limit` carries the `maximumAmount` of the period and the `remainingAmount` still available. |

```json theme={null}
{
  "code": "transaction_amount_invalid",
  "message": "The amount exceeds the daily limit",
  "details": {
    "context": "body",
    "property": "denomination",
    "rule": "amount-exceeds-daily-limit",
    "limit": {
      "maximumAmount": "100.00",
      "remainingAmount": "80.00"
    }
  }
}
```

## Metadata

Orders support [metadata](https://developer.uphold.com/rest-apis/entity-metadata.md), so you can attach your own data to an order, such as the id of the checkout in your system, and map it to the records of your own system.

Send `metadata` when you [create the order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md), or manage it later with the [metadata endpoints](https://developer.uphold.com/rest-apis/on-off-ramp-api/metadata/set-metadata.md), using `orders` as the entity.

| Operation | Scope |
| - | - |
| [Get metadata](https://developer.uphold.com/rest-apis/on-off-ramp-api/metadata/get-metadata.md) | `on-off-ramp.orders.metadata:read` |
| [Set metadata](https://developer.uphold.com/rest-apis/on-off-ramp-api/metadata/set-metadata.md), [Update metadata](https://developer.uphold.com/rest-apis/on-off-ramp-api/metadata/update-metadata.md), [Delete metadata](https://developer.uphold.com/rest-apis/on-off-ramp-api/metadata/delete-metadata.md) | `on-off-ramp.orders.metadata:write` |
| [Create order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md) with `metadata` | `on-off-ramp.orders.metadata:write`, in addition to `on-off-ramp.orders:create` |

Without the write scope, a create request that includes `metadata` is rejected with `token_insufficient_scopes`, and the order is not created.
