Introduction

The external accounts group of endpoints allows you to manage financial accounts that users own outside the platform, such as debit or credit cards.

External accounts can be used for both pull deposits (moving funds into Uphold) and withdrawals (sending funds out of Uphold).

External account shape

An external account includes the following properties:

{
  "id": "aa6e6efa-8d73-497c-8278-0347f459bd68",
  "ownerId": "1e32fca3-23f7-40ed-bc1b-de10c790182d",
  "type": "card",
  "status": "ok",
  "label": "My Visa Card",
  "asset": "GBP",
  "network": "visa",
  "features": ["deposit", "withdraw"],
  "createdAt": "2024-06-01T00:00:00Z",
  "updatedAt": "2024-07-15T00:00:00Z"
}

Each external account has a status that reflects its availability:

• processing: The account is being verified.
• ok: The account is valid and ready to use.
• failed: The verification failed — check statusDetails.reason for the failure reason.
• restricted / blocked: The account is temporarily or permanently unusable.

Types of external accounts

There are different types of external accounts available on the platform:

Card

External accounts of type card represent credit or debit cards manually linked by the user for fiat deposits and withdrawals.

Bank

External accounts of type bank represent bank accounts used for fiat deposits and withdrawals via networks like FPS, SEPA or ACH.

These accounts are automatically created after the user’s first successful deposit, using the bank details returned by Set Up Account Deposit Method endpoint.

When to use external accounts

• Bank push deposits: Use Set Up Account Deposit Method to show bank details. For FPS deposits, an external account is created automatically for each originating bank account. See the Bank Deposit (Bank transfer) flow for the example.
• Bank withdrawals: Use a bank external account as the destination of a quote to pay out over. See the Bank Withdrawal (Bank transfer) flow for the example.
• Card deposits/withdrawals: Link cards as external-account nodes and process transactions with quote-based flows (for example, using the Payment Widget Authorize).

Related flows

Bank Deposit

Generate deposit details and receive push deposits.

Bank Withdrawal

Withdraw funds to a bank account.

Managed UI option

If you need a managed UI to collect payment or bank details, consider the Payment Widget (select-for-deposit / select-for-withdrawal) and then consume the returned depositMethod or external-account with the Core API.

Test cards

You can use the cards listed below to test external accounts of type card in the Sandbox environment, and cover a variety of scenarios (adding cards successfully, authentication challenges and error cases).

Card Number	Network	Type	Country	Method
5355223761921186	Mastercard	Debit	GB	Instant
5573606426146833	Mastercard	Debit	GB	Instant
4921817844445119	Visa	Debit	GB	Instant
4659105569051157	Visa	Debit	GB	Instant
4242424242424242	Visa	Credit	GB	N/A
5385308360135181	Mastercard	Credit	US	N/A
4485040371536584	Visa	Credit	US	N/A
5518832400606463	Mastercard	Debit	US	N/A
4024764449971519	Visa	Debit	US	Instant
5502514549870410	Mastercard	Debit	FR	Instant
5436031030606378	Mastercard	Credit	MU	N/A

Reserved amounts

To trigger transaction errors for any of the cards above, use the corresponding amounts below.

Amount	Error
12.12	card_unauthorized
15.15	card_declined_by_bank
20.20	card_expired
26.26	insufficient_funds
34.34	velocity
60.60	card_unauthorized