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:
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, 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.
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 flow.
External accounts of type crypto represent cryptocurrency addresses manually registered by the user for crypto withdrawals only.

​
When to use external accounts

  • Bank push deposits: A bank external account represents the user’s originating bank account and is used to identify them in recurring transactions — via API or 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 or 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 or via Payment Widget.
  • Card withdrawals: A card external account is linked by the user and used as the destination of a quote — via API or via Payment Widget.
  • 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 or 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 or 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.

​
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 endpoint, then resolve it by submitting the collected answers.
  • verified: Cryptographic proof of address ownership through message signing or a Satoshi test. This level isn’t initiated through the external account verifications endpoint — it’s achieved when the address is verified during a crypto deposit or withdrawal, and the resulting verification is then also reflected here.
Check the status of either level with Get external account verification or List external account verifications, or read the verifications summary on the external account itself. See Address Book overview for a full walkthrough.

Bank Deposit

Fund an account via bank transfer.

Bank Withdrawal

Payout to a bank via quote-based transfers.

Card Deposit

Fund an account from a credit or debit card.

Card Withdrawal

Cash out to a credit or debit card.

APM Deposit

Fund an account from an alternative payment method.

APM Withdrawal

Pay out to an alternative payment method.

Address Book

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 (select-for-deposit / select-for-withdrawal) and then consume the returned depositMethod or external-account with the Core API.

​
Testing

To test card external accounts in the Sandbox environment, use the Test Cards reference, which lists available test card numbers and reserved amounts to simulate specific error scenarios.