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.
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 theon-ramp or off-ramp capability, which depends on their verification tier. An order then goes through these steps:
- 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.
- Order. Create the order from the quote before it expires, with the data for each requirement.
- 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
pendinguntil the funds arrive, and expires if they don’t arrive within 24 hours. - 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.
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.
pricing of a quote says which one applies. See Pricing.
Capabilities and verification tiers
An on-ramp order needs the user’son-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-verifiedfor 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
identityprocess isuphold-verified, you can ask Uphold to allow the user to submit a new identity. If it’spartner-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-ramporoff-rampuses the user’s current volume. Itsrequirementslist the KYC processes to complete for the current tier, for exampleuser-must-submit-identity-via-physical-documentat 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_failureuntil it’s met. See Create quote for the error.
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 overview. 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. Create a session with one of the order flows:
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. Theirorigin 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.createdorcore.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.