Skip to main content
A buy moves value from a fiat payment method, a card or an alternative payment method (APM), into the user’s Uphold crypto account. Uphold’s Anything to Anything technology moves value from any asset to any other, so the deposit and the conversion happen in a single transaction: the payment method is charged in fiat, and the crypto is credited to the user’s crypto account. There’s no need to deposit into a fiat account first and then trade.

Prerequisites

  • The user has completed onboarding.
  • Capabilities — card buys require the cards capability, and APM buys require deposits and the capability of the method, such as paypal. Converting fiat into crypto requires trades (UK retail users have a 24-hour post-onboarding cooldown before trading).
  • For APM buys, 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 buy walkthrough.

Select a crypto to buy

Call List assets to retrieve the assets available on the platform. Filter to assets that include buy in their features array to show only purchasable assets.
The chosen asset (BTC in this example) becomes the destination.asset for the buy. Call List accounts to find the user’s existing Uphold accounts for that asset.
If the user does not yet have an account for the chosen asset, create one with Create account.
The crypto account is the destination of the buy.

Define the source

The source is the fiat payment method that funds the buy.
Bank transfers are push deposits: the user sends the funds from their bank to deposit details, so they don’t follow this guide. See the bank transfer deposit guides. SEPA and FPS deposit details can target the crypto account directly, which converts the deposit into the crypto when it settles.

Card

Check available rails

Call List Rails to verify that a card rail with the deposit feature is available.
Let the user link a new card or select an existing one. The card external account is the origin of the buy. Call List external accounts to fetch the user’s saved cards.
Make sure the selected card has status: "ok" and deposit 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:

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.

Alternative payment method (APM)

Check available rails

Call List Rails with type=apm to find the APMs the user can pay with: those whose features include deposit.

Define the APM origin

The origin is either:
  • An apm node with the method the user pays with, such as paypal. No external account is needed.
  • A saved APM account, referenced by the id of its external account (from List external accounts).
The payment is authorized through the Payment Widget, which collects what the payment provider needs and creates the transaction. See the APM deposit guides for each method.

Transaction preview

Show the user a preview of the buy before committing. Create a quote from the payment method to the crypto account: it converts the fiat into the crypto at a locked rate. denomination sets the amount and the asset it’s expressed in, and target whether it’s the amount the user pays (origin) or receives (destination). Present origin.amount (what the payment method is charged), destination.amount (the crypto 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 card to the crypto account.

Alternative payment method (APM)

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

Confirm quote

Card

Commit the buy by calling Create transaction with the quote ID. Always include the authorize:3ds requirement — the card issuer may require 3DS authorization. You may embed stateful data in the returnUrl query parameters to resume the flow after redirect. Include the X-Uphold-User-Ip and X-Uphold-User-Agent headers with the end user’s IP and user agent. They’re required when a returnUrl is sent, and they’re used for the 3DS risk evaluation.
If origin.node.confirmationUrl is present, redirect the user to that URL to complete the 3DS challenge. After completion, the issuer redirects the user back to your returnUrl.

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 payment with the provider and creates the transaction. See the APM deposit 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": the crypto is now credited to the user’s Uphold account. Show both the amount charged and the crypto received.
You now support crypto buy via the REST API.

Sample transaction

A card buy charges the card in fiat, converts at the locked quote rate, and credits the crypto to the user’s crypto account, all in one transaction. The transaction fires a 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.