README

Overview

Digital wallet that associates transactions and balance to unique users.

Main goals

• Add and subtract transactions
• Lookup balance
• Support any number of currencies (incluiding company's own currencies)
• Transactions history

Generic requirements

• Amounts must allow decimals
• Use arbitrary precision (BCMath PHP)

User stories

• As consumer I want to create a wallet so I can perform further transactions with the same uid. I should be able add an initial amount in any currency of money and this amount could be negative. Independent of which currency I'm using the transaction values should be reasonably consistent on different days.
• As consumer I want to transact money by adding or subtracting balance from an existing wallet so a backer can pay for the services he consumes. Account balance must be consistent with the amount entered within transactions, even after a currency rate has changed. Negative amount transactions must include an expiration date if balance becomes negative after adding it.
• As consumer I want to lookup for current state of a wallet so I can know how much money a backer has available.
• As consumer I want to lookup for the current state of all wallets so I can have a general view.
• As consumer I want to lookup for the transactions history of a wallet so I can know how I've reached the current account balance of a wallet. Should be ordered by descending datetime.
• As consumer I want to filter by start and/or end time of transactions so I can be more granular on my transactions history lookup.
• As consumer I want to optionally include the currency object of transactions history list, so I don't need to look it up with other request.
• As consumer I want to list all existing currencies, so I can know which ones are available.
• As consumer I want to lookup at the current rate of a currency so I can display that information to users.
• As consumer I want to convert currency rates so I can perform operations based on this information.
• As consumer I want to send a notification email to the backer when a transaction is performed so he can have immediate feedback. A payment link must be included if account balance becomes negative. Must include due date and default to the absolute value of account balance.

Database tables

• currencies: id*, code (char 3), rate (decimal), step (decimal), created_at
• wallets: uid* (string 100), currency_code (fk char 3), balance (decimal), created_at, updated_at, deleted_at
• transactions: id*, wallet_uid (fk sting 100), currency_id (fk char 3), amount (decimal), type (string 100), description (string 255), detail (text), due_at (datetime), created_at, updated_at

Run it

Requirements

• BCMath PHP Extension
• Hawese Core

Installation

composer require hackware/hawese-wallet

Environment variables

• WALLET_TRANSACTION_TYPES are used to identify the origin of a transaction, it's a comma separated string of choices for Transaction::$type. By default only system is defined. Required.
• WALLET_DUE_AFTER a valid DateInterval::createFromDateString() string which defines the Transaction::$due_at date if a Wallet has negative balance. Defaults to 1 month.
• WALLET_SOURCE_URL is the place where to download the source code of your version of this project. Required.
• WALLET_ADD_FUNDS_URL Link to send with transaction notifications, which allows users to add new funds. Currently coupled to userland config, as will attach an auth_token query param (not more coupled than this). Required.
• WALLET_REMIND_DUE valid DateInterval::createFromDateString() comma separated string for sending remainders of due transactions X days previous to due date. Defaults to 1 day, 2 days, 3 days, 1 week.

Copyright and licensing

Copyright 2019 Hackware SpA.

This project is licensed under the GNU Affero General Public License v3 or any later version.

How to comply with license terms?

To comply with license terms you must provide the means to access the source code of your version of the software easily and free of charge to any person that has access to the software, even users which access through a network (i.e. web browser). I've provided an easy way to accomplish this requirement by setting the WALLET_SOURCE_URL environment variable, this will show the link on the index page (/) under the JSON links.wallet_sourcecode property.

Any modification or inclusion of this source code will inherit the same license, that is, it can't be sublicensed. But since it's a REST API you can consume it with any other software. That means that this software must always respect users freedom, even if the HTTP API is consumed by a privative one.

Other licensing options

If you want to use the software but are afraid of or can't comply with the license terms we can arrange other license terms for your case. Though most probably I'll not accept if you don't provide your modifications to the software back.