> ## 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.

# On & Off Ramp API introduction

> Move value between fiat and crypto with on-ramp and off-ramp orders created from quotes on Uphold.

The On & Off Ramp API lets you move value between fiat and crypto through a single order per direction: an **on-ramp** order buys crypto with fiat, and an **off-ramp** order sells crypto for fiat.

> [!NOTE]
>
> This is a **preview** of the new On & Off Ramp API. It is available in **Sandbox** only, and it can change before release.

## Why this API

On-ramp and off-ramp flows are among the most requested by partners. You can build them with the Core API, but each one takes two transactions: a deposit that brings the funds into an account of the user, and a withdrawal that sends them out again. Your integration then has to chain the two, refund the deposit when the withdrawal fails, and meet the regulatory requirements of both.

The On & Off Ramp API takes on that work. A single order covers the whole flow, and Uphold runs the deposit and the withdrawal behind it:

* **One operation instead of two.** You create and follow one order, with its own status and timeline, instead of chaining a deposit and a withdrawal and keeping them in step.
* **Built-in refunds.** If the withdrawal fails after the funds were collected, Uphold usually returns them to the user. See [Refunds](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#refunds).
* **Requirements known up front.** The quote lists what both legs of the order need, such as Travel Rule information or a 3DS authorization, so you collect it once, before creating the order. See [Requirements](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#requirements).

Although an order abstracts away two transactions, it is modeled on the same concepts as a Core [transaction](https://developer.uphold.com/rest-apis/core-api/transactions/overview.md): it has an `origin`, a `destination` and a `denomination`, it is created from a quote, and the quote lists the requirements to meet first. If you have integrated Core transactions, most of what you know carries over.

## How it works

Unlike a Core [transaction](https://developer.uphold.com/rest-apis/core-api/transactions/overview.md), which moves funds into, out of or between the accounts of a user, both ends of an order are outside the user's accounts.

### Order types

| Type | Takes | Delivers |
| - | - | - |
| `on-ramp` | Fiat from a payment method of the user, such as a card or an alternative payment method (APM). | Crypto to a crypto address or a saved crypto external account. |
| `off-ramp` | Crypto that the user deposits from an external wallet. | Fiat to a payment method of the user, such as a debit card. |

Use [List rails](https://developer.uphold.com/rest-apis/on-off-ramp-api/assets/list-rails.md) to find which payment methods, assets and networks each ramp type supports. Don't use the Core [List rails](https://developer.uphold.com/rest-apis/core-api/assets/list-rails.md) for orders, since its rails can differ from those of orders. See [Why not use the Core API rails](https://developer.uphold.com/rest-apis/on-off-ramp-api/assets/list-rails.md#why-not-use-the-core-api-rails).

### Order flow

The user needs the `on-ramp` or `off-ramp` capability, which depends on their [verification tier](#capabilities-and-verification-tiers). An order then goes through these steps:

1. **Quote.** [Create a quote](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) with the origin, destination and amount. It returns the rates, the fees, how firm its price is, and the [requirements](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#requirements) to meet, such as Travel Rule information or a 3DS authorization. A quote expires after a short time and can only be used once.
2. **Order.** [Create the order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md) from the quote before it expires, with the data for each requirement.
3. **Deposit.** Uphold collects the funds into an internal on-ramp or off-ramp account of the user. A [pull deposit](#pull-and-push-deposits) is collected right away. For a push deposit, the order stays `pending` until the funds arrive, and expires if they don't arrive within 24 hours.
4. **Withdrawal.** Uphold sends the funds to the destination, and the order is `completed`. If the withdrawal fails, Uphold usually refunds the deposit. Depending on why it failed, such as the outcome of a compliance review, the deposit may not be refunded. See [Refunds](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#refunds).

Subscribe to the order [webhooks](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#following-an-order) to follow an order through these steps, instead of polling it. The internal ramp accounts are [hidden from the Core API](#visibility-in-the-core-api), but the deposit and the withdrawal are not.

### Pull and push deposits

How the deposit is made decides how firm the price of an order is:

* **Pull deposit**: Uphold collects the funds from the origin itself, such as by charging a card. The deposit happens when the order is created, so the price of the quote is locked.
* **Push deposit**: The user sends the funds from outside Uphold, such as crypto from an external wallet. The deposit only arrives once the user sends it and Uphold detects it, which can take a while depending on the network, so the price is estimated until then.

The `pricing` of a quote says which one applies. See [Pricing](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#pricing).

## Capabilities and verification tiers

An on-ramp order needs the user's `on-ramp` [capability](https://developer.uphold.com/rest-apis/core-api/capabilities/overview.md), and an off-ramp order needs the `off-ramp` capability. What the user must verify for them depends on their verification tier, which is set by the user's total ramp volume: the more a user has moved through orders, the more verification they need.

### Tiers

The tier depends on the user's total on-ramp and off-ramp volume, counted over their whole history in the user's currency: USD, EUR or GBP, based on their address. Failed and expired orders don't count. A quote also counts its own amount (see [Checking the capability](#checking-the-capability)). A tier completed for one direction carries over to the other.

| Tier | Total volume (default, USD, EUR or GBP) | Ramp types | Verification added |
| - | - | - | - |
| Tier 1 | Up to 5,000 | On-ramp only | [Email](https://developer.uphold.com/rest-apis/core-api/kyc/update-email.md), verified [phone](https://developer.uphold.com/rest-apis/core-api/kyc/update-phone.md), [profile](https://developer.uphold.com/rest-apis/core-api/kyc/update-profile.md), [address](https://developer.uphold.com/rest-apis/core-api/kyc/update-address.md), electronic [identity](https://developer.uphold.com/rest-apis/core-api/kyc/update-identity.md) verification, and sanctions screening. |
| Tier 2 | Up to 10,000 | On-ramp and off-ramp | [Identity](https://developer.uphold.com/rest-apis/core-api/kyc/update-identity.md) verification with a document and a selfie. Off-ramp also needs [tax details](https://developer.uphold.com/rest-apis/core-api/kyc/update-tax-details.md). |
| Tier 3 | Above 10,000 | On-ramp and off-ramp | [Customer due diligence](https://developer.uphold.com/rest-apis/core-api/kyc/update-customer-due-diligence.md), and [enhanced due diligence](https://developer.uphold.com/rest-apis/core-api/kyc/update-enhanced-due-diligence.md) for high-risk users. |

* **Off-ramp starts at Tier 2.** Cashing out always needs document-based identity verification, even for the first order. A user who only completed Tier 1 must complete Tier 2 before their first off-ramp order.
* **Failed checks require Tier 2 while they fail.** While the user's identity or address verification has a failed result, or their sanctions screening has a match, they need Tier 2 verification, even at Tier 1 volume. If the failed process is [`partner-verified`](https://developer.uphold.com/rest-apis/core-api/kyc/overview#verification) for your organization, you can submit it again, and once it passes, for example with a corrected proof of address, Tier 1 applies again.
* **A failed Tier 2 check blocks orders while it fails.** While the document-based identity verification has a failed result, the user can't place orders. If the `identity` process is `uphold-verified`, you can ask Uphold to allow the user to submit a new identity. If it's [`partner-verified`](https://developer.uphold.com/rest-apis/core-api/kyc/overview#verification), you can submit a new identity, and once it passes, the user can place orders again.
* **Thresholds.** The volume thresholds above are the defaults. Depending on your integration, your organization can have different ones.

### Checking the capability

The tier is checked for every quote and order, and the volume it's based on depends on the check:

* [Get user capability](https://developer.uphold.com/rest-apis/core-api/capabilities/get-user-capability.md) for `on-ramp` or `off-ramp` uses the user's current volume. Its `requirements` list the KYC processes to complete for the current tier, for example `user-must-submit-identity-via-physical-document` at Tier 2.
* A quote uses the user's current volume plus the amount of the quote. A quote that takes the user into a new tier needs that tier's verification, even if the capability showed no requirements, and fails with `user_capability_failure` until it's met. See [Create quote](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) for the error.

A quote keeps the tier it was created under. If the user's tier changes before the order is created, for example because another order completed in between, the order fails with the `user-tier-changed` reason, and you need to create a new quote.

## Widgets

Uphold's [widgets](https://developer.uphold.com/widgets/introduction.md) provide ready-made UIs for parts of an order. Some flows need the Payment Widget; the others are optional, so you can use the REST API instead.

| Widget | Use it to | Required? |
| - | - | - |
| [Payment Widget](https://developer.uphold.com/widgets/payment/introduction.md) | Let the user select or link the payment method of an order, and authorize the deposit of an on-ramp order, which also creates the order. See [On-ramp via Widget](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-payment-widget.md). | **Yes**, for on-ramp orders paid with an alternative payment method (APM), such as Apple Pay, Google Pay or PayPal, and for linking cards if your organization isn't PCI DSS compliant. |
| [Travel Rule Widget](https://developer.uphold.com/widgets/travel-rule/introduction.md) | Collect the Travel Rule information of an on-ramp quote and resolve its request for information. | No. You can [resolve the RFI with the API](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#requests-for-information-rfis). |
| [KYC Widget](https://developer.uphold.com/widgets/kyc/introduction.md) | Collect the verification of the user's [tier](#capabilities-and-verification-tiers), such as document-based identity verification. | **Yes**, when the `identity` or `proofOfAddress` process is [`uphold-verified`](https://developer.uphold.com/rest-apis/core-api/kyc/overview#verification) for your organization, since Uphold verifies them in a provider session. Optional for the other processes, and for `partner-verified` ones, which you submit with the API. |

### Payment Widget

An APM deposit can only be authorized through the Payment Widget. APMs that support account linking, such as PayPal, are saved as an external account the first time the user pays with them. See the [APM transfers introduction](https://developer.uphold.com/developer-guides/apm-transfers/introduction.md).

Linking a card with [Create external account](https://developer.uphold.com/rest-apis/core-api/external-accounts/create-external-account.md) sends the full card number and security code through your systems, which requires your organization to be PCI DSS compliant. If it isn't, link cards through the Payment Widget, which collects the card details itself.

Call [Create widget session](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) with one of the order flows. See [On & Off Ramp flows](https://developer.uphold.com/widgets/payment/flows.md#on-&-off-ramp-flows) for what each one returns.

| Flow | What it does |
| - | - |
| `on-ramp:select-deposit-origin` | Links or selects the card or APM the user pays with. |
| `on-ramp:select-withdrawal-destination` | Collects the crypto asset, network and address to deliver to. |
| `off-ramp:select-deposit-origin` | Selects the crypto asset and network the user deposits from. |
| `off-ramp:select-withdrawal-destination` | Links or selects the card the payout goes to. |
| `order:authorize-deposit` | Creates an on-ramp order from a quote, with `data.quoteId`, and authorizes its card or APM deposit, including any 3DS challenge. |

You can mix the widget with the REST API, for example selecting the payment method with the widget and creating the quote with the API. Off-ramp orders have no authorize flow: create them with [Create order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md).

## Visibility in the Core API

An order is not a Core entity, but the funds it moves are. This is what the Core API shows for an order, and what it leaves out.

### Order legs

The deposit and the withdrawal of an order are regular Core [transactions](https://developer.uphold.com/rest-apis/core-api/transactions/overview.md). They're returned by the Core transaction endpoints and trigger the Core transaction webhooks, like any other transaction of the user. Their `origin` or `destination` is an `on-ramp-account` or `off-ramp-account` node, which carries the `orderId` of the order, so you can match each transaction to its order. This includes the reversal of a deposit when an order is [refunded](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#refunds): its `origin` is the ramp node, and its `destination` is the payment method the order was paid with.

The `orderId` is linked asynchronously, so it may be missing at first, such as on the `core.transaction.created` webhook of a crypto deposit. Transactions that aren't part of an order, such as dust sweeps, never carry one.

Only the user of the order sees these nodes. When an on-ramp order sends crypto to an address of another Uphold user, that user sees an off-chain `crypto-address` node instead, with no `orderId`.

### Internal ramp accounts

The on-ramp and off-ramp accounts that orders move funds through are internal to Uphold:

* Their ids are never returned, and they aren't listed among the user's [accounts](https://developer.uphold.com/rest-apis/core-api/accounts/overview.md).
* They don't trigger account webhooks, such as `core.account.created` or `core.account.balance-changed`.

### Portfolio

The internal ramp accounts are excluded from the user's [portfolio](https://developer.uphold.com/rest-apis/core-api/portfolio/overview.md):

* **Balances:** funds held for an order while it is processing aren't included in the portfolio balances, the historical balances or the portfolio statement.
* **Performance:** the activity of the internal ramp accounts doesn't count towards the performance of the portfolio, its assets or its accounts.
