Overview

Spinwheel's Bank Account Real-time Balance product provides you with key insight about a user's bank account. Please review our best practices for utilizing this product below!

Sandbox Test Data

Use the following test data in order to test successfully creating a bank account, and getting the realtime balance:

{
    "routingNumber": "121000248",
    "accountNumber": "001875060663",
    "telephoneBankingPin": "0000",
    "accountType": "CHECKING"
}

Use the following test data to test a NOT_SUPPORTED institution.

{
    "routingNumber": "21001208",
    "accountNumber": "001122060415",
    "telephoneBankingPin": "0000",
    "accountType": "CHECKING"
}

Step 1: Add a Bank Account

The first step is to add a bank account. Include the relevant routing number and account number. It is recommended to also include the account type and telephone banking pin for maximum coverage. When using the sandbox environment, please use the sandbox test data .

Determining Eligibility

Included in the response from the request to add a bank account (as well as the /v1/users endpoint ) is the capabilities matrix . We recommend confirming that the newly added bank account is supported for real-time balances prior to attempting to fetch it.

The following is an example of what could be seen on a bank account that is SUPPORTED for real-time balances.

{
  ...
  "data": {
    ...
    "capabilities": {
      "payments": {
        "billPayment": {
          "availability": "SUPPORTED"
        },
        "receiveOnlyPayment": {
          "availability": "SUPPORTED"
        }
      },
      "data": {
        "realtimeBalance": {
          "availability": "SUPPORTED" <-- ✅
        }
      }
    }
  }
}

Reasons the real-time balance may be NOT_SUPPORTED:

• INSTITUTION_NOT_SUPPORTED
• INSTITUTION_DISABLED
• REFRESH_EXHAUSTED
• NOT_PRIMARY_ACCOUNT_HOLDER
• ACCOUNT_TERMINATED
• CLOSED_ACCOUNT_NO_BALANCE
• CLOSED_ACCOUNT
• ACCOUNT_NUMBER_VERIFICATION_FAILED

Step 2: Initiate a Bank Account Balance Lookup

Once a bank account is created, you can simply call to look up the real-time balance, by using the userId and bankAccountId. Once this request is made, the status of the look up will be IN_PROGRESS. You may also notice that once a real-time balance request is made, the realtimeBalance.availability will be NOT_SUPPORTED to prevent multiple concurrent requests for a single bank account.

Step 3: Retrieve the Balance

In order to retrieve the bank account's balance, we recommend registering a webhook, you can read more on that here. Alternatively you may poll for changes in status using this endpoint.