/get_account_balance

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

Suggest Edits

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

📘

Sandbox Only

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
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.
account_nameStringRequired. 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 CodeKey in ResponseDescription
200N/ASuccessfully fetched balance data for linked account.
400validation_detailsBad request format - check validation_details for more information.
400link_statusAccount either has not completed verification with Plaid or was not linked with Plaid or MX.
400N/AUnable 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.
403N/Aauthsignature or usersignature header was absent or incorrect.
404N/Aaccount_name not found for current user.

🚧

Be aware!

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

  • 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 approved by Sila to link 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.

Updated over 1 year ago