Skip to main content
This guide walks you through supporting card deposits using the REST API.

Prerequisites

Walkthrough


Check available rails

Call List Rails to verify card deposit is available.
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.
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.

Select destination account

Card deposits can target any account. If the selected account is not in the card’s currency, the amount will be converted at settlement using Uphold’s prevailing rate. Make sure the destination asset has the necessary features enabled.

Find an existing account

Call List accounts to retrieve the user’s accounts and let them pick the one they want to fund.

Create a new account

If the user has no accounts, create one with Create account before proceeding.

Create a quote

Call Create quote with the card external account as origin and the destination account.
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. Always include the authorize:3ds requirement for card-origin transactions — whether the card requires authorization is decided per transaction by the issuer and isn’t known until the transaction response. You may include stateful data in query parameters of the returnUrl, such as the quoteId, so you can preserve context and resume the transaction flow upon return. 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 authorization is required, the response will include a confirmationUrl on the origin node. Redirect the user to that URL to complete the challenge. After completion, the user will be redirected back to your returnUrl.
In a successful card deposit, the origin is the external-account representing the card and the destination is the user’s account.

Monitor for settlement

Card deposit transactions may remain in processing while the payment settles. Monitor until the transaction reaches a terminal state.

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.
You now support card deposits 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: 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.