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",
  "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 rail supports the deposit feature using List Rails.
  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 rail supports the withdraw feature using List Rails.
  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.