Skip to main content
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

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.
The origin and destination are each represented by a node. The following node types are supported:
External accounts refer to the user’s external accounts, 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.
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 when creating the order.
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 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 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 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 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 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:
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.

Order legs

An order is a single operation, but it runs as up to three legs: a deposit, which collects the funds from the origin, a withdrawal, which sends them to the destination, and, if the order cannot be completed, a refund, 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:

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 of the Travel Rule Widget to start the withdrawal-form flow, passing the quoteId of the requirement as data.quoteId. The widget collects the data from the user and resolves the RFI.
  • Through the API: call List requests for information with the quoteId as reference to find the RFI, and resolve it with Update request for information.
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 and via API for a detailed walkthrough. See 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: 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: 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, subscribe to the webhooks to follow an order: See Webhooks for how to receive and verify them.

Order amount errors

Create quote and Create order 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:

On-ramp via API

Let users buy crypto with a card or an APM.

On-ramp via Widget

Let users buy crypto with a card or an APM, using the Payment Widget.

Off-ramp via API Coming soon

Let users sell crypto and cash out to a debit card.

Off-ramp via Widget Coming soon

Let users sell crypto and cash out to a card, using the Payment Widget.

Metadata

Orders support metadata, 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, or manage it later with the metadata endpoints, using orders as the entity. Without the write scope, a create request that includes metadata is rejected with token_insufficient_scopes, and the order is not created.