> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External accounts API overview

> Manage external financial accounts, such as user-owned debit and credit cards or bank accounts, used for pull deposits and withdrawals, and as the origin of FPS and SEPA bank push deposits.

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). For FPS and SEPA bank **push deposits**, the sender's bank account is also registered as an external account and identified as the origin of the resulting transaction.

## External account shape

An external account includes the following properties:

```json [expandable] theme={null}
{
  "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. This status is independent from the ownership `verifications` of `crypto` external accounts (each with its own `level` and `status`), described in [Verifying a crypto external account](#verifying-a-crypto-external-account).

* `processing`: The account is being validated and is not yet available.
* `ok`: The account is valid and ready to use.
* `failed`: The validation 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:

> [accordion] Card
>
> External accounts of type `card` represent **credit or debit cards** manually linked by the user for **fiat deposits and withdrawals**.

> [accordion] Bank
>
> External accounts of type `bank` represent **bank accounts** used for **fiat deposits and withdrawals** via networks like **FPS**, **SEPA** or **ACH**.
>
> How these accounts are created depends on the network:
>
> * **FPS** and **SEPA**: **automatically created** after the user's first successful push deposit, from the details of the bank account that sent the funds. The bank details returned by the [Set Up Account Deposit Method](https://developer.uphold.com/rest-apis/core-api/accounts/set-up-account-deposit-method.md) endpoint are the instructions to send funds *to* the user's Uphold account, not the details of the external account.
> * **ACH**: **explicitly created** by calling [Create external account](https://developer.uphold.com/rest-apis/core-api/external-accounts/create-external-account.md) with the user's routing and account number. Push deposits via ACH, FedNow / RTP and Wire are not linked automatically and have a `bank-address` origin instead.

> [accordion] APM
>
> External accounts of type `apm` represent authorized accounts at some alternative payment providers (currently **PayPal**) used for **fiat deposits and withdrawals**.
>
> These accounts are **automatically created** the first time a user transacts with the provider, using the details returned by the Payment Widget's [Authorize](https://developer.uphold.com/developer-guides/money-movement/payment-widget/authorize.md) flow.

> [accordion] Crypto
>
> External accounts of type `crypto` represent **cryptocurrency addresses** manually registered by the user for **crypto withdrawals only**.

Use the `type` query parameter of [List external accounts](https://developer.uphold.com/rest-apis/core-api/external-accounts/list-external-accounts.md) to retrieve only the types you need, e.g. `?type=crypto` or `?type=bank,card`.

## When to use external accounts

* **Bank push deposits (FPS and SEPA)**: A `bank` external account represents the user's originating bank account, registered automatically after the first deposit, and is used to identify them in recurring transactions. ACH, FedNow / RTP and Wire push deposits use a `bank-address` origin instead of an external account — [via API](https://developer.uphold.com/developer-guides/bank-transfers/deposit/via-rest-api) or [via Payment Widget](https://developer.uphold.com/developer-guides/bank-transfers/deposit/via-payment-widget).
* **Bank withdrawals**: A `bank` external account is used as the destination of a quote to pay out to the user's bank account — [via API](https://developer.uphold.com/developer-guides/bank-transfers/withdrawal/via-rest-api) or [via Payment Widget](https://developer.uphold.com/developer-guides/bank-transfers/withdrawal/via-payment-widget).
* **Card deposits**: A `card` external account is linked by the user and used as the origin of a quote. Card authorization may be required — [via API](https://developer.uphold.com/developer-guides/card-transfers/deposit/via-rest-api.md) or [via Payment Widget](https://developer.uphold.com/developer-guides/card-transfers/deposit/via-payment-widget/end-to-end.md).
* **Card withdrawals**: A `card` external account is linked by the user and used as the destination of a quote — [via API](https://developer.uphold.com/developer-guides/card-transfers/withdrawal/via-rest-api.md) or [via Payment Widget](https://developer.uphold.com/developer-guides/card-transfers/withdrawal/via-payment-widget/end-to-end.md).
* **APM deposits**: An `apm` external account is linked by the user and used as the origin of a quote, for APM providers that support account authorization (e.g., `paypal`) — [via API](https://developer.uphold.com/developer-guides/apm-transfers/deposit/via-rest-api) or [via Payment Widget](https://developer.uphold.com/developer-guides/apm-transfers/deposit/via-payment-widget).
* **APM withdrawals**: An `apm` external account is linked by the user and used as the destination of a quote, for APM providers that support account authorization (e.g., `paypal`) — [via API](https://developer.uphold.com/developer-guides/apm-transfers/withdrawal/via-rest-api) or [via Payment Widget](https://developer.uphold.com/developer-guides/apm-transfers/withdrawal/via-payment-widget).
* **Crypto withdrawals**: A `crypto` external account is registered by the user and used as the destination of a quote to withdraw to a saved cryptocurrency address — [via API](https://developer.uphold.com/developer-guides/crypto-transfers/withdrawal/via-rest-api.md).

## Verifying a crypto external account

A `crypto` external account can carry a Travel Rule verification of its address, tracked as one entry per `level`:

* `declared`: A self-declaration questionnaire about the address (e.g. whether it belongs to a VASP or a self-hosted wallet). Initiate one through the [external account verifications](https://developer.uphold.com/rest-apis/core-api/external-accounts/setup-external-account-verification.md) endpoint, then resolve it by [submitting the collected answers](https://developer.uphold.com/rest-apis/core-api/requests-for-information/update-request-for-information.md).
* `verified`: Cryptographic proof of address ownership, established either by message signing or a Satoshi test. Initiate it through the same [setup endpoint](https://developer.uphold.com/rest-apis/core-api/external-accounts/setup-external-account-verification.md) with `level: verified`, then resolve it either by [submitting the signed message](https://developer.uphold.com/rest-apis/core-api/requests-for-information/update-request-for-information.md) (message signing) or automatically on-chain once the Satoshi test amount is received (Satoshi test). A verification achieved during a crypto deposit or withdrawal is also reflected here.

Check the status of either level with [Get external account verification](https://developer.uphold.com/rest-apis/core-api/external-accounts/get-external-account-verification.md) or [List external account verifications](https://developer.uphold.com/rest-apis/core-api/external-accounts/list-external-account-verifications.md), or read the `verifications` summary on the external account itself.

See [Address book overview](https://developer.uphold.com/developer-guides/travel-rule/address-book/overview.md) for a full walkthrough.

## Related guides

> [card] [Bank Deposit](https://developer.uphold.com/developer-guides/bank-transfers/deposit/via-rest-api)
>
> Fund an account via bank transfer.

> [card] [Bank Withdrawal](https://developer.uphold.com/developer-guides/bank-transfers/withdrawal/via-rest-api)
>
> Payout to a bank via quote-based transfers.

> [card] [Card Deposit](https://developer.uphold.com/developer-guides/card-transfers/deposit/via-rest-api.md)
>
> Fund an account from a credit or debit card.

> [card] [Card Withdrawal](https://developer.uphold.com/developer-guides/card-transfers/withdrawal/via-rest-api.md)
>
> Cash out to a credit or debit card.

> [card] [APM Deposit](https://developer.uphold.com/developer-guides/apm-transfers/deposit/via-rest-api/paypal.md)
>
> Fund an account from an alternative payment method.

> [card] [APM Withdrawal](https://developer.uphold.com/developer-guides/apm-transfers/withdrawal/via-rest-api/paypal.md)
>
> Pay out to an alternative payment method.

> [card] [Address book](https://developer.uphold.com/developer-guides/travel-rule/address-book/overview.md)
>
> Verify ownership of an address saved in the crypto address book.

## Managed UI option

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

Linking a card through the API sends the full card number and security code through your systems, which requires PCI DSS compliance. If your organization isn't compliant, link cards through the Payment Widget.

## Metadata

External accounts support [metadata](https://developer.uphold.com/rest-apis/entity-metadata.md), so you can attach your own data to an external account, such as the id of the card or bank account in your system, and map it to the records of your own system.

Send `metadata` when you [create the external account](https://developer.uphold.com/rest-apis/core-api/external-accounts/create-external-account.md), or manage it later with the [metadata endpoints](https://developer.uphold.com/rest-apis/core-api/metadata/set-metadata.md), using `external-accounts` as the entity.

| Operation | Scope |
| - | - |
| [Get metadata](https://developer.uphold.com/rest-apis/core-api/metadata/get-metadata.md) | `core.external-accounts.metadata:read` |
| [Set metadata](https://developer.uphold.com/rest-apis/core-api/metadata/set-metadata.md), [Update metadata](https://developer.uphold.com/rest-apis/core-api/metadata/update-metadata.md), [Delete metadata](https://developer.uphold.com/rest-apis/core-api/metadata/delete-metadata.md) | `core.external-accounts.metadata:write` |
| [Create external account](https://developer.uphold.com/rest-apis/core-api/external-accounts/create-external-account.md) with `metadata` | `core.external-accounts.metadata:write`, in addition to `core.external-accounts:create` |

Without the write scope, a create request that includes `metadata` is rejected with `token_insufficient_scopes`, and the external account is not created.

## Testing

To test card external accounts in the Sandbox environment, use the [Test Cards](https://developer.uphold.com/rest-apis/core-api/accounts/test-helpers/fund-sandbox-accounts.md#card-deposit-using-test-cards) reference, which lists available test card numbers and reserved amounts to simulate specific error scenarios.
