API Documentation

Recurring Contribution Process

The CorePro API 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 CorePro on the following day.

Process Overview

CorePro generates a Bulk Transfer Initiate File
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.

Workflow

Every day, the CorePro Recurring Contribution process will determine which accounts have contributions scheduled to happen on the following day.
An Initiate File is generated by CorePro and uploaded to sftp.corepro.io. This file will contain all basic information needed for you to create a Request File for upload the following day.

NOTE: No further action is performed in CorePro at this point without receiving a subsequent Request File.
i.e. no transaction is ever created in CorePro as part of the Initiate File generation process and it will not appear in the customer's transaction list. A transaction is created only when the Request File is received and processed by CorePro.
Your system downloads the Initiate File from sftp.corepro.io and processes it.
Your processing should involve investigating the Initiate File and processing it accordingly. Some examples include:
- Create transactions in your system to denote the actual transaction which will take place the following day (assuming you upload the Request File)
- Contact customers via email or SMS to notify them their recurring contribution will happen the next day, giving them a chance to cancel it
- Simply log the data for future use
Follow the Bulk Transfer Process to actually transfer 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
- i.e. All Content rows that are in the Initiate File will always appear in the corresponding Request File
Your code does not need to populate the TransferTag field with a specific value when performing transfers via the Request File
- i.e. Nowhere does any of your code depend upon the tag property of the transaction object being populated

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

Download the Initiate File. Suppose its name is 201401152209_BULKTRANSFERINITIATE.TXT
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.

NOTE: 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

This is a file created by CorePro to notify the client of deposits that should occur automatically on the following day. It has the following properties:

Fixed-length. Header row is 179 bytes excluding line endings. Each content row is 343 bytes excluding line endings.
ANSI encoded
Line endings are Windows-style CarriageReturn + LineFeed (\r\n, or 0x0D0A)
A client-specific location will be provided on sftp.corepro.io for downloading this file.
File will appear in the relative directory of /BulkTransfer/Initiate
File name follows a specific, case-sensitive pattern of: yyyyMMddhhmm_BULKTRANSFERINITIATE.TXT
Root-relative path on sftp.corepro.io for a file of this kind would be: /BulkTransfer/Initiate/201501080015_BULKTRANSFERINITIATE.TXT

Format Disclaimer
Social Money 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 file excluding path. Will be named following this pattern: `yyyyMMddhhmm_BULKTRANSFERINITIATE.TXT` Example: 201410270810_BULKTRANSFERINITIATE.TXT
`RecordCount`	integer (10)	Right	52	The number of records represented within the file. NOTE: This field is zero-padded on the left side. e.g.: `0000000872`
`FileCreatedDate`	datetime (34)	Right	62	The date the file was created. Follows same format as API e.g.: `2014-10-20T10:30:31.456-05:00`. See `date format details`.
`FileEffectiveDate`	datetime (34)	Right	96	The date to which the data in the file pertains. Follows same format as API e.g.: `2014-10-20T23:59:59.999-05:00`. See `date format details`.
`ReferenceId`	string (50)	Left	130	A unique identifier that could 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. NOTE: 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. NOTE: 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. NOTE: This field is zero-padded on the left side. e.g.: `0007102519` This is NOT an `accountNumber`. It is the `externalAccountId` of an `externalAccount` object or the `accountId` of an `account` object.
`FromAccountId`	integer (10)	Right	134	The unique identifier for the account from which funds will be withdrawn. NOTE: This field is zero-padded on the left side. e.g.: `0008309285` This is NOT an `accountNumber`. It is the `accountId`of an `account` 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` property on the `account` or `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 `externalAccount` object.
`FromAccountName`	string (50)	Left	294	The name of the "from" account, aka the `name` property on the `account` or `externalAccount` object.

Example Bulk Transfer Initiate File

Content: See 201508310901_BULKTRANSFERINITIATE.TXT
NOTE: Your browser or text editor may wrap the text to fit the window. Actual source file does not wrap.