Create and use virtual accounts
Create a virtual account linked to a customer for deposits, conversions, and transactions
Flow 1 - Deposit, store balance, and transact later
Create Virtual Account
Begin by creating a virtual account for your customer. For this example, we'll assume an Individual.
Example POST /payments/internal_accounts request:
{
"participant_code": "CUST01",
"currency": "USD",
"account_type": "virtual_account"
}
Response:
{
"participant_code": "CUST01",
"currency": "USD",
"account_type": "virtual_account",
"status": "approved",
"internal_account_id": "6f2e3b40-4d9c-11ee-be56-0242ac120002",
"account_number": "9876543210",
"routing_number": "021000021"
}
Notes:
- You'll receive an
internal_account_status_changedwebhook if the request is successful. - zerohash will reject any requests where the
participant_codeis not in anapprovedstate. - The
internal_account_idhas been created, uniquely identifying the account in the zerohash system. This ID will be used in subsequent API calls to move money. - The
account_numberandrouting_numberfields represent the true bank account that has been created on the back-end
Deposit
When funds arrive at the virtual account, you'll receive an account_balance.changed webhook message, letting you know that the account has been credited.
The Individual can now hold funds in this account for as long as they want.
Connect External Account
To prepare to convert fiat to stablecoins and withdraw externally, you should connect an external account to the Individual via the POST /payments/external_accounts endpoint. Example request:
{
"participant_code": "CUST01",
"type": "crypto",
"details": {
"network": "SOL",
"supported_assets": ["USDC"],
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
}
Response:
{
"request_id": "a9e2c6fb-f738-4ecb-986c-befd70678707",
"external_account_id": "107e8a2a-c835-4b76-b49d-a633d45727b9",
"participant_code": "CUST01",
"platform_code": "PLAT01",
"account_nickname": "",
"created_at": "2024-10-11T00:52:21.865Z",
"status": "pending",
"type": "crypto",
"details": {
"network": "SOL",
"supported_assets": [
"USDC"
],
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"destination_tag": ""
}
}
Convert and Withdraw
When the user wants to convert fiat to stablecoins and withdraw externally, they will call the POST /paymentsendpoint. Example request:
Notice that the internal_account_id is specified, letting zerohash know that the source account used to make the conversion should be the virtual account
{
"participant_code": "BENEF1",
"obo_participant": {
"participant_code": "PAYOR1",
"account_group": "PLAT01",
"account_label": "general"
},
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
"asset": "USDC",
"quoted_asset": "USD",
"total": "125.50",
"payment_type": "payout",
"description": "",
"source_account": {
"internal_account_id": "6f2e3b40-4d9c-11ee-be56-0242ac120002"
}
}
Immediately after a successful request, zerohash will immediately convert the USD from the virtual account and disburse the funds to the address associated with the external_account
Flow 2 - Deposit, and automatically convert → disburse
Overview
This flow shows how to create a virtual account linked to a customer that is enabled for automatic fiat-to-stablecoin conversions and disbursements. This simplifies fund management by automating the conversion and payout processes.
Create Virtual Account
Example POST /payments/internal_accounts request:
{
"participant_code": "CUST01",
"currency": "USD",
"account_type": "virtual_account",
"enable_auto_conversion_withdraw": true,
"external_account_id": "2cc93b20-ee43-4877-8cdc-863e61829015",
}
Response:
{
"participant_code": "CUST01",
"currency": "USD",
"account_type": "virtual_account",
"status": "approved",
"internal_account_id": "6f2e3b40-4d9c-11ee-be56-0242ac120002",
"account_number": "9876543210",
"routing_number": "021000021",
"enable_auto_conversion_withdraw": true
}
Setting
enable_auto_conversion_trueto true activates automatic processing, including conversion of incoming USD deposits to stablecoins and scheduled disbursements to linked external accounts.
Deposit
When a deposit arrives, zerohash will automatically and immediately convert the USD to the stablecoin associated with the external_account_id and disburse the funds to the address associated with the external_account
Updated 21 days ago
