List Virtual Accounts
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"currency": "<string>",
"status": "<string>",
"label": "<string>",
"balances": {
"available": "<string>",
"pending_payin": "<string>",
"held_for_payout": "<string>",
"total": "<string>"
},
"beneficiary_name": "<string>",
"bank_name": "<string>",
"account_number": "<string>",
"account_number_last4": "<string>",
"iban": "<string>",
"swift_bic": "<string>",
"routing_number": "<string>",
"routing_number_type": "<string>",
"bank_address": {},
"beneficiary_address": {},
"provisioned_at": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Virtual Accounts
List Virtual Accounts
Retrieve a paginated list of the virtual accounts in one virtual account group
GET
/
v1
/
accounts
/
{account_id}
/
virtual-account-groups
/
{group_id}
/
virtual-accounts
List Virtual Accounts
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/virtual-accounts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"currency": "<string>",
"status": "<string>",
"label": "<string>",
"balances": {
"available": "<string>",
"pending_payin": "<string>",
"held_for_payout": "<string>",
"total": "<string>"
},
"beneficiary_name": "<string>",
"bank_name": "<string>",
"account_number": "<string>",
"account_number_last4": "<string>",
"iban": "<string>",
"swift_bic": "<string>",
"routing_number": "<string>",
"routing_number_type": "<string>",
"bank_address": {},
"beneficiary_address": {},
"provisioned_at": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Returns the virtual accounts belonging to one virtual account group, newest first. There are no sort parameters.
List items are the same shape as Get Virtual Account: every field, including the full bank details, is present on each row. There are no
status or currency filters, so a group with several currencies returns them all and you filter client-side. Virtual accounts in another group on the same account are not included: list each group separately.
Requires an API key with read access on the virtual_accounts scope.
There is no disable or delete endpoint for virtual accounts on this API. A virtual account cannot be closed, frozen or renamed through the client API. frozen and disabled are set by Hop, so a virtual account you created stays in this list for the life of the account. Set a durable label when you create the virtual account: neither the label nor the account can be changed afterwards.
Path Parameters
string
required
The account’s external ID (starts with
acct_)string
required
The virtual account group’s external ID (starts with
vag_). An unknown group, or one belonging to another account, returns 404, not an empty page.Query Parameters
integer
default:"1"
Page number (minimum 1)
integer
default:"10"
Items per page (1-100)
Response
array
Virtual account objects, newest first
Show Virtual Account Fields
Show Virtual Account Fields
string
Virtual account identifier (starts with
va_)string
Always returns
"virtual_account"string
Account ID (starts with
acct_). Rows do not repeat group_id. Every item belongs to the group in the path.string
Currency code of the virtual account
string
Virtual account status:
pending, active, frozen or disabled. Only an active virtual account is payable and usable as a payout funding source or transfer leg.string
Label, or
nullobject
string
Account holder a payer should address the deposit to, or
nullstring
Bank holding the account, or
nullstring
Full account number, or
null on a pending row and on accounts identified by IBANstring
Account number masked as
**** + last 4. The IBAN is masked instead when there is no account number. null on a pending row.string
Full IBAN, or
null on a pending row and on accounts identified by account numberstring
SWIFT/BIC code, or
nullstring
Routing number or sort code, or
nullstring
What
routing_number holds, for example ROUTING_NUMBER or SORT_CODE; null when there is no routing numberobject
Bank address for wire instructions (
address_line, city, region, postal_code, country), or nullobject
Account holder address for wire instructions, same shape as
bank_address, or nullstring
ISO 8601 timestamp when the bank details became available, or
null while pendingstring
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the virtual account: the API key id (starts with
ak_) when opened through this API, otherwise the actor Hop recordedstring
Actor that last updated the virtual account, or
nullinteger
Current page number
integer
Items per page
integer
Total number of items
integer
Total number of pages
Errors
| Status | code | When |
|---|---|---|
404 | RESOURCE_NOT_FOUND | group_id is unknown or belongs to another account |
422 | VALIDATION_ERROR | page or size is out of range |
Request Example
curl "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups/vag_8p2m5k9t3w6b1r4n7z0c5v3h/virtual-accounts?size=10" \
-H "X-API-Key: your_api_key" \
-H "X-Signature: hmac_signature" \
-H "X-Timestamp: 1234567890" \
-H "X-Nonce: abc123"
Response Example
{
"items": [
{
"id": "va_6b3n9k1q4t7w2z5m8p0r3d6f",
"object": "virtual_account",
"account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
"currency": "EUR",
"status": "active",
"label": "EU Collections",
"balances": {
"available": "250.00",
"pending_payin": "0.00",
"held_for_payout": "0.00",
"total": "250.00"
},
"beneficiary_name": "Acme GmbH",
"bank_name": "Example Bank",
"account_number": null,
"account_number_last4": "****3000",
"iban": "DE89370400440532013000",
"swift_bic": "DEUTDEFFXXX",
"routing_number": null,
"routing_number_type": null,
"bank_address": {
"address_line": "1 Bank Street",
"city": "Frankfurt",
"region": null,
"postal_code": "60311",
"country": "DE"
},
"beneficiary_address": {
"address_line": "22 Hauptstrasse",
"city": "Berlin",
"region": null,
"postal_code": "10115",
"country": "DE"
},
"provisioned_at": "2026-01-15T10:12:00Z",
"created": "2026-01-15T10:00:00Z",
"updated": "2026-01-15T10:12:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
},
{
"id": "va_2w9e4r7t1y5u8i3o6p0a5s2d",
"object": "virtual_account",
"account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
"currency": "USD",
"status": "pending",
"label": "US Collections",
"balances": {
"available": "0.00",
"pending_payin": "0.00",
"held_for_payout": "0.00",
"total": "0.00"
},
"beneficiary_name": null,
"bank_name": null,
"account_number": null,
"account_number_last4": null,
"iban": null,
"swift_bic": null,
"routing_number": null,
"routing_number_type": null,
"bank_address": null,
"beneficiary_address": null,
"provisioned_at": null,
"created": "2026-01-14T09:00:00Z",
"updated": "2026-01-14T09:00:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
}
],
"page": 1,
"size": 10,
"total": 2,
"pages": 1
}