API Documentation

Virtual Accounts (BETA-CLOSED)

Suggest Edits

Sila’s Virtual Accounts feature allows customers to open a virtual account for their end users and provide them with an account and routing number that can be used for incoming "external" ACH transactions. "External" means that these ACH transactions are originated from a bank outside of Sila, and we receive those ACH transactions to the virtual account. Those incoming external ACH transactions can be credits or debits.

Endpoints in this section contain methods to manage virtual accounts including opening, updating, closing, etc.

🚧

Incompatible with Virtual Accounts

  • Incoming external WIRE transactions are not supported at this time.
  • Instant Settlement is not supported at this time.

📘

Getting Access Virtual Accounts

Sila needs to ensure you are prepared to support vAccounts for your users. Before contacting your Sila Sales Executive please review and ensure you will be able to meet the following requirements:

Eligibility Requirements:

  • Customer must have at least 3 full-time staff
  • Customer needs to establish and provide Sila hours of operation for end user support
  • Customer needs to establish an end user support policy with designated service level targets and measures
  • Customer needs to have a Complaints Management Program
  • Customer needs to have a Dispute and Error Handling Procedure that provides for intake, response and appropriate resolution of end user disputes in compliance with Regulation E
  • Customers must provide a sample volume report, service level report, and service quality scorecard.
  • Virtual Account Disclosures
  • Virtual Account Marketing and Advertising Content

To start the qualification process you will need to reach out to your Sila Sales Executive.

Sandbox - Virtual Accounts are disabled by default. Sandbox access will be turned on after approval.

Virtual Accounts End User Requirements

This end user entity must have passed full KYC/KYB in order to open a virtual account.

Usage

Open a Virtual Account
https://docs.silamoney.com/docs/open_virtual_account

Refer to full documentation for request/response Specs and SDK examples.

This allows the user to generate/allocate a new virtual account number, and make it active for transacting.

The associated app must have virtual account creation enabled for this endpoint to result in the successful creation of a virtual account.

For this endpoint, the "app" and "user" used for creating the virtual account respectively come from the auth_handle and user_handle specified in the "header" object of the request body. The specified user must have passed full KYC in order to open a virtual account.

View a Virtual Account
https://docs.silamoney.com/docs/get_virtual_account

Refer to full documentation for request/response Specs and SDK examples.

To view the data associated with a single virtual account, the /get_virtual_account endpoint will return an array of virtual account data including the balance.

View All Virtual Accounts
https://docs.silamoney.com/docs/get_virtual_accounts

Refer to full documentation for request/response Specs and SDK examples.

To view a list of virtual accounts for an entity, use the /get_virtual_accounts API. 

POST /0.2/get_virtual_accounts HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]

{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2",
    "crypto": "ETH", 
    "reference": "<your unique id>"
  }
}

***

HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "response_time_ms": "171",
  "virtual_accounts": [
    {
      "virtual_account_id": "UUID",
      "virtual_account_name": "myvaccount",
      "account_number": "9710001234567890",
      "routing_number": "084106768",
      "account_type": "VIRTUAL_ACCOUNT",
      "active": true,
      "closed": false,
      "created_epoch": 1644525019,
      "closed_epoch": null,
      "ach_credit_enabled": true,
      "ach_debit_enabled": false
    }
  ],
  "pagination": {
    "returned_count": 1,
    "total_count": 1,
    "current_page": 1,
    "total_pages": 1
  }
}

View All Payment Methods
https://docs.silamoney.com/docs/get_payment_methods

To view a list of payment methods for an entity, which would include virtual accounts, use the /get_payment_methods API.

Sample request/response - for SDK examples, refer to the link above for the full documentation.

POST /0.2/get_payment_methods HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]

{
  "header": {
    "created": 1234567890, 
    "auth_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "reference": "<your unique id>"
  }
}

***

HTTP/1.1 200 OK

{
    "success": true,
    "payment_methods": [
        {
            "payment_method_type": "blockchain_address",
            "blockchain_address_id": "79e1154a-4a78-4ea9-971b-54a8b17dxxxx",
            "blockchain_address": "0x3999A8eb9B6CD5a3646497A354D2d9f90D42Ea8e",
            "blockchain_network": "ETH",
            "nickname": "My Wallet",
            "frozen": false,
            "default": true
        },
        {
            "payment_method_type": "bank_account",
            "bank_account_id": "db0be7e5-cd90-444c-9145-a9f64c3xxxxx",
            "account_number": "*9999",
            "routing_number": "044000000",
            "account_name": "Chase",
            "account_type": "CHECKING",
            "active": true,
            "account_status": "active",
            "account_link_status": "instantly_verified",
            "match_score": 0.95,
            "entity_name": "Sally Mander",
            "account_owner_name": "SALLY D MANDER",
            "web_debit_verified": true
        },
        {
            "payment_method_type": "card",
            "card_id": "17135ec1-607e-49bf-9bcd-28dcc46xxxxx",
            "card_name": "My Card",
            "card_last_4": 9999,
            "expiration": "202505",
            "card_type": "Debit",
            "pull_enabled": true,
            "push_enabled": true,
            "push_availability": "Immediate",
            "active": true,
            "country": "US",
            "currency": "USD"
        },
    {
            "payment_method_type": "virtual_account",
            "virtual_account_id": "UUID",
            "virtual_account_name": "myvaccount",
            "account_number": "9710001234567890",
            "routing_number": "084106768",
            "account_type": "VIRTUAL_ACCOUNT",
            "active": true,
            "closed": false,
            "created_epoch": 1644525019,
            "closed_epoch": null,
            "ach_credit_enabled": true,
            "ach_debit_enabled": false
        }      
    ],
    "pagination": {
        "returned_count": 4,
        "total_count": 4,
        "current_page": 1,
        "total_pages": 1
    },
    "status": "SUCCESS", 
    "response_time_ms": "171",
    "reference": "<your unique id>"
}

Incoming External ACH Transactions

Virtual accounts can receive incoming external ACH transactions that can be debits or credits. A credit transaction will appear as an "issue" transaction, and a debit transaction will appear as a "redeem" transaction.

Transaction Status Update webhooks will fire when these transactions occur based on the effective date of the transaction. If the effective date is not in the future (most common scenario), then you will receive a webhook with the "complete" status within an hour of when the transaction is received. If the transaction has an effective date in the future, you will first receive a webhook with the "queued" status within an hour of when the transaction is received, and then another webhook with the "complete" status on the morning of effective date.

📘

Sandbox Mocking

Since virtual accounts support incoming external ACH transactions, we created a special sandbox-only API that simulates these incoming external ACH transactions. By calling this API, you can observe the activity on the virtual account that is the result of these incoming external ACH transactions.

Creating Test Incoming External ACH Transactions in Sandbox
https://docs.silamoney.com/v0.3/docs/testing_vaccount_transactions_in_sandbox

To simulate an external incoming ACH transaction to a virtual account, use the /create_test_virtual_account_ach_transaction endpoint.

Once you call this API, you can observe the transaction in /get_transactions. There may be a slight delay while the transaction is processing.

Valid Transaction Codes:
22: Automated deposit (checking credit)
23: Prenote of checking credit
27: Automated payment (checking debit)
28: Prenote of checking debit
32: Automated deposit (savings credit)
33: Prenote of savings credit
37: Automated payment (savings debit)
38: Prenote of savings debit

📘

Prenotes

A Prenote is a zero dollar transaction that can be sent to a virtual account as a debit or credit. Financial institutions often send a prenote transaction to an account for verification purposes prior to sending actual debits and credits.
Prenotes will trigger transaction webhooks and will appear in the /get_transactions API results.
Prenotes will not appear on statements.

Sample request/response - for SDK examples, refer to the link above for the full documentation.

POST /0.2/create_test_virtual_account_transaction HTTP/1.1
{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2",
    "reference": "ref"
  },
    "amount": 20000,
    "virtual_account_number": 9710001234567890,
    "tran_code": 22,
    "entity_name": "SALLY SMITH",
    "ced": "PAYROLL",
    "ach_name": "ACME INC"
}

***

HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "reference": "ref",
  "message": "Transaction submitted to the processing queue."
}

Sila Transactions

Virtual account behave similarly to wallets, where you can use Sila APIs issue/transfer/redeem for moving funds in and out.

Creating Sila transactions involving virtual accounts requires the use of the virtual_account_id as the identifier of the virtual account, and using the new source_id and destination_id parameters in the issue/transfer/redeem APIs.

The virtual_account_id can be viewed using one of these APIs:
https://docs.silamoney.com/docs/get_virtual_accounts
https://docs.silamoney.com/docs/get_payment_methods

Below are some examples of how you can transact with a virtual account.

Issue Sila
https://docs.silamoney.com/docs/issue_sila

To add funds to a virtual account via a linked bank account, call /issue_sila, providing the account_name of the linked bank account as the source, and the destination_id as the virtual_account_id . Please note, descriptor is an optional parameter, and the use of a descriptor will incur an additional fee per transaction.
Also note for our instant products where virtual accounts are the destination, processing_type = "INSTANT_ACH" is supported, but processing_type = "INSTANT_SETTLEMENT" currently is not.

Sample request - linked bank account to virtual account

POST /0.2/issue_sila HTTP/1.1
{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "reference": "ref"
  }, 
  "amount": 2000,
  "descriptor": "my transaction",
  "account_name": "My Chase", -- source is the linked bank account
  "destination_id": "d8bcfb75-b521-4230-b433-e453f43f668b", -- virtual_account_id of virtual account
  "business_uuid": "<your business UUID>",
  "processing_type": "STANDARD_ACH"
}

Redeem Sila
https://docs.silamoney.com/docs/redeem_sila

To redeem funds from a virtual account to a linked bank account, call /redeem_sila, providing the source_id of the virtual account as the source, and the account_name of the linked bank account as the destination. Please note, descriptor is an optional parameter, and the use of a descriptor will incur an additional fee per transaction.

Sample request - virtual account to linked bank account

POST /0.2/redeem_sila HTTP/1.1
{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"sally_handle", 
    "version": "0.2", 
    "reference": "ref"
  }, 
  "amount": 2000,
  "source_id": "d8bcfb75-b521-4230-b433-e453f43f668b", -- virtual_account_id of virtual account
  "account_name": "My Chase", -- destination is the linked bank account
  "descriptor": "my transaction",
  "business_uuid": "<your business UUID>",
  "processing_type": "STANDARD_ACH"
}

Transfer Sila
https://docs.silamoney.com/docs/transfer_sila

To transfer funds to a virtual account from a wallet, call /transfer_sila, providing the source_id of the wallet as the source, and the destination_id as the virtual_account_id . The source_id of the wallet will be the blockchain_address_id of the wallet, which can be viewed using the /get_payment_methods API. You can also transfer funds to a virtual account from another virtual account, or transfer funds from a wallet to a virtual account.

Sample request - wallet to virtual account

POST /0.2/transfer_sila HTTP/1.1
{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "reference": "ref"
  }, 
  "amount": 2000,
  "descriptor": "my transaction",
  "source_id": "6c18a1a5-70c1-4872-9cf2-559b59708d3e", -- blockchain_address_id of wallet --
  "destination_id": "d8bcfb75-b521-4230-b433-e453f43f668b", -- virtual_account_id of virtual account
  "destination_handle": "user.silamoney.eth" -- user handle of the destination
}

Sample request - virtual account to virtual account

POST /0.2/transfer_sila HTTP/1.1
{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "reference": "ref"
  }, 
  "amount": 2000,
  "descriptor": "my transaction",
  "source_id": "6c18a1a5-70c1-4872-9cf2-559b59708d3e", -- virtual_account_id of virtual account 1
  "destination_id": "d8bcfb75-b521-4230-b433-e453f43f668b", -- virtual_account_id of virtual account 2
  "destination_handle": "user.silamoney.eth" -- user handle of the destination
}

Sample request - virtual account to wallet

POST /0.2/transfer_sila HTTP/1.1
{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "reference": "ref"
  }, 
  "amount": 2000,
  "descriptor": "my transaction",
  "source_id": "d8bcfb75-b521-4230-b433-e453f43f668b", -- virtual_account_id of virtual account
  "destination_id": "6c18a1a5-70c1-4872-9cf2-559b59708d3e", -- blockchain_address_id of wallet
  "destination_handle": "user.silamoney.eth" -- user handle of the destination
}

Updated 7 months ago

What’s Next