Recurring Contribution Process

Helix supports the concept of recurring contributions. A recurring contribution is defined by the various recurringContribution properties on a customer's account object. The Recurring Contributions Process does not create any transactions itself. It simply notifies you which accounts (and amounts) customers have configured to automatically deposit money into Helix on the following day.

Process Overview

  1. Helix generates a Bulk Transfer Initiate File
  2. The following day you begin the Bulk Transfer Process based on the above file.

📘

No transactions are created until the Bulk Transfer Process is started.

Standard Workflow

  1. Every day, the Helix Recurring Contribution process will determine which accounts have contributions scheduled to happen on the following day.
  2. Your system downloads the Bulk Transfer Initiate File from sftp.corepro.io and processes it. Your processing should involve investigating the Initiate File and processing it accordingly. For example you may want to contact customers via email or SMS to notify them their recurring contribution will happen the next day, giving them a chance to cancel it
  3. Follow the Bulk Transfer Process to actually transfer the funds

Simplified Workflow

The simplified workflow has the following prerequisites:

  • You do not need to give your customers the opportunity to cancel or void a recurring contribution the day prior to it occurring - meaning all Content rows that are in the Bulk Transfer Initiate File will always appear in the corresponding Bulk Transfer Request File
  • Your code does not need to populate the TransferTag field with a specific value when performing transfers via the Bulk Transfer Request File - meaning none of your code depends upon the tag property of the transaction object being populated

If the above is true, you may essentially copy/paste/rename/upload the Bulk Transfer Initiate File to create a Bulk Transfer Request File:

  1. Download the Bulk Transfer Initiate File. Suppose its name is 201401152209_BULKTRANSFERINITIATE.TXT
  2. The next day, rename that file to 20140116_BulkTransfer.txt and follow the Bulk Transfer Process.

📘

The Initiate File and the Request File are specifically formatted to support this simplified workflow. If you look at the files carefully, you'll notice the TransferDescription field in the Initiate File matches up exactly with the TransferTag field in the Request File. Code exists to specifically ignore the value of Recurring Deposit if it occurs in the TransferTag when processing the Request File in order to support this Simplified Workflow.

Bulk Transfer Initiate File Definition

The Bulk Transfer Initiate File is created by Helix on a daily basis and has the following properties:

  1. Fixed-length.
  2. ANSI encoded
  3. Line endings are Windows-style CarriageReturn + LineFeed (\r\n, or 0x0D0A)
  4. A client-specific location will be provided on sftp.corepro.io for downloading this file.
  5. File will be available in the relative directory of /BulkTransfer/Initiate
  6. File name follows a specific, case-sensitive pattern of: yyyyMMddhhmm_BULKTRANSFERINITIATE.TXT

🚧

Format Disclaimer
Helix reserves the right to append new field(s) to the end of any Header or Content line without notice. This is to allow new data points to be added as needed in a timely fashion.

Implementation Note
Your code should be written such that unexpected characters after the "last" field but prior to the end of each line should be ignored. That is, if the file is documented as being 872 bytes per line, receiving a file with 984 bytes per line should not disrupt your processing. This applies to both Header and Content lines.

File Name Disclaimer
The date in file name should be used as a guideline for human eyes only. Any date-related programmatic dependencies should rely on the FileCreatedDate or FileEffectiveDate contained within the header line of each file, as these will be precise to the second and will be in the appropriate timezone.

Header Row

Property

Data Type (Length)

Alignment

Start Position

Description

RecordType

string (1)

Left

1

The flag for the header row. Will always be H.

FileName

string (50)

Left

2

The name of this request file excluding path.
Format: yyyyMMddhhmm_BULKTRANSFERINITIATE.TXT
Example: 201410270810_BULKTRANSFERINITIATE.TXT

RecordCount

integer (10)

Right

52

The number of records represented within the file. This field is zero-padded on the left side.
Example: 0000000872

FileCreatedDate

datetime (34)

Left

62

The date the file was created. Follows same format as API.
Example: 2014-10-20T10:30:31.456-05:00
See data format guidelines

FileEffectiveDate

datetime (34)

Left

96

The date to which the data in the file pertains. Follows same format as API.
Example: 2014-10-19T23:59:59.999-05:00
See data format guidelines

ReferenceId

string (50)

Left

130

A unique identifier that can be included in the header row of the Bulk Transfer Request File so it is possible to correlate the Initiate, Request, and Response files together programmatically.

Content Row

Property

Data Type (Length)

Alignment

Start Position

Description

CustomerId

integer (10)

Right

1

The unique identifier for a customer. This field is zero-padded on the left side. e.g.: 0000000872

CustomerTag

string (50)

Left

11

The client-supplied unique identifier for the customer, aka the tag property on the customer object. This may be empty as it is an optional property.

TransferDescription

string (50)

Left

61

The description for this transaction. Will always be Recurring Deposit.

TransferKind

string (3)

Left

111

The kind of transfer that should be made. Will always be RCR. Provided here so it can be easily echoed into the Bulk Transfer Request File.

TransferAmount

integer (10)

Right

114

The amount of funds to transfer. This field is zero-padded on the left side and two decimals will be assumed, e.g., 0000000832 represents an amount of $8.32.

ToAccountId

integer (10)

Right

124

The unique identifier for the account to which funds will be deposited. This field is zero-padded on the left side.
Example: 0007102519
This is NOT an account number. It is the accountId of an account object.

FromAccountId

integer (10)

Right

134

The unique identifier for the external account from which funds will be withdrawn. This field is zero-padded on the left side.
Example: 0008309285
This is NOT an account number. It is the 'externalAccountId` of an externalAccount object.

ToAccountTag

string (50)

Left

144

The client-supplied unique identifier for the "to" account, aka the tag property on the account object. This may be empty as it is an optional property.

FromAccountTag

string (50)

Left

194

The client-supplied unique identifier for the "from" account, aka the tag externalAccount object. This may be empty as it is an optional property.

ToAccountName

string (50)

Left

244

The name of the "to" account, aka the name property of the account object.

FromAccountName

string (50)

Left

294

The name of the "from" account, aka the name property on the externalAccount object.