Payment Processing Changes

Distributions have recently seen a fairly major upgrade and revamp, one that is major enough that there are some backward compatibility issues for API users (albeit, minor ones).

Distributions were originally built automatically from aggregate amounts. Those who have created distributions know that you enter amounts related to the payment types (principal, interest, dividend, etc.) and the system inspects the current investor holdings and automatically creates payments.

This system works really well for simple payments that take place only after holdings are assigned. In practice, however, this model has issues when:

  1. You’re making some kind of special single payment.
  2. You need to add payments to a distribution that are pro-rated in some fashion.
  3. You’re making a correction from a prior distribution.
  4. You have some sort of complex payment system where investors are paid at different interest rates or other custom logic.

To accommodate a wider range of client needs, the way in which distributions are put together has changed.

Build by Payments, Not Aggregates

You can now create distributions with total amounts of 0. Just create a new distribution and specify 0 as the amount to each amount category. Doing so will yield an empty distribution. The API itself as well as the interface at has been updated to allow new payments to be created and creating payments automatically updates the distribution total.

This means, in a situation where you only want to pay a subset of investors, you no longer need to have a distribution filled with a bunch of 0 amount payments or have to work around cumbersome recalculations. Create the distribution, add a prorated payment or two, and submit.

Detailed Payments

A change that was necessary to accommodate this was adding the amount breakdowns to the payments themselves. This is important because the aggregates on the distribution need to be updated and, in the case of complex payment systems, the amount allocated to each payee may break down differently than the aggregate total.

Pay Directly From Custodial Accounts Revisited

When our distribution system was originally launched, it was possible to make distributions directly from escrow, because that’s where the funds were located. However, with time and growth, FASTransfer has become the organization responsible for distributions and funds must be sent to FASTransfer for distribution.

This change made the workflow of moving funds from an escrow account to FASTransfer a little cumbersome. Specifically, the issuer needed to make a disbursement from escrow to FASTransfer to cover the total on a distribution after it was created. Now, when creating a distribution, the custodial account is available as a payment_method.

This option is actually just a convenient method for doing the same above. If you wish to create a distribution from funds in your custodial account, selecting the custodial account option automatically queues up a disbursement to FASTransfer. The process itself hasn’t changed, but a portion of it is managed automatically.

Distribution Hold Times

With growth comes some policy changes. Hold times have been added to distributions themselves. This means if funding via ACH, it will take 10 days before the distribution is sent out. This is to prevent ACH rejections from showing up after funds have been sent.

And exception to this rule are distributions funded via escrow disbursements. Even though these disbursements default to “ACH” they are not subject to the long hold time as the funds can be verified ahead of time.

Payment Failures

Individual payments used to simply get reprocessed when there was a problem processing and there was no real good feedback from the interface or the API. Like investments, investor payments get marked as failed if there is an issue processing the payment (this is generally due to checks not being received or ACH information for the investor being bad or, in rarer cases, the payee rejecting the payment).

When payments are marked as failed a new payment is created to be processed again. This means if there is an issue delivering an initial payment and a second one is paid, the investor will have two payments associated for the distribution, not one. One will be failed and the other will be paid.

API Issues

This change does cause some issues customers using the distributions API directly in complex ways. For a majority of users, nothing changes, but for those creating distributions and then altering the amounts by investor, you may have to make some slight modifications to your code—and those modifications should lead to a simpler setup.

  1. You can create payments while the distribution is in draft mode. This means if an investor doesn’t have a holding assigned yet and you wish to make some sort of early interest payment, go ahead and add said investor.
  2. You can destroy payments while the distribution is in draft mode. This is much more natural than setting the amount to 0. (Furthermore, 0 payments are automatically destroyed when marking a distribution as ready.)
  3. You should update the category amount (e.g. interest_amount, dividend_amount, etc.) rather than amount directly.
  4. Creating, updating, or destroying payments automatically updates the aggregate amounts on the distribution itself. This means you no longer have to update the totals yourself after making a bunch of changes.
  5. If you wish to create an empty distribution, set recalculate_investor_payments to false when creating.