Reference accounts

To be able to withdraw cash from a user account’s cash balance, a reference bank account must be registered with the Investment API. This guide lines out how to register and manage bank reference accounts for a user on the Investment API.

How reference bank accounts work

A reference bank account is an account at a bank other than Upvest. This account serves as a destination for cash withdrawals from the user’s available cash balance at their Upvest account. Currently, we allow registering Euro SEPA (Single European Payments Area) bank accounts only. The reference account owner must match the user on the Investment API.

Registering a reference bank account

Prerequisites

You can register a reference bank account as soon as you have created a user. The registration of a reference bank account is required to complete the onboarding process and therefore to activate the account.

To register a reference bank account, we require you to provide:

• Bank account owner name which matches the name of the user on the Investment API
• IBAN (International Bank Account Number) of the account
• BIC (Bank Identifier Code) of the account
• A timestamp of the confirmation of your user to register the reference bank account

Other optional fields are available to assign a name to the reference bank account that is more human readable.

Once the required information is collected and validated, you register the bank account with POST /payments/reference_accounts.

Example request

{
  "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202",
  "account_owner": "Max Mustermann",
  "name": "Max's Reference Account",
  "iban": "DE02100500000054540402",
  "bic": "BELADEBE",
  "confirmed_at": "2020-08-23T14:15:22Z"
}

Managing reference bank accounts

If you want to retrieve, update or delete your reference bank account we allow the following actions via the Investment API:

• List reference bank accounts registered with a specific user by requesting GET /users/{user_id}/payments/reference_accounts
• Retrieve reference bank account information by requesting GET /payments/reference_accounts/{reference_account_id}
• You can delete a reference bank account by requesting DELETE /payments/reference_accounts/{reference_account_id}. You can only delete a reference bank account if there are at least two reference bank accounts registered with a given user.

To exchange a reference bank account we require you to register the new reference bank account first, before you delete an outdated reference bank account.

Next steps

Now you are all set to trigger a cash balance withdrawal.