Virtual accounts

Overview

A virtual account is a persistent fiat bank account tied to your client’s Portal wallet. Every deposit auto-converts to crypto and settles onchain, with no per-deposit API call. Use it as a standing on-ramp, in contrast to a one-off payin that quotes and settles a single transfer.

Portal proxies these endpoints to Due and returns Due’s responses verbatim. Example responses below are illustrative; exact fields come from Due and may evolve.

1. Prerequisite: approved KYC

Virtual accounts require a provisioned Due customer with approved KYC. Some channels additionally require endorsements. See KYC onboarding.

2. Discover a channel

GET /channels lists the rails and currencies available to the customer. Pass onlyAvailable=true to filter to channels the customer can use today. Pick the fiat deposit channel (the source, for example sepa / EUR) and the crypto destination rail and currency (for example base-sepolia / USDC).

curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/due/channels?onlyAvailable=true' \
  --header 'Authorization: Bearer [token]'

3. Register the Portal wallet

The virtual account settles crypto to a wallet Due knows about, so register your client’s Portal wallet first. Call POST /wallets with the wallet address.

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/wallets \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "0xc118ad00663be7d0360b56a4e9fbb20530bf4693"
  }'

Example response:

{
  "data": {
    "id": "wlt_123",
    "address": "evm:0xc118ad00663be7d0360b56a4e9fbb20530bf4693",
    "preferences": {
      "selectedNetworks": ["base-sepolia"]
    }
  }
}

The wallet is usable as a destination only once Due binds it to networks, shown as a non-empty preferences.selectedNetworks. Use GET /wallets to list registered wallets and confirm. The returned id (wlt_...) is the virtual account destination in the next step.

4. Create the virtual account

Call POST /virtual-accounts. The fiat side is the deposit channel (schemaIn, currencyIn) and the crypto side is where funds settle (railOut, currencyOut).

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/virtual-accounts \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "destination": "wlt_123",
    "schemaIn": "bank_sepa",
    "currencyIn": "EUR",
    "railOut": "base-sepolia",
    "currencyOut": "USDC",
    "reference": "customer-1234"
  }'

destination: the wlt_... id from step 3. Converted crypto settles here.
schemaIn: the fiat deposit bank schema (for example bank_sepa or bank_us).
currencyIn: the fiat currency accepted for deposits (for example EUR). Optional; if omitted, Due resolves a default and the returned key includes the resolved currency, so always use the returned key for later reads and updates.
railOut / currencyOut: the crypto rail and asset funds convert to.
reference: your own label for the account, also used to build its key.

Example response:

{
  "data": {
    "id": "va_789",
    "key": "wlt_123/bank_sepa/EUR/base-sepolia/USDC/customer-1234",
    "isActive": false,
    "details": null
  }
}

5. Wait for the account to activate

Due provisions the underlying bank account asynchronously (up to about a minute). Subscribe to webhooks to learn when it activates. You can also read the account by its composite key at any time; it is ready once isActive is true and details is populated. The key is destination/schemaIn/currencyIn/railOut/currencyOut/reference.

curl --request GET \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/virtual-accounts/key/wlt_123/bank_sepa/EUR/base-sepolia/USDC/customer-1234 \
  --header 'Authorization: Bearer [token]'

Example response once active:

{
  "data": {
    "id": "va_789",
    "isActive": true,
    "details": {
      "bankName": "Lead Bank",
      "beneficiary": "Due Payments",
      "iban": "DE89370400440532013000",
      "bic": "DEUTDEFF",
      "reference": "customer-1234"
    }
  }
}

Webhooks also notify you when deposits arrive and convert, so you never have to check the account yourself. Acknowledge deliveries quickly with a 2XX, then process events asynchronously.

6. Fund the account

Show the details bank information to your client. Any deposit to that account auto-converts to currencyOut and settles in their Portal wallet. There is no per-deposit API call.

Managing the account

GET /virtual-accounts/list lists the customer’s virtual accounts.
POST /virtual-accounts/key/{key} updates an account by its composite key.

Application fees are enforced by the custodian’s Portal Dashboard configuration and injected server-side. Any applicationFeeBps or applicationFeeAmount you send is stripped, so clients cannot override them. See Application fees.

​Overview

​1. Prerequisite: approved KYC

​2. Discover a channel

​3. Register the Portal wallet

​4. Create the virtual account

​5. Wait for the account to activate

​6. Fund the account

​Managing the account

​Next steps

Overview

1. Prerequisite: approved KYC

2. Discover a channel

3. Register the Portal wallet

4. Create the virtual account

5. Wait for the account to activate

6. Fund the account

Managing the account

Next steps