Prerequisites
- The user has completed onboarding.
- The user has an Uphold crypto account with sufficient balance.
- Capabilities — converting crypto into fiat requires the
tradescapability (UK retail users have a 24-hour post-onboarding cooldown before trading). Card payouts also require thecard-withdrawalscapability and a destination card withoctSupport: "supported", and APM payouts the withdrawal capability of the method, such aspaypal-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
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.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 withtype=card to verify that a card rail with the withdraw feature is available.
Link or select the card
Let the user link a new card or select an existing one. The card external account is thedestination of the sell.
Call List external accounts to fetch the user’s saved cards.
status: "ok" and withdraw in features.
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.
status: "processing" while the card is validated.
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.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 withtype=bank to verify that the bank rail has the withdraw feature. The example below uses SEPA.
Link or select the bank account
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 fortype: "bank", status: "ok", and "withdraw" in features.
Alternative payment method (APM)
Check available rails
Call List Rails withtype=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
apmnode with themethodthe user is paid with, such aspaypal. No external account is needed. - A saved APM account, such as a PayPal account, referenced by the
idof its external account (from List external accounts).
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 theapm 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. NoreturnUrl 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 thetransaction: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 forcore.transaction.status-changed webhooks or polling.
Via webhooks
Subscribe tocore.transaction.status-changed. The event fires on every status transition; filter on data.transaction.status to detect terminal states:
completed— transaction settled successfullyfailed— transaction failed;data.transaction.statusDetails.reasonsays 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.
Notify the user
Display a confirmation when thecore.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 singlecore.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 itserror 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: itsstatus 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.