Managing Virtual Accounts

Partial, Delayed, or Missing Deposits

Deposit Processing:

• HIFI automatically validates deposits, confirms amount and sender details

• Processing times vary by payment rail:

  • ACH: 1-3 business days

  • Wire: Same day

  • RTP: Real-time

Status Progression:

1. FIAT_PENDING → Waiting for fiat to settle

2. CRYPTO_PENDING → Converting and sending crypto

3. COMPLETED → Stablecoins delivered

Important: Ensure the beneficiary name matches the account holder name, or the payment may be rejected.

Refunds and Reversals

When deposits fail, HIFI handles refunds automatically:

You can also deactivate a virtual account to temporarily prevent new deposits—existing pending deposits continue processing, and the account can be reactivated later.

Deactivating (Closing) a Virtual Account

Use the Deactivate Virtual Account endpoint to temporarily disable an account:

When deactivated:

• New deposits are rejected

• Existing pending deposits continue processing

• Account can be reactivated later

Reactivating a Virtual Account

If you need to re-enable a deactivated account, use the Reactivate Virtual Account endpoint to restore it.

Replacing a Virtual Account

To replace a virtual account:

1. Deactivate the old account

2. Create a new virtual account with updated settings (e.g., different destination chain or currency)

You can also use the Update Virtual Account endpoint to modify an existing account's settings without creating a new one.

Note: Virtual accounts are billable, so consider updating rather than creating new accounts when possible.

Settlement Rules

Settlement rules define how fees are calculated and distributed when processing onramp transactions on virtual accounts. They allow you to create a fee structure that gets applied to specific virtual accounts.

Key operations:

• Create a new settlement rule

• Apply a rule to a virtual account to enable its fee structure

• Remove a rule from a virtual account to disable fees

• Retrieve, list, update, or delete existing rules

Note: Settlement rules are for virtual account onramps. For offramp transaction fees, use Developer Fees instead.

Developer Rules

Developer Fees enable automated fee calculation and distribution for offramp transactions. Fees are added on top of the offramp amount and credited to beneficiary wallets in stablecoin.

Fee Models:

• Percentage: Fee based on the offramp amount (e.g., "0.002" = 0.2%)

• Flat: Fixed amount regardless of transaction size (e.g., "5" = 5 USDC)

How it works:

1. Include developerFee when creating an offramp

2. Fees are automatically calculated and deducted from the source wallet

3. After settlement, fees are credited to specified beneficiary wallets (up to 10)

Example: 100 USDC offramp + 0.2% + $5 flat fee = 105.2 USDC debited from source wallet.

Note: Developer fees are currently supported for USD offramps only. For virtual account onramp fees, use Settlement Rules.