Prerequisites
- The user has completed onboarding and has the required capabilities enabled.
- A funded account to debit the funds from.
Walkthrough
Check available rails
Call List Rails to verify card withdrawal is available.Select source account
Card withdrawals can be sourced from any account. If the selected account is not in the card’s currency, the balance will be converted at the time of the transaction using Uphold’s prevailing rate. Make sure the origin asset has the necessary features enabled. Call List accounts to retrieve the user’s accounts and let them pick the one to withdraw from.Link or select a card account
Let the user link a new card or select an existing one.Find an existing card account
Call List external accounts to fetch the user’s saved cards.status: "ok" and withdraw in features.
Link a new card account
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.
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.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.
Create a quote
Call Create quote with the origin account and the card external account as destination.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.Confirm and create transaction
Once the user confirms, call Create transaction with the quote ID.account and the destination is the external-account representing the card. The transaction status is initially processing and updates to completed once the transfer settles.
Notify the user
Display an in-app confirmation when the transaction iscompleted, and send an email if applicable.
You now support card withdrawals via the REST API.
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.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.