OpenAPI Specification
openapi: 3.0.0
info:
title: Hifi Account Virtual Account API
version: 2.0.0
description: API documentation for Hifi
servers:
- url: https://production.hifibridge.com
description: Production server
- url: https://sandbox.hifibridge.com
description: Sandbox server
security:
- bearerAuth: []
tags:
- name: Virtual Account
description: Virtual Account endpoints
paths:
/v2/users/{userId}/virtual-accounts:
post:
summary: Create a virtual account
description: 'Generate a virtual bank account to onramp from `sourceCurrency` to `destinationCurrency` on chain `destinationChain`. (note: virtual accounts are billable)
'
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/CreateVirtualAccountBody'
responses:
'200':
$ref: '#/components/responses/CreateVirtualAccountResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
get:
summary: List all virtual accounts
description: List all virtual accounts associated with a user under your organization.
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/VASourceCurrencyParameter'
- $ref: '#/components/parameters/VADestinationCurrencyParameter'
- $ref: '#/components/parameters/VADestinationChainParameter'
- $ref: '#/components/parameters/LimitParameter'
- $ref: '#/components/parameters/CreatedBeforeParameter'
- $ref: '#/components/parameters/CreatedAfterParameter'
responses:
'200':
$ref: '#/components/responses/GetAllVirtualAccountsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/virtual-accounts/{accountId}:
get:
summary: Retrieve a virtual account
description: Get an existing virtual bank account detail.
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/VirtualAccountIdPathParameter'
- $ref: '#/components/parameters/VALimitParameter'
- $ref: '#/components/parameters/VACreatedBeforeParameter'
- $ref: '#/components/parameters/VACreatedAfterParameter'
responses:
'200':
$ref: '#/components/responses/GetVirtualAccountResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/virtual-accounts/{accountId}/update:
post:
summary: Update a virtual account
description: 'Update an existing virtual account.
'
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/VirtualAccountIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/UpdateVirtualAccountBody'
responses:
'200':
$ref: '#/components/responses/UpdateVirtualAccountResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/virtual-accounts/{accountId}/deactivate:
post:
summary: Deactivate a virtual account
description: Deactivate an existing virtual account.
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/VirtualAccountIdPathParameter'
responses:
'200':
$ref: '#/components/responses/DeactivateVirtualAccountResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/virtual-accounts/{accountId}/reactivate:
post:
summary: Reactivate a virtual account
description: Reactivate an existing virtual account.
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/VirtualAccountIdPathParameter'
responses:
'200':
$ref: '#/components/responses/ReactivateVirtualAccountResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/virtual-accounts/{accountId}/simulate-deposit:
post:
summary: Simulate a deposit to a virtual account
description: 'Simulate a deposit to a virtual account in sandbox environment. This endpoint is only available in sandbox and allows testing deposit flows.
**Note:** This endpoint is only available in sandbox environment.
'
tags:
- Virtual Account
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/VirtualAccountIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/SimulateVirtualAccountDepositBody'
responses:
'200':
$ref: '#/components/responses/SimulateVirtualAccountDepositResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
components:
responses:
DeactivateVirtualAccountResponse:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DeactivateVirtualAccountObject'
examples:
VirtualAccountObjectDeactivateExample:
$ref: '#/components/examples/VirtualAccountObjectDeactivateExample'
CreateVirtualAccountResponse:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVirtualAccountObject'
examples:
VirtualAccountObjectCreationExample:
$ref: '#/components/examples/VirtualAccountObjectCreationExample'
GetVirtualAccountResponse:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualAccountObject'
examples:
VirtualAccountObjectExample:
$ref: '#/components/examples/VirtualAccountObjectExample'
SimulateVirtualAccountDepositResponse:
description: Successfully triggered sandbox deposit
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateVirtualAccountDeposit'
examples:
VirtualAccountDepositSimulationObjectExample:
$ref: '#/components/examples/VirtualAccountDepositSimulationObjectExample'
InternalServerErrorResponse:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
NotFoundResponse:
description: Resource not found
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: object
properties:
code:
type: string
message:
type: string
ReactivateVirtualAccountResponse:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ReactivateVirtualAccountObject'
examples:
VirtualAccountObjectCreationExample:
$ref: '#/components/examples/VirtualAccountObjectCreationExample'
UnauthorizedResponse:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
UpdateVirtualAccountResponse:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateVirtualAccountObject'
GetAllVirtualAccountsResponse:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualAccountListObject'
examples:
VirtualAccountObjectListExample:
$ref: '#/components/examples/VirtualAccountObjectListExample'
examples:
VirtualAccountDepositSimulationObjectExample:
summary: Virtual Account Deposit Simulation Object
value:
amount: '88.8'
paymentRail: WIRE
requestId: 550e8400-e29b-41d4-a716-446655440000
source:
routingNumber: '021000021'
accountNumber: '123456789'
name: Henry Wu
bankName: Bank of NoWhere
userId: 840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d
reference: Test deposit
description: Simulated test deposit
VirtualAccountObjectExample:
summary: Virtual Account Object
value:
id: cfbc005d-8640-57a4-89e1-539c974fa780
createdAt: '2025-09-27T03:08:11.548Z'
updatedAt: '2025-09-27T03:08:11.548Z'
userId: 840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d
source:
paymentRail:
- ach
- wire
- rtp
currency: usd
destination:
chain: POLYGON
currency: usdc
walletAddress: '0xd102C4130985B7fcB95697616eaf5542c4f98d49'
externalWalletId: null
status: activated
depositInstructions:
bankName: Bank of NoWhere
bankAddress: 123 Main St, New York, NY 10001, USA
beneficiary:
name: Henry Wu
address: Example St 1., Apt 123, New York, NY, 10010, US
ach:
routingNumber: 028000024
accountNumber: '123456789'
wire:
routingNumber: '021000021'
accountNumber: '123456789'
rtp:
routingNumber: '021000021'
accountNumber: '123456789'
instruction: Please deposit usd to the bank account provided. Please ensure that the beneficiary name matches the account holder name provided, or the payment may be rejected.
settlementRuleId: null
VirtualAccountObjectListExample:
summary: Virtual Account Object List
value:
count: 1
data:
- id: cfbc005d-8640-57a4-89e1-539c974fa780
createdAt: '2025-09-27T03:08:11.548Z'
updatedAt: '2025-09-27T03:08:11.548Z'
userId: 840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d
source:
paymentRail:
- ach
- wire
- rtp
currency: usd
destination:
chain: POLYGON
currency: usdc
walletAddress: '0xd102C4130985B7fcB95697616eaf5542c4f98d49'
externalWalletId: null
status: activated
depositInstructions:
bankName: Bank of NoWhere
bankAddress: 123 Main St, New York, NY 10001, USA
beneficiary:
name: Henry Wu
address: Example St 1., Apt 123, New York, NY, 10010, US
ach:
routingNumber: 028000024
accountNumber: '123456789'
wire:
routingNumber: '021000021'
accountNumber: '123456789'
rtp:
routingNumber: '021000021'
accountNumber: '123456789'
instruction: Please deposit usd to the bank account provided. Please ensure that the beneficiary name matches the account holder name provided, or the payment may be rejected.
settlementRuleId: null
nextCursor: '2025-09-27T03:08:11.548Z'
VirtualAccountObjectDeactivateExample:
summary: Virtual Account Object (Deactivation)
value:
message: Virtual account deactivated
accountInfo:
id: cfbc005d-8640-57a4-89e1-539c974fa780
createdAt: '2025-09-27T03:08:11.548Z'
updatedAt: '2025-09-27T03:08:11.548Z'
userId: 840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d
source:
paymentRail:
- ach
- wire
- rtp
currency: usd
destination:
chain: POLYGON
currency: usdc
walletAddress: '0xd102C4130985B7fcB95697616eaf5542c4f98d49'
externalWalletId: null
status: deactivated
depositInstructions:
bankName: Bank of NoWhere
bankAddress: 123 Main St, New York, NY 10001, USA
beneficiary:
name: Henry Wu
address: Example St 1., Apt 123, New York, NY, 10010, US
ach:
routingNumber: 028000024
accountNumber: '123456789'
wire:
routingNumber: '021000021'
accountNumber: '123456789'
rtp:
routingNumber: '021000021'
accountNumber: '123456789'
instruction: Please deposit usd to the bank account provided. Please ensure that the beneficiary name matches the account holder name provided, or the payment may be rejected.
settlementRuleId: null
VirtualAccountObjectCreationExample:
summary: Virtual Account Object (Creation)
value:
message: Virtual account created successfully
accountInfo:
id: cfbc005d-8640-57a4-89e1-539c974fa780
createdAt: '2025-09-27T03:08:11.548Z'
updatedAt: '2025-09-27T03:08:11.548Z'
userId: 840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d
source:
paymentRail:
- ach
- wire
- rtp
currency: usd
destination:
chain: POLYGON
currency: usdc
walletAddress: '0xd102C4130985B7fcB95697616eaf5542c4f98d49'
externalWalletId: null
status: activated
depositInstructions:
bankName: Bank of NoWhere
bankAddress: 123 Main St, New York, NY 10001, USA
beneficiary:
name: Henry Wu
address: Example St 1., Apt 123, New York, NY, 10010, US
ach:
routingNumber: 028000024
accountNumber: '123456789'
wire:
routingNumber: '021000021'
accountNumber: '123456789'
rtp:
routingNumber: '021000021'
accountNumber: '123456789'
instruction: Please deposit usd to the bank account provided. Please ensure that the beneficiary name matches the account holder name provided, or the payment may be rejected.
settlementRuleId: null
schemas:
ReactivateVirtualAccountObject:
type: object
properties:
message:
type: string
accountInfo:
$ref: '#/components/schemas/VirtualAccountObject'
UpdateVirtualAccount:
type: object
title: Update Virtual Account
properties:
sourceCurrency:
type: string
enum:
- usd
destinationCurrency:
type: string
enum:
- usdc
- usdt
description: 'usdt is only supported on ethereum
'
destinationChain:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
description: 'Either `externalWalletId` or `destinationChain` must be provided.
'
externalWalletId:
type: string
description: 'Either `externalWalletId` or `destinationChain` must be provided.
'
required:
- sourceCurrency
- destinationCurrency
InternalServerError:
type: object
properties:
error:
type: string
example: Unexpected error happened
CreateVirtualAccountObject:
type: object
properties:
message:
type: string
accountInfo:
$ref: '#/components/schemas/VirtualAccountObject'
VirtualAccountListObject:
type: object
properties:
count:
type: integer
description: Number of virtual accounts.
data:
type: array
items:
$ref: '#/components/schemas/VirtualAccountObject'
nextCursor:
type: string
description: The `createdAt` timestamp of the last record in the current page. Pass this as `createdBefore` in the next request to retrieve the next page of results.
DeactivateVirtualAccountObject:
type: object
properties:
message:
type: string
accountInfo:
$ref: '#/components/schemas/VirtualAccountObject'
VirtualAccountObject:
type: object
properties:
id:
type: string
format: uuid
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
userId:
type: string
format: uuid
source:
type: object
properties:
paymentRail:
type: array
items:
type: string
currency:
type: string
destination:
type: object
properties:
chain:
type: string
currency:
type: string
walletAddress:
type: string
externalWalletId:
type: string
status:
type: string
enum:
- activated
- deactivated
microDeposits:
type: object
properties:
count:
type: integer
data:
type: array
items:
type: object
properties:
createdAt:
type: string
format: date-time
currency:
type: string
amount:
type: integer
sourceBankInfo:
$ref: '#/components/schemas/InboundObject'
depositInstructions:
type: object
properties:
bankName:
type: string
bankAddress:
type: string
swiftCode:
type: string
beneficiary:
type: object
properties:
name:
type: string
address:
type: string
ach:
type: object
properties:
routingNumber:
type: string
accountNumber:
type: string
wire:
type: object
properties:
routingNumber:
type: string
accountNumber:
type: string
rtp:
type: object
properties:
routingNumber:
type: string
accountNumber:
type: string
reference:
type: string
depositBy:
type: string
format: date-time
instruction:
type: string
settlementRuleId:
type: string
format: uuid
CreateVirtualAccount:
type: object
title: Create Virtual Account
properties:
sourceCurrency:
type: string
enum:
- usd
destinationCurrency:
type: string
enum:
- usdc
- usdt
description: 'usdt is only supported on ethereum
'
destinationChain:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
description: 'Either `externalWalletId` or `destinationChain` must be provided.
'
externalWalletId:
type: string
description: 'Either `externalWalletId` or `destinationChain` must be provided.
'
required:
- sourceCurrency
- destinationCurrency
InboundObject:
type: object
properties:
bankName:
type: string
senderName:
type: string
routingNumber:
type: string
accountNumber:
type: string
accountType:
type: string
fedBatchId:
type: string
imad:
type: string
omad:
type: string
traceNumber:
type: string
bankAddress:
type: string
description:
type: string
paymentRail:
type: string
enum:
- ach
- wire
- rtp
UpdateVirtualAccountObject:
type: object
properties:
message:
type: string
accountInfo:
$ref: '#/components/schemas/VirtualAccountObject'
Unauthorized:
type: object
properties:
error:
type: string
example: Not authorized
SimulateVirtualAccountDeposit:
type: object
title: Simulate Virtual Account Deposit
properties:
amount:
type: string
description: Amount to simulate deposit
paymentRail:
type: string
enum:
- WIRE
- ACH
description: Payment rail for the simulated deposit , recommended to use WIRE for faster settlement
requestId:
type: string
description: Unique identifier for the request (recommend using uuid v4)
source:
type: object
required:
- routingNumber
- accountNumber
- name
- bankName
properties:
routingNumber:
type: string
description: Routing number of the source bank account
accountNumber:
type: string
description: Account number of the source bank account
name:
type: string
description: Name on the source bank account
bankName:
type: string
description: Name of the source bank
userId:
type: string
description: Optional user ID to associate with this deposit
reference:
type: string
description: Optional reference for this deposit
description:
type: string
description: Optional description for this deposit
required:
- amount
- paymentRail
- requestId
- source
parameters:
LimitParameter:
name: limit
in: query
schema:
type: string
minimum: 1
maximum: 100
description: default to 10, maximum to 100
required: false
VASourceCurrencyParameter:
name: sourceCurrency
in: query
schema:
type: string
enum:
- usd
description: Source currency
required: false
VADestinationCurrencyParameter:
name: destinationCurrency
in: query
schema:
type: string
enum:
- usdc
- usdt
description: Destination currency
required: false
VACreatedBeforeParameter:
name: createdBefore
in: query
schema:
type: string
description: Return the micro deposit records that created before this eventId
required: false
CreatedBeforeParameter:
name: createdBefore
in: query
schema:
type: string
format: date
description: 'ISO format: YYYY-MM-DD'
required: false
UserIdPathParameter:
name: userId
in: path
schema:
type: string
description: ID of the user
required: true
VACreatedAfterParameter:
name: createdAfter
in: query
schema:
type: string
description: Return the micro deposit records that created after this eventId
required: false
VirtualAccountIdPathParameter:
name: accountId
in: path
schema:
type: string
description: ID of the virtual account
required: true
CreatedAfterParameter:
name: createdAfter
in: query
schema:
type: string
format: date
description: 'ISO format: YYYY-MM-DD'
required: false
VADestinationChainParameter:
name: destinationChain
in: query
schema:
type: string
enum:
- POLYGON
description: Destination chain
required: false
VALimitParameter:
name: limit
in: query
schema:
type: string
minimum: 1
maximum: 100
description: Number of micro deposit records return for the virtual account, default to 10 maximum to 100
required: false
requestBodies:
UpdateVirtualAccountBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateVirtualAccount'
CreateVirtualAccountBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVirtualAccount'
SimulateVirtualAccountDepositBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateVirtualAccountDeposit'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT