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.
origin and destination are each represented by a node. The following node types are supported:
External account
External account
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 thenetworkof the card. When creating an order, itsconfirmationUrlis the URL to send the user to for confirming the authorization, such as a 3DS challenge.apm: A saved APM account, which also carries aconfirmationUrlwhen the user must confirm the payment.crypto: A saved crypto address of the user, as the destination of an on-ramp order. Itsnetworkandexecutionare those of a crypto address node.
APM
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 when creating the order.Crypto address
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 thetransactionHash.offchain: Processed within Uphold, with theaccountIdandaccountOwnerIdit was made to.simulated: Simulated without affecting the blockchain, with a simulatedtransactionHash.
Creating a quote-based order
An order is always created from a quote, in two steps:- Create a quote with the
type,origin,destinationanddenominationof the order. The quote returns the rates, thefeesand therequirementsthat must be met to create the order. - Create the order with the
quoteId, before the quoteexpiresAt. Provide the data for eachauthorize:*requirement of the quote inparams.requirements, such asauthorize:3dswith areturnUrl, and resolve thetravel-rulerequirement before creating the order. Optionally, attach your ownmetadatato the order. If the metadata cannot be saved, the order is still created, and the response describes the issue inerrors.metadata.
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 betweenorigin 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.Fees
Thefees 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 therequirements 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:
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 theorigin, 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 theorigin 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
Thepricing 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 thedestination: 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 thetravel-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 with the
withdrawal-formflow anddata.quoteIdset to thequoteIdof the requirement. The widget collects the data from the user and resolves the RFI. - Through the API: call List requests for information with the
quoteIdasreferenceto find the RFI, and resolve it with Update request for information.
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. Thetimeline 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
Thestatus and timeline of an order follow its legs as they run.
Statuses
Thestatus 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 inprocessing, 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 toprocessingonce it is released.completed: The withdrawal has completed and the funds have reached thedestination.failed: The order did not complete. Thetimelinesays 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.
completed, failed or expired is final.
Timeline
Thetimeline 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 thetransaction_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:
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. Sendmetadata 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.