Skip to main content
A sell moves value out of the user’s Uphold crypto account to a fiat payment method: a card (via OCT), a bank account, or an alternative payment method (APM) such as PayPal or Apple Pay. Uphold’s Anything to Anything technology moves value from any asset to any other, so the conversion and the payout happen in a single transaction: the crypto account is debited, the crypto is converted at the quote’s rate, and the fiat is paid out. There’s no need to trade into a fiat account first and then withdraw.

Prerequisites

  • The user has completed onboarding.
  • The user has an Uphold crypto account with sufficient balance.
  • Capabilities — converting crypto into fiat requires the trades capability (UK retail users have a 24-hour post-onboarding cooldown before trading). Card payouts also require the card-withdrawals capability and a destination card with octSupport: "supported", and APM payouts the withdrawal capability of the method, such as paypal-withdrawals. Bank withdrawal capability varies by rail — see the per-rail guides.
  • For APM payouts, the Payment Widget is set up in your frontend.
  • The integration uses Uphold’s rails. Partner-owned rails (omnibus) follow a different flow not covered here.

Walkthrough

Prefer to click through the flow? See the interactive sell walkthrough.

Select a crypto to sell

Call List accounts to retrieve the user’s Uphold accounts. Present crypto accounts with a non-zero balance as sellable.
The chosen account (f8c2d1e4 / BTC in this example) is the origin for the sell.

Define the destination

The destination determines where the sell proceeds go. Choose the path that matches the user’s intent.

Card

The user receives the proceeds on a linked card, paid out via OCT.

Check available rails

Call List Rails with type=card to verify that a card rail with the withdraw feature is available.
Let the user link a new card or select an existing one. The card external account is the destination of the sell. Call List external accounts to fetch the user’s saved cards.
Make sure the selected card has status: "ok" and withdraw in features.
If the user wants to use a card not yet on file, call Create external account with the card details.
This 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, with its flow.
The response initially returns status: "processing" while the card is validated.
Once validated, the status transitions to ok and the full details are available.
Monitor the external account status via Get external account or the core.external-account.status-changed webhook until status is ok before proceeding.
If the card can’t be linked, Create external account returns an HTTP error. These are the errors to act on, such as by showing the user a message:
A freshly linked card returns "octSupport": "unknown" while Uphold verifies OCT eligibility. Poll GET /core/external-accounts/{id} until details.octSupport is "supported" before using the card as a sell destination.

EMD disclaimer

This disclaimer is required to comply with FCA regulations. Display it to users based in GB, the first time they link a credit/debit card or generate bank deposit details — it only needs to be shown once:
Uphold Europe Limited is an EMD Agent of Optimus Cards UK Limited (FRN: 902034). All received funds are held in a designated safekeeping account with a regulated bank and kept separate from Uphold’s own assets. These funds are not protected by the UK Financial Services Compensation Scheme.

Bank account

The user receives the proceeds in a linked bank account.

Check available rails

Call List Rails with type=bank to verify that the bank rail has the withdraw feature. The example below uses SEPA.
Bank account linking varies by rail. See the per-rail guides: Once the user has a linked bank external account, retrieve it with List external accounts. Filter for type: "bank", status: "ok", and "withdraw" in features.

Alternative payment method (APM)

Check available rails

Call List Rails with type=apm to find the APMs that can be used as a sell destination: those whose features include withdraw.

Define the APM destination

The user receives the proceeds through an APM, such as PayPal. The destination is either:
  • An apm node with the method the user is paid with, such as paypal. No external account is needed.
  • A saved APM account, such as a PayPal account, referenced by the id of its external account (from List external accounts).
The payout is authorized through the Payment Widget, which creates the transaction. See the APM withdrawal guides for each method.

Transaction preview

Show the user a preview of the sell before committing. Create a quote from the crypto account to the card, bank account or APM: it converts the crypto into fiat at a locked rate. denomination sets the amount and the asset it’s expressed in, and target whether it’s the amount the user sells (origin) or receives (destination). Present origin.amount (the crypto debited), destination.amount (the fiat the user receives) and the fees to the user.
Quotes are short-lived. Use refreshAt to drive re-quoting: if the user hasn’t confirmed by then, create a new quote and show the updated amounts, since there’s no refresh endpoint. The quote’s expiresAt is equal to or later than refreshAt, to give the user time to complete an external action needed to proceed, such as authorizing an APM payment.

Card

Quote from the crypto account to the card external account.

Bank account

Quote from the crypto account to the bank external account. The example below uses SEPA (EUR). For rail-specific details, see the per-rail bank-transfer withdrawal guides.

Alternative payment method (APM)

Quote from the crypto account to the APM, with the apm node as the destination. The quote lists the authorize:* requirement of the method, such as authorize:paypal.

Confirm quote

Card

Commit the sell by calling Create transaction with the quote ID. No returnUrl or 3DS is needed — card sell transactions do not require user card authorization.

Bank account

Commit the sell by calling Create transaction with the quote ID.
Bank withdrawals settle asynchronously — instantly for FPS / FedNow, hours to days for ACH / SEPA. See the per-rail bank-transfer withdrawal guides for timing details.

Alternative payment method (APM)

Don’t create the transaction yourself. Hand off to the Payment Widget: call Create widget session to start the transaction:authorize flow, passing the quoteId and the authorize:* requirement of the quote, and the widget authorizes the payout and creates the transaction. See the APM withdrawal guides for the session, the widget setup and its events.

Monitor for settlement

Monitor the transaction by listening for core.transaction.status-changed webhooks or polling.

Via webhooks

Subscribe to core.transaction.status-changed. The event fires on every status transition; filter on data.transaction.status to detect terminal states:
  • completed — transaction settled successfully
  • failed — transaction failed; data.transaction.statusDetails.reason says why. See Failure reasons

Via polling

GET /core/transactions/{transactionId} returns the current state. Use polling as a fallback when webhook delivery cannot be guaranteed. Terminal statuses are completed and failed.
Prefer webhooks over polling in production. See Webhooks for setup instructions.

Notify the user

Display a confirmation when the core.transaction.status-changed webhook fires with status: "completed". For card payouts, include the payout amount and currency so the user knows the card credit to expect. For bank withdrawals, confirm the amount and destination account once the withdrawal settles.
You now support crypto sell via the REST API.

Sample transaction

A sell to a card debits the user’s internal crypto account, converts at the locked quote rate, and pays out fiat to the linked card via OCT. The transaction fires a single core.transaction.status-changed webhook on completion.

Request errors

Create quote and Create transaction reject a request with an HTTP error when it can’t go ahead, in which case no transaction is created. The table only lists the errors your integration should act on, such as by showing the user a message. The other errors usually point to an issue in your integration. See the API reference of each endpoint for the full list. For an APM, the Payment Widget creates the transaction, so the errors of Create transaction reach you through its error event instead: an authorize_transaction_failed error whose event.detail.error.cause is the original error, with the status in httpStatusCode and the same code and details as in the table. The errors of Create quote are returned to your backend as usual.

Failure reasons

A transaction that was created can still fail afterwards: its status becomes failed, or on-hold when information is requested, and statusDetails.reason says why. You learn about it through the core.transaction.status-changed webhook, or by polling Get transaction. The table only lists the reasons your integration should act on, such as by notifying the user.
If a card payout is declined after the crypto has been debited, the crypto is returned to the user’s Uphold account, not to an external wallet. Make sure your UI tells the user where the funds are.