Bookkeeping

Tracking customer balances

We'll ask you to submit financial reporting to help us keep track of how much money each of your customers is holding. How this works depends on whether you're using individual or commingled accounts for your customers.

Individual customer accounts

If your individual customers have their own accounts, you’re done! We already have all the information we need.

Commingled accounts

If you're operating accounts commingling customer funds, you'll need to integrate against our Bookkeeping API. Read on.

Chart of Accounts

You don’t need to bookkeep the entirety of your finances to be compliant. We expect you to keep track of customer balances and commingled cash.

At a minimum, you’re expected to create:

1. One bookkeeping account per customer. With these accounts, you should set compliance_category to customer_balance and additionally pass the entity_id of the customer.
2. One bookkeeping account per commingled Account (i.e. account_123). With these accounts, you should set compliance_category to commingled_cash and additionally pass the account_id of the relevant account.

To set up a customer_balance bookkeeping account First, submit an informational entity for the customer whose balance you’re tracking. Then:

curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "name": "John Funds",
  "compliance_category": "customer_balance",
  "entity_id": "entity_456", # a customer entity
}'

# Response
{
  id: "bookkeeping_account_123",
  name: "John Funds",
  compliance_category: "customer_balance",
  entity_id: "entity_456"
}

To set up a commingled_cash bookkeeping account:

curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "name": "FBO Account",
  "compliance_category": "commingled_cash",
  "account_id": "account_abc" # a commingled account
}'

# Response
{
  id: "bookkeeping_account_456",
  name: "John Funds",
  compliance_category: "commingled_cash",
  account_id: "account_abc"
}

The above accounts will only be sufficient in narrow cases: you’ll likely need to create other Bookkeeping Accounts to handle situations where your customer balances do not match the commingled cash exactly. These accounts do not need to have a compliance_category. See the examples below.

Invariants

You are expected to submit bookkeeping entries such that:

1. The customer balances reflected in each of their bookkeeping accounts matches your ledger. This should reflect what a customer would see in your own application interface.
2. The balance in the commingled account matches the current balance in the account at all times.

When submitting bookkeeping entry sets affecting commingled cash accounts, you should tag an entry set with the transaction_id for the Transaction which affected the cash balance.

Examples

A customer transfers in $100

Debit customer_balance, credit commingled_cash:

curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_entry_sets" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "date": "2020-01-31T23:59:59Z", # date must match transaction.created_at
  "transaction_id": "transaction_123", # entries sum must match transaction.amount
  "entries": [
    {
      "bookkeeping_account_id": "bookkeeping_account_123", # customer balance account
      "amount": -100_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_456", # commingled cash account
      "amount": 100_00,
    }
  ]
}'

One customer transfers funds to another

Debit one customer_balance, credit the other customer_balance.

You charge a fee to a customer

First, you should create an AccountTransfer from the commingled Account to an Account you control (on your Commercial Banking program).

Credit commingled_cash, debit customer_balance, tag the transaction_id.

You receive a bundled payout from Stripe containing some corporate cash

First, you’ll need to create an Bookkeeping Account to track corporate cash being held in the FBO.

curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "name": "Corporate Cash"
}'

# Response
{
  id: "bookkeeping_account_789",
  name: "Corporate Cash"
}

Then, create an entry set (this example assumes you’re receiving a bundled payout for $230, $100 of which belongs to each of two customers and $30 of which belongs to you).

curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_entry_sets" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "date": "2020-01-31T23:59:59Z", # date must match transaction.created_at
  "transaction_id": "transaction_123", # entries sum must match transaction.amount
  "entries": [
    {
      "bookkeeping_account_id": "bookkeeping_account_123", # customer balance account
      "amount": -100_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_abc", # another customer balance account
      "amount": -100_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_789", # corporate cash
      "amount": -30_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_456", # commingled cash
      "amount": 230_00,
    }
  ]
}'