API Documentation

[Mobile] Table of Contents:

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

  1. CorePro 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.

Workflow

  1. 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.

  2. 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

       

  3. 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
  • 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:
  1. Download the 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.

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:

  1. Fixed-length. Header row is 179 bytes excluding line endings. Each content row is 343 bytes excluding line endings.
  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 appear in the relative directory of /BulkTransfer/Initiate
  6. File name follows a specific, case-sensitive pattern of: yyyyMMddhhmm_BULKTRANSFERINITIATE.TXT
  7. 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:
  1. yyyyMMddhhmm_BULKTRANSFERINITIATE.TXT
  2. 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 accountIdof 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.

Ready to start a conversation?

Email Us