Return detailed escrow balances

[kyungmin]

As suggested in https://github.com/balanced/balanced-dashboard/issues/1385, we want to display all escrow balance breakdowns in the dashboard.

In addition to in_escrow, http://api.balancedpayments.com/marketplaces/ should also return reserve_balance and order_balance. (Open to suggestion on naming)

[mjallday]

what is order_balance? the sum of all funds uncollected from all orders?

[kyungmin]

@mjallday Yes. We want to expose how much money is left in their escrow for Orders users.

[mjallday]

What is that number useful for?

Let's approach this from another angle.

That number for an active marketplace is always going to be > 0 but what information does it provide? IMO a more useful display of information would be to bucket the Order balances by time. E.g. If I want to stay compliant I'd want to know how about which Orders have a balance that's been stored in Balanced for close to 30 days because that's money that I should be paying out.

I think we could potentially make the same argument for reserve_balance. If the marketplace needs to keep a reserve_balance equal to x days of processing then it would change over time. If reverse_balance is a fixed number then displaying a single integer makes more sense.

[kyungmin]

Staying compliant is one thing, but what happens to the balance after 30 days? If I want to check how much balance is available in my account, I would expect available_balance to include total order_balance as well as general in_escrow balance.

To encourage users to stay compliant, we can add a notification message to remind users that they need to debit/credit out their balance over 30 days.

[mjallday]

I like the idea of the notification, I think that's a great idea and we should open a separate issue to discuss.

If I want to check how much balance is available in my account

Available for what? The issue I see is that you can spend funds in one Order on anything other than the merchant associated with that Order. So what does it mean for the funds to be available? I'm failing to understand what the use case for seeing the sum total of my Orders apart from having an integer value to look at.

I can't do anything with that number without understanding the system in greater detail. I can't pay all that money out to a single merchant, what does it mean to have those funds available? Is this to give me a general metric to understand the health of my business?

That single number makes a lot more sense for aggregating because I need to know that number so I can calculate it against whatever liabilities I have on my books. With Orders I don't have that problem, I can't overpay from one Order to cover another.

This is just my opinion so please help me understand if my points are not making sense or there's an alternate use-case that I'm missing.

[kyungmin]

One specific use case that I heard from @rmanisha is that a customer was confused by escrow balance being still 0 after they created an order with debit. This may be a very specific use case that may be addressed differently. @rmanisha have you heard of any other cases similar to this?

[rmanisha]

No, but I'm not generally on support. Ping @rserna2010 @remear Have you guys heard other people have this issue?

@mjallday my concern is that at a glance, after charging a card and associating it to an order, a person will assume that the transaction did not succeed when checking their balance. This could possibly lead to double charges.

Speaking to the example you used, my liabilities include merchants that I have to pay using Orders. On my end, I'm going to keep track of the total amount of funds I have processed on behalf of my merchants, less funds I've paid out. At month end those numbers should reconcile to the funds held with Balanced. In the beginning of the life of my business, this will likely be handled by someone technical. Later, I will hand the task to an accountant, who will log onto the dashboard and check total balance held (orders, and general) and see if that agrees to our books.

Does that help?

[mjallday]

yes, i think where i'm going with this is trying to uncover gems like

my liabilities include merchants that I have to pay using Orders. On my end, I'm going to keep track of the total amount of funds I have processed on behalf of my merchants, less funds I've paid out.

the dashboard should provide views that display this information.

@kyungmin is going to figure out how our customers work with linked transactions to get the dashboard to better serve them.

I have no issue with adding a total order balance integer to the API but want to make sure we address the underlying issues that make this number important to them.

[remear]

@rmanisha We see this all the time in support. Customers do not immediately understand Orders maintain balances separate from both other Order balances and the marketplace balance.

[kyungmin]

@mjallday are you planning on implementing this?

[kyungmin]

Can this be prioritized? Not having this number is confusing for people who are using orders.