Skip to main content
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.
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.
  • 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.
Although an order abstracts away two transactions, it is modeled on the same concepts as a Core transaction: 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, 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

Use List rails to find which payment methods, assets and networks each ramp type supports. Don’t use the Core List rails for orders, since its rails can differ from those of orders. See 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. An order then goes through these steps:
  1. Quote. Create a quote with the origin, destination and amount. It returns the rates, the fees, how firm its price is, and the 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 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 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.
Subscribe to the order webhooks to follow an order through these steps, instead of polling it. The internal ramp accounts are hidden from 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.

Capabilities and verification tiers

An on-ramp order needs the user’s on-ramp capability, 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). A tier completed for one direction carries over to the other.
  • 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 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, 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 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 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 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.

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. Linking a card with Create external account 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 with one of the order flows. See On & Off Ramp flows for what each one returns. 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.

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. 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: 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.
  • 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:
  • 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.