Skip to main content

Managing Virtual Accounts

Overview​

A virtual account is a set of bank payment methods (IBAN, ACH routing details) assigned to one of your customers so they can fund fiat-to-crypto conversions, as described in the Payin via Virtual Account product and the Bank Onramp recipes.

Once created, virtual accounts can be listed and, when no longer needed, closed. This page covers both operations.

List Virtual Accounts​

Use the GET /virtual-accounts endpoint to retrieve a customer's virtual accounts. Each item includes the virtual account Status and the payment methods linked to it.

curl -L 'https://api.sandbox.noah.com/v1/virtual-accounts?CustomerID=321434324' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>'
{
  "Items": [
    {
      "VirtualAccountID": "b1f2c3d4e5",
      "Status": "Active",
      "PaymentMethods": [
        {
          "ID": "Bank/Ach/USD/000000000/000000000000/000000000",
          "CustomerID": "321434324",
          "Country": "US",
          "PaymentMethodCategory": "Bank",
          "DisplayDetails": {
            "Type": "FiatPaymentMethodBankDisplay",
            "AccountNumber": "000000000000",
            "RoutingNumber": "000000000",
            "BankName": "BANKING CIRCLE USA"
          }
        }
      ]
    }
  ]
}

A virtual account has one of three statuses:

StatusMeaning
ActiveAccount is open and can receive deposits
PendingClosureClosure requested and in progress
ClosedAccount is closed
tip

Fetch banking details from this endpoint each time you display them, rather than caching stale values.

Close a Virtual Account​

Use the POST /virtual-accounts/{VirtualAccountID}/close endpoint to close a virtual account you no longer need.

curl -L -X POST 'https://api.sandbox.noah.com/v1/virtual-accounts/b1f2c3d4e5/close' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>'

The response returns the current status of the account:

{
  "VirtualAccountID": "b1f2c3d4e5",
  "Status": "PendingClosure"
}
ResponseStatusMeaning
202 AcceptedPendingClosureClosure has been requested or is already in progress
200 OKClosedAccount was already closed (safe to call more than once)

What closing does​

  • Closes all associated payment methods. Every IBAN or ACH detail linked to the virtual account is deactivated and can no longer receive deposits.
  • Stops active-account charges. Once closure is complete, this virtual account will no longer count as active for billing purposes. Please refer to your contract terms for the exact conditions and implications.
warning

Closing a virtual account is irreversible. The account and its payment methods cannot be reopened — if the customer needs a virtual account again, you must create a new one, which will have different banking details.

When to close a virtual account​

Common reasons to close a virtual account include:

  • The customer has offboarded or closed their relationship with you.
  • The account is no longer used and you want to avoid any future account charges included in your pricing.
  • Compliance or risk action requires removing the customer's ability to receive deposits.
  • You are cleaning up test or duplicate accounts that are no longer needed.

Further Reading​