Virtual accounts

A virtual account is an account that a partner bank opens for a client to receive bank transfers. Request one with POST /dapi/v1/banks and a product.

Term	Meaning
product	The region you request, such as `eu` or `us`. The key of `POST /dapi/v1/banks`.
rail	The bank route HEVN picks for the product. Returned as `rail`, an opaque value.
virtual account	The `bnk_…` record. On a named rail the partner bank opens it in the client’s legal name.
account details	What the payer needs: IBAN, account and routing number, or PIX key. Returned as `requisites`.

The partner bank converts each incoming payment and delivers the settlement token to the client’s Base smart wallet, or to the account named in accountId. Routes here take X-Hevn-Account. Without it they act on your integrator account. See Acting as a client.

Request a virtual account

Call POST /dapi/v1/banks with one product. Responses and refusals are in Request a receiving account.

curl -X POST "$HEVN_API/banks" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"product":"eu"}'

client = hevn.acting_as(CLIENT_ID)

bank = client.post("/banks", {"product": "eu"})
for blocker in bank.get("blockers", []):
    print(blocker["code"], blocker["message"])

const client = hevn.actingAs(clientId);

const bank = await client.post("/banks", { product: "eu" });
for (const blocker of bank.blockers ?? []) console.log(blocker.code, blocker.message);

client := api.ActingAs(clientID)

bank, err := client.Post("/banks", hevn.Body{"product": "eu"})
for _, blocker := range bank.List("blockers") {
	fmt.Println(blocker.Str("code"), blocker.Str("message"))
}

Statuses

`status`	Meaning	Next
`preparing`	Waiting on a blocker, under review, or approved with no account details yet.	Clear `blockers[]` and poll `GET /dapi/v1/banks/{product}`.
`active`	Account details are published. The only payable status.	Give the account details to the payer.
`suspended`	Paused by the partner bank. Payments in flight settle. No new payment starts.	Poll.
`closed`	Refused or closed. Terminal.	n/a

In production the partner bank opens the account after a review and sets the timing. The sandbox has no review.

Deliver to an account

Send accountId, the acc_… id of an external account or a sub account, to open a virtual account that delivers to that account’s address. Without it the virtual account delivers to the Base smart wallet.

curl -X POST "$HEVN_API/banks" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"product":"us","accountId":"acc_5Jd8Qw2LmX"}'

bank = client.post("/banks", {"product": "us", "accountId": "acc_5Jd8Qw2LmX"})

const bank = await client.post("/banks", { product: "us", accountId: "acc_5Jd8Qw2LmX" });

bank, err := client.Post("/banks", hevn.Body{"product": "us", "accountId": "acc_5Jd8Qw2LmX"})

Response 201, Location: /dapi/v1/banks/us?accountId=acc_5Jd8Qw2LmX

{ "product": "us", "opened": true, "status": "preparing", "accountId": "acc_5Jd8Qw2LmX", "…": "…" }

Rule	Detail
Key	One virtual account per account and product. A repeat returns `200` with `Idempotency-Replayed: true`.
Read	`GET /dapi/v1/banks/{product}?accountId=acc_…`. Without the query the route reads the main wallet’s virtual account.
List	`GET /dapi/v1/banks` returns these records next to the main wallet’s. Each has `accountId`.
Token	The partner bank delivers the token the account holds, on the account’s network.
Products	Those with a rail that settles that token on chain to the address. Another product returns `409 account_destination_unsupported` on `POST` and `403 rail_not_available` on `GET`.
Destination	Fixed. A virtual account keeps the address it was opened for.

The rules of each kind are on External wallets and Sub accounts.

List products

Call GET /dapi/v1/banks to read each product the client can request, or GET /dapi/v1/banks/{product} for one.

curl "$HEVN_API/banks" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID"

catalogue = client.get("/banks")

const catalogue = await client.get("/banks");

catalogue, err := client.Get("/banks")

{
  "rails": [
    {
      "product": "eu",
      "rail": "sepa-eur-usdc-kappa",
      "currency": "EUR",
      "railCurrency": "USDC",
      "method": "sepa",
      "opened": false,
      "feeBps": 100,
      "supportedAccounts": ["USDC"]
    }
  ]
}

Fields are in List virtual accounts. Products are listed in the rail reference, and fees in Fees.

What still blocks it

{
  "status": "preparing",
  "…": "…",
  "blockers": [
    {
      "code": "kyb_required",
      "field": "kyb",
      "message": "The client's business verification has to be completed before this account can open."
    }
  ]
}

`code`	Cleared by
`kyb_required`	A business client’s KYB application reaching `approved`. See Write the document.
`verification_required`	A linked individual verifying their identity in a `verify` session.
`terms_required`	The client accepting the partner bank’s terms at `url`.

url is absent on verification_required for a linked individual.

Account details

{
  "product": "eu",
  "opened": true,
  "status": "active",
  "id": "bnk_88Hq3T",
  "destinationAccount": "USDC",
  "minimumDeposit": "1.00",
  "…": "…",
  "requisites": {
    "fields": { "iban": "DE89370400440532013000", "bic": "BANKDEFFXXX" },
    "holder": { "type": "business", "businessName": "Northwind Trading Ltd" },
    "bankName": "Example Bank",
    "state": "active"
  }
}

fields has the identifiers the method uses, listed per method in the rail reference. ContactPaymentAccountView on a contact has the same fields, holder and bankName as RailRequisitesView here. Give the payer fields, the holder name, bankName and any paymentReference. Field rules are in Retrieve one virtual account.

When paymentReference is set, a payment without it cannot be attributed to the client.

Start here

Core concepts

Clients

Move money

Ship it

Reference

Changelog

Virtual accounts

Request a virtual account

Statuses

Deliver to an account

List products

What still blocks it

Account details

Next: Payins