Transaction Effects On Balance

Whenever a transaction occurs, it affects the wallet it is associated with. For purchases, the wallet's balance is deducted, while for refunds, the balance is increased. Transactions each have a history: a set of events which ultimately result in a final overall result.

The order of these events is dependent on how the specific merchant has chosen to process the transaction. Some transactions can have multiple partial smaller settlements, while others may only have a single settlement. There are other nuances that can occur such as transactions settling for an amount that is different than what was authorized, or transactions expiring after not being settled.

The Penny system keeps track of all of these changes which occur for a transaction and ensures that your wallet balance correctly reflects these changes. The overall effect that a transaction has had throughout its lifetime is summarized within its effect_on_balance field:

{
    "effect_on_balance": {
        "from_fees": {
            "available_balance": ...,
            "total_balance": ...
        },
        "overall": {
            "available_balance": ...,
            "total_balance": ...
        }
    }
}

This field indicates how much the transaction has affected your wallet's available balance and total_balance, breaking it down into two components:

1. How much the transaction affected your wallet overall (transaction amount + fees)
2. How much the transaction affected your wallet through its related fees (fees only)

This field is cumulative, meaning that it shows the effect on your wallet's balance at that point in its history. Therefore, in order to know how much the transaction affected your wallet overall, you must look at this field in the transaction's latest version.

For example, consider the following transaction history (fees are an example only):

1. Authorization: 15 USD, Fees: 0.10 USD
2. Settlement:     5 USD, Fees: 0.10 USD
3. Settlement:    10 USD, Fees: 0.10 USD

The effect_on_balance field in this case would be as follows:

1. Authorization: 15 USD, Fees: 0.10 USD
{
    "effect_on_balance": {
        "from_fees": {
            "available_balance": 0.10,
            "total_balance": 0.00
        },
        "overall": {
            "available_balance": -15.00,
            "total_balance": 0.00
        }
    }
}

2. Settlement:     5 USD, Fees: 0.10 USD
{
    "effect_on_balance": {
        "from_fees": {
            "available_balance": 0.10,
            "total_balance": 0.10
        },
        "overall": {
            "available_balance": -5.10,
            "total_balance": -5.10
        }
    }
}

3. Settlement:    10 USD, Fees: 0.10 USD
{
    "effect_on_balance": {
        "from_fees": {
            "available_balance": 0.20,
            "total_balance": 0.20
        },
        "overall": {
            "available_balance": -15.20,
            "total_balance": -15.20
        }
    }
}

Notice that the latest version (version 3) of the transaction's effect_on_balance contains the overall effect that the transaction has had (-15.20 USD total, with 0.20 USD of that being from fees), while the other versions contain the cumulative steps it went through the end up with that final overall effect.