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.

Prerequisites

A customer must have completed onboarding and accepted required agreements before you can create a virtual account for them.

Confirm both on GET /customers/{CustomerID} or from Customer webhooks:

Onboarding is complete when Verifications.Status is Approved for the fiat option you are issuing. See Hosted Onboarding.
Agreements are complete when each required row in Agreements has Accepted: true. If OnboardingStatus is AgreementsRequired, terms are still outstanding.

Create the account with the USD or EUR bank onramp workflow.

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:

Status	Meaning
`Active`	Account is open and can receive deposits
`PendingClosure`	Closure requested and in progress
`Closed`	Account 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"
}

Response	Status	Meaning
`202 Accepted`	`PendingClosure`	Closure has been requested or is already in progress
`200 OK`	`Closed`	Account 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.

Overview​

Prerequisites​

List Virtual Accounts​

Close a Virtual Account​

What closing does​

When to close a virtual account​

Further Reading​