Skip to main content
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:
External accounts of type card represent credit or debit cards manually linked by the user for fiat deposits and withdrawals.
External accounts of type bank represent bank accounts used for fiat deposits and withdrawals via networks like FPS or SEPA.These accounts are automatically created after the user’s first deposit, using the bank details returned by Set Up Account Deposit Method endpoint.

​
Making transactions with external accounts

To pull funds from an external account (external account → Uphold):
  1. Link the external account using Create External Account.
  2. Ensure the external account supports the deposit feature.
  3. Create a quote where:
    • The origin is the external account.
    • The destination is one of the user’s Uphold accounts.
  4. Create a transaction to commit the quote.
To send funds to an external account (Uphold → external account):
  1. Make sure the external account is valid (status: ok).
  2. Ensure the external account supports the withdraw feature.
  3. Create a quote where:
    • The origin is a user’s Uphold account.
    • The destination is the external account.
  4. Create a transaction to commit the quote.

​
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 NumberNetworkTypeCountryMethod
5355223761921186MastercardDebitGBInstant
5573606426146833MastercardDebitGBInstant
4921817844445119VisaDebitGBInstant
4659105569051157VisaDebitGBInstant
4242424242424242VisaCreditGBN/A
5385308360135181MastercardCreditUSN/A
4485040371536584VisaCreditUSN/A
5518832400606463MastercarddebitUSN/A
4024764449971519VisaDebitUSInstant
5502514549870410MastercardDebitFRInstant
5436031030606378MastercardCreditMUN/A

​
Reserved amounts

To trigger transaction errors for any of the cards above, use the corresponding amounts below.
AmountError
12.12card_unauthorized
15.15card_declined_by_bank
20.20card_expired
26.26insufficient_funds
34.34velocity
60.60card_unauthorized
⌘I