Bank Cards API

An API that simulates a basic Bank Cards system, built with FastAPI and uvicorn, used in the Wallet System project.

Setup:

1. Clone the repository:

   git clone <repo-url>

2. Navigate to the repository root:

   cd Bank-Cards-API

3. Install project dependencies:

   pip install -r requirements.txt

4. Setup a working MariaDB server:

   • Option 1: Download and install from the official MariaDB page.
   • Option 2: Setup a MariaDB container with Docker:
     • Pull MariaDB:

       docker pull mariadb

     • Run MariaDB:

       docker run -p 3306:3306 --name <NAME> -e MYSQL_ROOT_PASSWORD=<PASSWORD> -d mariadb:latest

5. Configure the project environment:

   • Create a .env file in the root directory:

      # PRIVATE MariaDB connection params
      DB_USER='your_db_user'
      DB_PASSWORD='your_db_password'
      DB_HOST='your_host_address'
      DB_PORT='your_host_port'
      DB_NAME='bank_cards_api_db'
     
      # PRIVATE ExchangeRate API Key
      EXCHANGE_RATE_API_KEY='your_exchange_rate_api_key'
     
      # PRIVATE Bank Cards encryption Key
      DB_BANK_CARDS_ENCRYPT_KEY='your_bank_cards_encrypt_key'

   • Import the schema from db_schema.sql (located in the data folder) into your running MariaDB server.

6. Start the server

   • Option 1 (Recommended): Use uvicorn to run the FastAPI app:

     uvicorn main:app --host 127.0.0.1 --port 8001 --reload

   • Option 2: Run the main.py file with your preferred IDE, or:

     python ./main.py

   If everything is configured properly, the web server will be available at: http://127.0.0.1:8001/

   • API documentation: Once the server is running, you can access the interactive API docs at http://127.0.0.1:8001/docs (provided by FastAPI).

---

API Overview

• All endpoints are under the /bankcards prefix.
• All currency codes are strictly validated against a live/cached set from the ExchangeRate API.
• The API returns detailed error messages and appropriate HTTP status codes for invalid requests, not found, insufficient funds, and internal errors.
• Currency conversion is handled automatically for all types of transfers if different currencies are used.
• Interactive API documentation is always available at /docs.

---

Endpoints:

POST /bankcards

• Purpose: Create a new bank card in the system.
• Request Body: New Bank Card details, example:

  {
      "number": "1111222233334444",
      "expiration_date": "02/24",
      "card_holder": "Elliot Alderson",
      "check_number": "123",
      "currency_code": "USD",
      "starting_balance": 1234.00
  } 

• Response: Bank Card lookup hash with status code 201, example:

  {
      "card_lookup_hash": "hash-string"
  }

• Possible errors:
  • 400 — Card with the given information already exists.
  • 422 — If any of the Request Body fields are invalid.
  • 500 — Internal server error.

GET /bankcards

• Purpose: Get the current balance and id of a given card.
• Request Body: Bank Card details, example:

  {
      "number": "1111222233334444",
      "expiration_date": "02/24",
      "card_holder": "Elliot Alderson",
      "check_number": "123"
  } 

• Response: Balance and id details with status code 200, example:

  {
      "card_lookup_hash": "hash-string",
      "balance": 1234.00,
      "currency_code": "USD"
  }

• Possible errors:
  • 404 — The card was not found.
  • 422 — One or multiple invalid Request Body fields.
  • 500 — Internal server error.

PUT /bankcards/transfer/{sender_card_lookup_hash}/{receiver_card_lookup_hash}

• Purpose: Transfer a given amount of money from the sender card to the receiver one. Handles currency conversion if needed.
• Request Body: Transfer details, example:

  {
      "amount": 1234.00,
      "currency_code": "USD"
  }

• Response: Transfer success with status code 200, example:

  {
      "amount": 123,
      "currency_code": "BGN",
      "transfer_type": "TRANSFER"
  } 

• Possible errors:
  • 400 — Invalid client request, sender currency mismatch, or insufficient funds.
  • 404 — One of the cards was not found.
  • 422 — One or multiple invalid Request Body fields.
  • 500 — Internal server rror.

PUT /bankcards/withdraw/{card_lookup_hash}

• Purpose: Withdraw a given amount of money from the given card. Handles currency conversion if needed.
• Request Body: Withdraw details, example:

  {
      "amount": 1234.00,
      "currency_code": "USD"
  }

• Response: Withdraw success with status code 200, example:

  {
      "amount": 123,
      "currency_code": "BGN",
      "transfer_type": "WITHDRAW"
  } 

• Possible errors:
  • 400 — Invalid client request.
  • 402 — Card has insufficient funds for this transfer.
  • 404 — The card was not found.
  • 422 — One or multiple invalid Request Body fields.
  • 500 — Internal server error.

PUT /bankcards/deposit/{card_lookup_hash}

• Purpose: Deposit a given amount of money into the given card. Handles currency conversion if needed.
• Request Body: Deposit details, example:

  {
      "amount": 1234.00,
      "currency_code": "USD"
  }

• Response: Deposit success with status code 200, example:

  {
      "amount": 123,
      "currency_code": "BGN",
      "transfer_type": "DEPOSIT"
  } 

• Possible errors:
  • 400 — Invalid client request.
  • 404 — The card was not found.
  • 422 — One or multiple invalid Request Body fields.
  • 500 — Internal server error.

---

License

This project is licensed under the MIT License. View LICENSE for details.