/balance-check

Check gift card balances for a variety of providers

Primary LanguagePythonMIT LicenseMIT

Logo

Balance Check

Build Status Build status Python 3.7 License: MIT Code style: black

Automation tool for checking the balance of gift cards issued by various providers.

Supported Providers

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 -r requirements.txt
pre-commit install

You can invoke the tool by running python -m balance_check in place of balance-check.

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. You must then add it to the __all__ list in balance_check.providers.__init__. 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, import balance_check.logger which 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.

Bank Cards icon by Icons8