API Documentation

/open_virtual_account

Suggest Edits

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.

How to open a virtual account

To create a virtual account, use the /open_virtual_account endpoint. The virtual account created will be associated with the end user entity provided in the authentication header.

The virtual account and routing number are provided in the response. A virtual account number is sixteen digit number. The first six digits of that number are a bin that is assigned to the customers app and will be static for all of that apps virtual accounts.

Example: [static bin][dynamic digits]
9710001234567890

Requests

Authorization / Authentication

Apps using Access Token Authorization

Use a valid access token in an Authorization: Bearer request header.

See Authenticating with an Access Token for more details.

Apps using ECDSA Authentication

Both authsignature and usersignature headers are required for this request. The usersignature header should be generated with a keypair registered to the user (either registered from the /register endpoint or the /register_wallet endpoint).

See the section on ECDSA Authentication for more detail about ECDSA signature generation.

POST /0.2/open_virtual_account 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", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  },
  "virtual_account_name": "Sherrys Money Tree",
  "ach_credit_enabled": true,
  "ach_debit_enabled": false
}

***
HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "response_time_ms": "171",
  "reference": "<your unique id>",
  "message": "Virtual account successfully opened.",
  "virtual_account": {
    "virtual_account_id": "{{payment instrument UUID here}}",
    "virtual_account_name": "Sherrys Money Tree",
    "account_number": "1234567812345678",
    "routing_number": "123456789",
    "account_type": "VIRTUAL_ACCOUNT",
    "active": true,
    "closed": false,
    "created_epoch": 1645105714,
    "closed_epoch": null,
    "ach_credit_enabled": true,
    "ach_debit_enabled": false
  }
}

var payload = {
    "ach_debit_enabled":true,
    "ach_credit_enabled":false,
    "virtual_account_name":'default_v_account_1',
    "statements_enabled": true
}
const res = await sila.openVirtualAccount(userHandle, userPrivateKey, payload);

Success Response Object
{
  "statusCode": 200,
  "headers": {
    "server": "nginx/1.14.0 (Ubuntu)",
    "date": "Fri, 25 Mar 2022 11:45:07 GMT",
    "content-type": "application/json",
    "content-length": "511",
    "connection": "close",
    "access-control-allow-origin": "*",
    "access-control-allow-headers": "*",
    "allow": "POST, OPTIONS",
    "vary": "Cookie"
  },
  "data": {
    "success": true,
    "reference": "c18fadd8-0c75-4b7d-a995-59af6ba09ee6",
    "message": "Virtual account successfully opened.",
    "virtual_account": {
      "virtual_account_id": "72130e62-1bd8-431d-b88d-2440a27c828a",
      "virtual_account_name": "default_v_account_1",
      "account_number": "9710010589065012",
      "routing_number": "084106768",
      "account_type": "VIRTUAL_ACCOUNT",
      "ach_credit_enabled": false,
      "ach_debit_enabled": true,
      "active": true,
      "closed": false,
      "created_epoch": 1648208707,
      "closed_epoch": null
    },
    "status": "SUCCESS",
    "response_time_ms": "255"
  }
}

payload = {
    "virtual_account_name": "default",
    "user_handle": "user.silamoney.eth",
    "ach_credit_enabled": True,
    "ach_debit_enabled": False,
  	"statements_enabled": True
}

silasdk.User.openVirtualAccount(app, payload, eth_private_key)

# Success

{
   "success":true,
   "reference": "<your unique id>"
   "message":"Virtual account successfully opened.",
   "virtual_account":{
      "virtual_account_id":"f06e7f6d-381f-42c0-997f-98b86cfe3770",
      "virtual_account_name":"default",
      "account_number":"9710013025110151",
      "routing_number":"084106768",
      "account_type":"VIRTUAL_ACCOUNT",
      "active":true,
      "closed":false,
      "created_epoch":1642756429,
      "closed_epoch":"None",
      "ach_credit_enabled": true,
      "ach_debit_enabled": false,
     "statements_enabled": true
   },
   "status":"SUCCESS",
   "status_code": 200,
}

ApiResponse response = api.openVirtualAccount("userHandle", "userPrivateKey","virtual_account_name","ach_credit_enabled","ach_debit_enabled","statements_enabled");          

// Success Response
System.out.println(response.getStatusCode()); // 200
VirtualAccountResponse parsedResponse = (VirtualAccountResponse) response.getData();
System.out.println(parsedResponse.getStatus()); // SUCCESS
System.out.println(parsedResponse.getSuccess()); // true
System.out.println(parsedResponse.getReference()); // Reference number
System.out.println(parsedResponse.getMessage()); // Virtual account successfully opened.

parsedResponse.getVirtualAccount(); // Virtual account details
System.out.println(parsedResponse.getVirtualAccount().getVirtualAccountId()); // 1df8f430-3dec-47a2-bfa7-5e02b19a7bc8
System.out.println(parsedResponse.getVirtualAccount().getVirtualAccountName()); // Your virtual account name
System.out.println(parsedResponse.getVirtualAccount().getAccountNumber()); // Account number
System.out.println(parsedResponse.getVirtualAccount().getRoutingNumber()); // 123456789
System.out.println(parsedResponse.getVirtualAccount().getAccountType()); // VIRTUAL_ACCOUNT
System.out.println(parsedResponse.getVirtualAccount().getClosedEpoch()); // "null" or <epoch_timestamp>
System.out.println(parsedResponse.getVirtualAccount().getCreated_epoch()); // <epoch_timestamp>
System.out.println(parsedResponse.getVirtualAccount().isClosed()); // true/false
System.out.println(parsedResponse.getVirtualAccount().isActive()); // true/false
System.out.println(parsedResponse.getVirtualAccount().isAchCreditEnabled()); // true/false
System.out.println(parsedResponse.getVirtualAccount().isAchDebitEnabled()); // true/false
System.out.println(parsedResponse.getVirtualAccount().isStatementsEnabled()); // true/false

$userHandle = 'user.silamoney.eth';
$userPrivateKey = 'some private key'; // Hex format
$virtualAccountName = "virtual account name";
$achDebitEnabled = true;// Optional - null or true or false;
$achCreditEnabled = true;// Optional - null or true or false;
$statements_enabled = true;

// Call the api
$response = self::$config->api->openVirtualAccount($userHandle, $userPrivateKey, $virtualAccountName);


// or without optional params
$response = $client->openVirtualAccount($handle, $privateKey, $virtualAccountName, $statements_enabled);


echo $response->getStatusCode();
echo $response->getData()->status;
echo $response->getData()->success;
echo $response->getData()->virtualAccount["account_type"];
echo $response->getData()->virtualAccount["virtual_account_name"];
echo $response->getData()->virtualAccount["ach_credit_enabled"];
echo $response->getData()->virtualAccount["ach_debit_enabled"];
echo $response->getData()->virtualAccount["statements_enabled"];

//Load your informations
bool achCreditEnabled = true; // optional input field
bool achDebitEnabled = false; // optional input field
ApiResponse<object> response = api.OpenVirtualAccount(userHandle, userPrivateKey, virtualAccountName, achCreditEnabled, achDebitEnabled);

// Success Object Response

Console.WriteLine(response.StatusCode); // 200           
Console.WriteLine(((VirtualAccountResponse)response.Data).Message); // Message
Console.WriteLine(((VirtualAccountResponse)response.Data).Success); // true
Console.WriteLine(((VirtualAccountResponse)response.Data).Status); // SUCCESS
Console.WriteLine(((VirtualAccountResponse)response.Data).Reference); // ccb35eb8-xxxx-xxxx-xxxx-xxxxx
Console.WriteLine(((GetVirtualAccountsResponse)response.Data).ResponseTimeMs); // API responses time

Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount);
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.AccountNumber);  // 1234567812345678
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.AccountType); // VIRTUAL_ACCOUNT
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.Active);  // true/false
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.Closed); // true/false
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.ClosedEpoch); // epoch timestamp
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.CreatedEpoch); // epoch timestamp
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.RoutingNumber); // 044000000
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.VirtualAccountId); // {{payment instrument UUID here}}
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.VirtualAccountName); // name of virtual account

Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.AchCreditEnabled); // true
Console.WriteLine(((VirtualAccountResponse)response.Data).VirtualAccount.AchDebitEnabled); // false
KeyTypeDescription
headerJSON objectRequired. Requires these keys in JSON format: created, app_handle, user_handle. See the /check_handle endpoint for the complete list of fields in this object.
virtual_account_namestrOptional. If specified, this will become the nickname for the created virtual account.
Note: if the nickname is already in use for a Payment Instrument linked to the specified user, 8 characters will be placed at the end of the specified nickname to enforce uniqueness
ach_credit_enabledbooleanOptional. Whether or not the virtual account can receive incoming external ACH credits. Default is true.
ach_debit_enabledbooleanOptional. Whether or not the virtual account can receive incoming external ACH debits. Default is false.

Responses

Status CodeDescription
200Successfully opened a virtual account.
400Bad request format - check validation_details for more information.
401authsignature or usersignature header was absent or incorrect.
403Not Authorized
404Not Found

Response Contents

KeyDatatypeDescription
virtual_account_idUUIDUUID is unique and distinct to the virtual account
virtual_account_namestring or nullName of the virtual account
account_numberstringFull virtual account number
routing_numberstring or nullVirtual account ACH routing number.
account_typestringBank account subtype "VIRTUAL_ACCOUNT"
activebooleanWhether the virtual account is "active", True or False.
closedbooleanWhether the account is "closed", True or False.
createddatetimeUnix datetime for the date the virtual account was created.
closed_epochdatetime or nullUnix datetime for the date the virtual account was closed.
ach_credit_enabledbooleanWhether or not the virtual account can receive incoming external ACH credits
ach_debit_enabledbooleanWhether or not the virtual account can receive incoming external ACH debits

Updated 7 months ago