Get a virtual account

GET

virtual-accounts

{virtual_account_id}

curl --request GET \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}"

headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

fetch('https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}', 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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "11111111-2222-3333-4444-555555555555",
  "user_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "approved",
  "type": "US_BANK",
  "bank": "austin_capital_trust",
  "mode": "fiat",
  "destination": null,
  "source_deposit_instructions": {
    "currency": "usd",
    "bank_name": "Example Bank National Association",
    "bank_address": "1 Second Street South, St. Cloud, MN, 56301",
    "bank_account_number": "1000000001",
    "bank_routing_number": "000000001",
    "bank_beneficiary_name": "Northwind Trading LLC",
    "bank_beneficiary_address": "1 Market Street, San Francisco, CA, 94105"
  },
  "payment_methods": {
    "inbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ],
    "outbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ]
  },
  "methods": {
    "inbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ],
    "outbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ]
  },
  "account_holder_name": "Northwind Trading LLC",
  "account_number": "1000000001",
  "routing_number": "000000001",
  "bank_name": "Example Bank National Association",
  "bank_address": "1 Second Street South, St. Cloud, MN, 56301",
  "account_holder_address": "1 Market Street, San Francisco, CA, 94105",
  "description": "Operating account",
  "markup": {
    "wire_fixed_fee": "1.50",
    "ach_fixed_fee": "0.50",
    "inbound_variable_fee_pct": "0.25"
  },
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:04:00.000Z",
  "metadata": {}
}

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "id",
      "message": "Invalid virtual account ID format",
      "code": "invalid_string"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem."
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Virtual account 11111111-2222-3333-4444-555555555555 not found",
  "timestamp": "2026-09-01T12:00:00.000Z"
}

Authorizations

Authorization

string

header

required

The data.access_token value from Get access token.

x-api-key

string

header

required

API key issued by Kira.

Headers

X-Api-Version

string

Version applied to this request. It wins over your account's pinned version — see Versioning.

Example:

"2026-04-14"

Path Parameters

virtual_account_id

string<uuid>

required

UUID of the account to read.

Response

Success.

One virtual account. The six flat bank fields repeat what source_deposit_instructions holds: absent when it is null, and null where it holds an empty value.

string<uuid>

Virtual account UUID.

user_id

string<uuid>

UUID of the user that owns the account.

status

string

Where the account is in its lifecycle — see Virtual account values. Available options: approved, rfi, declined, deactivated.

type

enum<string>

Account type.

Available options:

US_BANK

bank

string | null

Which bank the account runs on, and with it the rail — see Virtual account values. null while the bank is still opening it.

mode

string

What the account does with a deposit. Available options: fiat, crypto. See Virtual account values.

destination

object | null

Where a crypto-mode deposit is sent. null on a fiat-mode account.

Show child attributes

source_deposit_instructions

object | null

The bank details a payer uses to send money to this account. null until the bank assigns them.

They can also arrive filled with placeholders, such as an account_number of PENDING-ACT-ACCOUNT. Treat them as real only after the virtual_account.activated webhook — see Webhooks.

Show child attributes

payment_methods

object | null

Which rails the account takes money on and pays out on.

Show child attributes

methods

object | null

The same value as payment_methods.

Show child attributes

account_holder_name

string | null

Name the payment must be made out to.

account_number

string | null

Account number the payer sends to.

routing_number

string | null

Routing number the payer sends to.

bank_name

string | null

Name of the bank holding the account.

bank_address

string | null

Postal address of that bank.

account_holder_address

string | null

Postal address of the beneficiary.

description

string

Label you set when you created the account. Absent when you set none.

status_reason

string

Why the account is in its current status, in the bank's own words. Free text — read it, do not parse it. Absent when there is nothing to report.

markup

object

Your fees on this account, each a decimal string. Absent when none are set.

Show child attributes

created_at

string

When the account was created, as an ISO 8601 timestamp.

updated_at

string

When the account last changed, as an ISO 8601 timestamp.

metadata

object

Key/value pairs you attached to the account. {} when you attached none.

Get a virtual account

curl --request GET \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}"

headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

fetch('https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}', 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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "11111111-2222-3333-4444-555555555555",
  "user_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "approved",
  "type": "US_BANK",
  "bank": "austin_capital_trust",
  "mode": "fiat",
  "destination": null,
  "source_deposit_instructions": {
    "currency": "usd",
    "bank_name": "Example Bank National Association",
    "bank_address": "1 Second Street South, St. Cloud, MN, 56301",
    "bank_account_number": "1000000001",
    "bank_routing_number": "000000001",
    "bank_beneficiary_name": "Northwind Trading LLC",
    "bank_beneficiary_address": "1 Market Street, San Francisco, CA, 94105"
  },
  "payment_methods": {
    "inbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ],
    "outbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ]
  },
  "methods": {
    "inbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ],
    "outbound": [
      {
        "name": "WIRE",
        "status": "active"
      },
      {
        "name": "ACH",
        "status": "active"
      }
    ]
  },
  "account_holder_name": "Northwind Trading LLC",
  "account_number": "1000000001",
  "routing_number": "000000001",
  "bank_name": "Example Bank National Association",
  "bank_address": "1 Second Street South, St. Cloud, MN, 56301",
  "account_holder_address": "1 Market Street, San Francisco, CA, 94105",
  "description": "Operating account",
  "markup": {
    "wire_fixed_fee": "1.50",
    "ach_fixed_fee": "0.50",
    "inbound_variable_fee_pct": "0.25"
  },
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:04:00.000Z",
  "metadata": {}
}

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "id",
      "message": "Invalid virtual account ID format",
      "code": "invalid_string"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem."
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Virtual account 11111111-2222-3333-4444-555555555555 not found",
  "timestamp": "2026-09-01T12:00:00.000Z"
}

Across the API

Authentication

Versioning

Users

Virtual Accounts

Recipients

Quotations

Payouts

Catalogs

Get a virtual account

Authorizations

Headers

Path Parameters

Response