/get_account_balance

Requests bank account balance data from an end-users linked bank account.

The /get_account_balance endpoint will return available_balance and current_balance reported by the user entity's financial institution.

📘

In the sandbox environment $100.00 is used for the available bank account balance, $110 for the current bank account balance.

📘

Current vs. Available Balance

For prevention of returns for insufficient funds, Available Balance should be used as it includes the offset for any known pending transactions.

  

Requests

Both authsignature and usersignature headers are required for this request.

The account_name key is a nickname of one of the user's linked bank accounts for which balance data should be fetched.

Note - We recently renamed the field auth_handle to app_handle. For backward compatibility, auth_handle is still valid but has been removed from our documentation.

  
POST /0.2/get_account_balance HTTP/1.1
Host: sandbox.silamoney.com
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
Content-Type: application/json

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

***

HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "available_balance": 100,
  "current_balance": 110,
  "masked_account_number": "0000",
  "routing_number": 123456789,
  "account_name": "default", 
  "response_time_ms": "171",
  "reference": "<your unique id>"
}
const res = await Sila.getAccountBalance(
  userHandle,
  walletPrivateKey,
  accountName,
);

// Success Response Object

console.log(res.statusCode); // 200
console.log(res.data.success); // TRUE
console.log(res.data.status);
console.log(res.data.available_balance); // Available balance
console.log(res.data.current_balance); // Current balance
console.log(res.data.masked_account_number); // Masked account number
console.log(res.data.routing_number); // Routing number
console.log(res.data.account_name); // Account name
payload = {
    "user_handle": "user.silamoney.eth",
    "account_name": "default"
}

response = User.getAccountBalance(app, payload, user_private_key)

### Success Response Object

{
    "success": True,
    "available_balance": 100,
    "current_balance": 110,
    "masked_account_number": "0000",
    "routing_number": 123456789,
    "account_name": "default",
    "status": 'SUCCESS',
    "status_code": 200
}

### Failure Response Object

{
    "success": False,
    "message": "Error message"
}
ApiResponse response = api.getAccountBalance(DefaultConfigurations.getUserHandle(),
                DefaultConfigurations.getUserPrivateKey(), "account name");

// Success Response Object
System.out.println(response.getStatusCode()); // 200
System.out.println(((AccountBalanceResponse)response.getData()).getSuccess());
System.out.println(((AccountBalanceResponse)response.getData()).getStatus());
System.out.println(((AccountBalanceResponse)response.getData()).getAvailableBalance());
System.out.println(((AccountBalanceResponse)response.getData()).getAccountName()); // Account name
System.out.println(((AccountBalanceResponse)response.getData()).getCurrentBalance()); // Current Balance
System.out.println(((AccountBalanceResponse)response.getData()).getMaskedAccountNumber()); // Masked Account Number
System.out.println(((AccountBalanceResponse)response.getData()).getRoutingNumber()); // Account routing number
$userHandle = 'user.silamoney.eth';
$userPrivateKey = 'some private key'; // Hex format
$accountName = 'Custom Account Name';
$response = $client->getAccountBalance($userHandle, $userPrivateKey, $accountName);

// Success 200
echo $response->getStatusCode(); // 200
echo $response->getData()->success; // TRUE
echo $response->getData()->availableBalance; // Available balance
echo $response->getData()->currentBalance; // Current balance
echo $response->getData()->maskedAccountNumber; // Masked account number
echo $response->getData()->routingNumber; // Routing number
echo $response->getData()->accountName; // Account name
ApiResponse<object> response = api.GetAccountBalance(userHandle, walletPrivateKey, accountName);

// Success Object Response

Console.WriteLine(response.StatusCode); // 200
var parsedData = (GetAccountBalanceResponse)response.Data;
Console.WriteLine(parsedData.Success); // TRUE
Console.WriteLine(parsedData.AvailableBalance); // Available balance
Console.WriteLine(parsedData.CurrentBalance); // Current balance
Console.WriteLine(parsedData.MaskedAccountNumber); // Masked account number
Console.WriteLine(parsedData.RoutingNumber); // Routing number
Console.WriteLine(parsedData.AccountName); // Account name

Key

Type

Description

header

JSON object

Required. 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.

account_name

String

Required. Max length 40
The account_name must match a bank account associated with the user_handle; check /get_accounts endpoint for a list of these.
Example: Custom Account Name

  

Responses

Status Code

Key in Response

Description

200

N/A

Successfully fetched balance data for linked account.

400

validation_details

Bad request format - check validation_details for more information.

400

link_status

Account either has not completed verification with Plaid or was not linked with Plaid.

400

N/A

Unable to get bank account balance details. Original login credentials might have expired or the bank account may have been closed. Can attempt to link account again to try to fetch balance details.

403

N/A

authsignature or usersignature header was absent or incorrect.

404

N/A

account_name not found for current user.

🚧

Be aware!

Only accounts linked with Plaid's Instant Auth, eg. username and password, are eligible.

  • Not all U.S. financial institutions support /get_account_balance, and some institutions do not calculate nor provide "available balance."

  • Some U.S. financial institutions only return one or the other.

    You will need to handle these errors however you see fit.

    • Eg. if you can’t query the balance then the user should be subject to a lower transaction limit, or you should delay giving them access to their funds for 4 business days to ensure no returns occur.
  • Will NOT WORK for accounts linked with Plaids same day micro deposit or for accounts linked with Sila's direct account linking method.

    You will want to apply some cautious business logic to accounts linked in this manner to prevent these user from de-frauding you.
    Example:

    • Allow 1 transaction only before allowing a second transaction.
    • Limit the 1st transaction to safe dollar amount maximum
    • Hold the minted tokens for 5-7 business to be sure the dollars don't get returned before allowing a second transaction.

Did this page help you?