Update a virtual account

PATCH

virtual-accounts

{virtual_account_id}

curl --request PATCH \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "markup": {
    "wire_fixed_fee": "2.00",
    "inbound_variable_fee_pct": null
  }
}
'

{
  "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": "2.00",
    "ach_fixed_fee": "0.50"
  },
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-02T09:30:00.000Z",
  "metadata": {}
}

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 change.

Body

application/json

Send markup, metadata, or both.

markup

object

The fees to change on this account, each a decimal string with at most two decimals. A value sets that fee, null removes it, and a fee you leave out keeps its value. Any key not listed here is rejected, and so is an empty object.

Show child attributes

metadata

object

A patch, not a replacement: a key with a value sets it, a key with "" deletes it, and {} clears every key. The limits apply to the result — see Metadata.

Show child attributes

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.

curl --request PATCH \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "markup": {
    "wire_fixed_fee": "2.00",
    "inbound_variable_fee_pct": null
  }
}
'

{
  "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": "2.00",
    "ach_fixed_fee": "0.50"
  },
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-02T09:30:00.000Z",
  "metadata": {}
}

Across the API

Authentication

Versioning

Users

Virtual Accounts

Recipients

Quotations

Payouts

Catalogs

RFIs

Update a virtual account

Authorizations

Headers

Path Parameters

Body

Response