Bulk Transfer Process
The Bulk Transfer Process is essentially a batch version of calling /transfer/create
repeatedly. To issue several requests to transfer funds, please use this process. Throttling mechanisms exist in the CorePro API to ensure timely responses. See Batch Processing Overview for more information.
Basic Workflow
- You upload a
Bulk Transfer Request File
- CorePro processes it, then uploads a
Bulk Transfer Response File
containing the results.
Detailed Workflow
- You upload a properly formatted
Bulk Transfer Request File
tosftp.corepro.io
- Later that same day, CorePro calls the
/transfer/create
functionality for each content row in the file, but in a vastly more efficient manner - CorePro then writes the results to a
Bulk Transfer Response File
and uploads it tosftp.corepro.io
- You inspect this response file for success and failed counts, and process accordingly.
NOTE: Only failed transactions will appear in the content section of the response file
Bulk Transfer Request File Definition
This is a file created by the client to perform the equivalent of several requests to the /transfer/create
service. Multiple files per day can be processed, typically on an hourly basis. It has the following properties:
- Fixed-length. Header row is 179 bytes excluding line endings. Each content row is 398 bytes excluding line endings.
- ANSI encoded
- Line endings are Windows-style CarriageReturn + LineFeed (
\r\n
, or0x0D0A
) - A client-specific location will be provided on
sftp.corepro.io
for uploading this file. - File must be uploaded to the relative directory of
/BulkTransfer/Request
-
File name follows a specific, case-insensitive pattern of:
yyyyMMddhhmm_BulkTransfer.txt
- The date in the file name should be the creation date of the file.
- For example, if the file name is
201501080015_BulkTransfer.TXT
, the data it contains will apply to Jan 8 2015. - The header record contains an
EffectiveDate
field. This should be the same value as theCreatedDate
field. - Root-relative path on
sftp.corepro.io
for that file would be:/BulkTransfer/Request/201501080015_BulkTransfer.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 | 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. Should be named following this pattern:
|
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 client-supplied unique identifier that will be included in the header row of the response file after CorePro has processed this file. This allows correlation of the request and response files. |
Content Row
Property | 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 NOTE: One of CustomerId or CustomerTag must be specified. |
CustomerTag |
string (50) | Left | 11 |
The client-supplied unique identifier for the customer. If omitted, simply pass as 50 spaces. NOTE: One of CustomerId or CustomerTag must be specified.
|
TransferTag |
string (50) | Left | 61 | The client-supplied unique identifier for the transaction that will be created. This value is optional and will be written to the tag property of the transaction . If omitted, simply pass as 50 spaces. |
TransferKind |
string (3) | Left | 111 | The kind of transfer to perform. This is only applicable to transactions created via this file. See below for valid values:
|
TransferAmount |
integer (10) | Right | 114 | The amount of funds to transfer from the FromAccountId to the ToAccountId . 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 accountId of an account object or an externalAccountId of an externalAccount 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.
|
NachaDescription |
string (255) | left | 144 |
Client-specified text describing the transfer. It will be stored as the nachaDescription on the transaction object.
|
Example Bulk Transfer Request File
Content: See 201508170003_BULKTRANSFER.TXT
NOTE: Your browser or text editor may wrap the text to fit the window. Actual source file does not wrap.
Bulk Transfer Response File Definition
This is a file created by Social Money after CorePro processes a Bulk Transfer Request File. Multiple files per day can be processed, typically on an hourly basis. It has the following properties:
- Fixed-length. Header row is 209 bytes excluding line endings. Each content row is 863 bytes excluding line endings.
- ANSI encoded
- Line endings are Windows-style CarriageReturn + LineFeed (
\r\n
, or0x0D0A
) - A client-specific location will be provided on
sftp.corepro.io
for downloading this file. - File will appear in the relative directory of
/BulkTransfer/Response
- File name follows a specific, case-sensitive pattern of:
yyyyMMddhhmm_BULKTRANSFERRESPONSE.TXT
- NOTE: This file is an exception in the naming convention used by other files. The date in the file name is the exact same date as the one in the corresponding
Bulk Transfer Request File
. It is NOT theCreatedDate
of the file. - For example, if the
Bulk Transfer Request File
name is201501080015_BulkTransfer.txt
, the response file name will be 201501080015_BULKTRANSFERRESPONSE.TXT regardless of the actualCreatedDate
orEffectiveDate
. - Root-relative path on
sftp.corepro.io
for that file would be:/BulkTransfer/Response/201501080015_BULKTRANSFERRESPONSE.TXT
- NOTE: This file is an exception in the naming convention used by other files. The date in the file name is the exact same date as the one in the corresponding
- Only failed transactions will appear in the Content Row section. Successful transactions will not be represented with a content row, but will be included in the
SuccessCount
tally.
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 | 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:
|
RecordCount |
integer (10) | Right | 52 | The number of Content lines in this file. Should always match the FailedCount as this file contains only failed transfers.NOTE: This field is zero-padded on the left side. e.g.: 0000000003 |
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 | The client-supplied unique identifier that was supplied in the corresponding request file. |
SuccessCount |
integer (10) | Right | 180 | The number of records successfully processed by CorePro. NOTE: This field is zero-padded on the left side. e.g.: 0000000001 |
FailedCount |
integer (10) | Right | 190 | The number of records that failed processing by CorePro. NOTE: This field is zero-padded on the left side. e.g.: 0000000002 |
ProcessedCount |
integer (10) | Right | 200 | The number of records processed (either successfully or unsuccessfully) by CorePro. Should always match the number of content rows in the corresponding request file. NOTE: This field is zero-padded on the left side. e.g.: 0000000003 |
Content Row
Property | 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.
|
TransferTag |
string (50) | Left | 61 | The client-supplied unique identifier for the failed transfer. |
TransferKind |
string (3) | Left | 111 |
The kind of transfer that failed. See below for valid values:
|
TransferAmount |
integer (10) | Right | 114 |
The amount of funds to transfer from the FromAccountId to the ToAccountId . 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 accountId of an account object or an externalAccountId of an externalAccount 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.
|
NachaDescription |
string (255) | Left | 344 |
The client-specified text describing this transfer which was supplied in the NachaDescription of the corresponding Request File.
|
ErrorNumber |
string (10) | Right | 599 | Error number that occurred while processing the transfer. See /transfer/create for details. NOTE: If multiple errors exist for a transfer, only the first error will be returned. This field is zero-padded on the left side. e.g.: 0000060101 |
ErrorMessage |
string (255) | Left | 609 | The CorePro-generated error description for a failed transfer request. This message may be culture-aware. NOTE: If multiple errors exist for a transfer, only the first error will be returned. |
Example Bulk Transfer Response File
Content: See 201508170003_BULKTRANSFERRESPONSE.TXT
NOTE: Your browser or text editor may wrap the text to fit the window. Actual source file does not wrap.