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:

​
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

To support testing of card flows in sandbox environment, you can use the test cards provided by Checkout.com.

These cards allow you to test different scenarios involved in adding a card, including successful saves, authentication challenges (such as 3D Secure), and error conditions.