Balance Check
Automation tool for checking the balance of gift cards issued by various providers.
Supported Providers
- Blackhawk / Gift Card Mall -
blackhawkCAPTCHA - Spafinder -
spafinderCAPTCHA - GameStop -
gamestopCAPTCHA - Best Buy -
bestbuy
Providers marked with CAPTCHA will require an Anti-CAPTCHA API key.
Quick Start
Download and extract the appropriate standalone executable file for your operating system from the releases page.
Windows
Open a command prompt and cd to the directory where you downloaded the executable, e.g.:
cd C:\Users\John\Downloads
Or, open the folder in Explorer, hold the SHIFT key, and choose "Open Command Prompt Here" from the context menu.
From that command prompt window, run the following to display the full usage message:
balance-check.exe -h
To configure your Anti-CAPTCHA API key, run the following (replacing <key> with your key):
set ANTI_CAPTCHA_KEY="<key>"
To run a balance check using the blackhawk provider using a CSV on your desktop, you might run the following:
balance-check.exe blackhawk C:\Users\John\Desktop\cards.csv
Instead of typing out the full path to the input CSV, you can also drag-and-drop the CSV into the command prompt window after typing the first part of the command.
macOS & Linux
Open a terminal (macOS: Applications -> Utilities -> Terminal) and cd to the directory where you downloaded the binary, e.g.:
cd ~/Downloads
From that termal window, run the following to display the full usage message:
balance-check -h
To configure your Anti-CAPTCHA API key, run the following (replacing <key> with your key):
export ANTI_CAPTCHA_KEY="<key>"
To run a balance check using the blackhawk provider using a CSV on your desktop, you might run the following:
balance-check blackhawk ~/Desktop/cards.csv
CSV Format
Your input CSV should be formatted as follows:
- Each column should contain a parameter required by the specified provider
- A header row is required and should label each column with the name of the parameter it is defining
Each provider expects a certain set of parameters. In general, a provider supporting a prepaid debit card will expect a card_number, exp_month, exp_year, and cvv and a provider supporting a typical third-party gift card will expect a card_number and pin.
Example (for the blackhawk provider):
| card_number | exp_month | exp_year | cvv |
|---|---|---|---|
| 4111111111111111 | 12 | 24 | 999 |
Contributing
Contributions of all kinds are welcome!
To get started, install Python 3.7, pip, and virtualenv.
Clone this repository, set up your virutal environment, and install the dependencies:
git clone https://github.com/stevenmirabito/balance-check.git
cd balance-check
virtualenv .venv -p python3
pip install .
pre-commit install
You will have the balance-check CLI on your path. You may need to pip install . again after making code changes in order to sync the changes with the virtualenv.
Please fork this repository, push to your fork, and open a pull request to contribute changes.
Adding a Provider
Providers must implement a uniquely-named subclass of BalanceCheckProvider in the balance_check.providers module. If your provider has been successfully registered, it will appear in the usage message as a supported provider.
Your provider must implement check_balance(self, **kwargs) which will accept a keyword argument for each column in the input spreadsheet. You may optionally define a Cerberus schema on self.schema and invoke self.validate with any fields you would like to validate. This is recommended to ensure your provider will not send requests with bad card data. A built-in schema generator for prepaid cards is provided in balance_check.validators.credit_card and convenience functions for solving CAPTCHAs are provided on balance_check.captcha_solver.
Notes:
- Do not
print()inside your provider - instead, importbalance_check.loggerwhich has been configured to not interfere with the progress bar shown to the user - If your provider is unable to successfully retrieve the balance for a card, it is safe to simply raise an exception - this will be caught by the application, the user will be shown a formatted message, and the check will be retried.
If you find this tool useful, consider buying a coffee for the author.