API Documentation

/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

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

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.

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
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",
    "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
bank_account_idStringOptional. Use the bank_account_id UUID found in /get_payment_methods to specify which account you are selecting. Used when the end user has multiple accounts with the same 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.
400Multiple accounts found for the provided nickname. Please specify an account uuid.End user has linked payment methods with the same account name. Use /get_payment_methods to find the bank_account_id UUID of the account you want to use.
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 Plaid's 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 4 months ago