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 Helix API to ensure timely responses. See Batch Processing Overview for more information.
Basic Workflow
- You upload a Bulk Transfer Request File
- Helix processes it then uploads a Bulk Transfer Response File containing the results
Detailed Workflow
- You upload a properly formatted Bulk Transfer Request File to
sftp.corepro.io
- Later that same day Helix calls the /transfer/create functionality for each content row in the file, but in a vastly more efficient manner
- Helix writes the results to a Bulk Transfer Response File and uploads it to
sftp.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
The Bulk Transfer Request File is a file created by the client to perform the equivalent of several requests to the /transfer/create endpoint. Multiple files per day can be processed, typically on an hourly basis. It has the following properties:
- Fixed-length
- ANSI endocded
- Line endings are Windows-style CarriageReturn + LineFeed (
\r\n
, or0x0D0A
) - 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.
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 theFileCreatedDate
orFileEffectiveDate
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 |
---|---|---|---|---|
Record Type | string (1) | Left | 1 | The flag for the header row. Will always be |
File Name | string (50) | Left | 2 | The name of this file excluding path.
|
Record Count | integer (10) | Right | 52 | The number of records represented within the file. This field is zero-padded on the left side. |
File Created Date | datetime (34) | Left | 62 | The date the file was created. Follows same format as API. |
File Effective Date | datetime (34) | Left | 96 | The date to which the data in the file pertains. Follows same format as API. Example: |
Reference ID | string (50) | Left | 130 | A client-supplied unique identifier that will be included in the header row of the response file after Helix has processed this file. This allows correlation of the request and response files. |
Content Row
Property | Data Type (Length) | Alignment | Start Position | Description |
---|---|---|---|---|
Customer ID* | integer (10) | Right | 1 | The Helix-assigned unique ID for a customer. This field is zero-padded on the left side.
|
Customer Tag | string (50) | Left | 11 | The client-supplied unique identifier for the customer. If omitted, simply pass as 50 spaces.
|
Transfer Tag | 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 |
Transfer Kind | string (3) | Left | 111 | The kind of transfer to perform. This is only applicable to transactions created via this file. Possible values:
|
Transfer Amount | integer (10) | Right | 114 | The amount of funds to transfer from the |
To Account ID | integer (10) | Right | 124 | The unique identifier for the bank account to which funds will be deposited. This field is zero-padded on the left side. |
From Account ID | integer (10) | Right | 134 | The unique identifier for the bank account from which funds will be withdrawn. This field is zero-padded on the left side. |
Nacha Description | string (255) | left | 144 | Client-specified text describing the transfer. It will be stored as the |
To Customer ID | integer (10) | Right | 399 | The Helix-assigned unique ID for a customer. This field is zero-padded on the left side.
|
To Customer Tag | string (50) | Left | 409 | The client-supplied unique identifier for the customer. If omitted, simply pass as 50 spaces.
|
To Transfer Tag | string (50) | Left | 459 | The client-supplied unique identifier for the transaction that will be for against the receiving account. This value is optional and will be written to the |
Take me to the Example Bulk Transfer Request File
Bulk Transfer Response File Definition
The Bulk Transfer Response File is created by Helix after Helix processes a Bulk Transfer Request File. It has the following properties:
- Fixed-length
- ANSI encoded
- Line endings are Windows-style CarriageReturn + LineFeed (
\r\n
, or0x0D0A
) - File will appear in the relative directory of
/BulkTransfer/Response
- File name follows a specific, case-sensitive pattern of:
yyyyMMddhhmm_BULKTRANSFERRESPONSE.TXT
- 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 the
CreatedDate
of the file. - For example, if the Bulk Transfer Request File name is
201501080015_BULKTRANSFER.txt
, the response file name will be201501080015_BULKTRANSFERRESPONSE.TXT
regardless of the actualCreatedDate
orEffectiveDate
- 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 the
- 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
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 theFileCreatedDate
orFileEffectiveDate
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 |
---|---|---|---|---|
Record Type | string (1) | Left | 1 | The flag for the header row. Will always be |
File Name | string (50) | Left | 2 | The name of this file excluding path.
|
Record Count | integer (10) | Right | 52 | The number of Content lines in this file. Should always match the |
File Created Date | datetime (34) | Left | 62 | The date the file was created. Follows same format as API. |
File Effective Date | datetime (34) | Left | 96 | The date to which the data in the file pertains. Follows same format as API. Example: |
Reference ID | string (50) | Left | 130 | The client-supplied unique identifier that was supplied in the corresponding request file. |
Success Count | integer (10) | Right | 180 | The number of records successfully processed by Helix. This field is zero-padded on the left side. |
Failed Count | integer (10) | Right | 190 | The number of records that failed processing by Helix. This field is zero-padded on the left side. |
Processed Count | integer (10) | Right | 200 | The number of records processed (either successfully or unsuccessfully) by Helix. Should always match the number of content rows in the corresponding request file. This field is zero-padded on the left side |
Content Row
Property | Data Type (Length) | Alignment | Start Position | Description |
---|---|---|---|---|
Customer ID | integer (10) | Right | 1 | The Helix-assigned unique ID for a customer. This field is zero-padded on the left side. |
Customer Tag | string (50) | Left | 11 | The client-supplied unique identifier for the customer, aka the |
Transfer Tag | string (50) | Left | 61 | The client-supplied unique identifier for the failed transfer. |
Transfer Kind | string (3) | Left | 111 | The kind of transfer that failed. Possible values:
|
Transfer Amount | integer (10) | Right | 114 | The amount of funds to transfer from the |
To Account ID | integer (10) | Right | 124 | The unique identifier for the bank account to which funds will be deposited. This field is zero-padded on the left side. |
From Account ID | integer (10) | Right | 134 | The unique identifier for the bank account from which funds will be withdrawn. This field is zero-padded on the left side. |
To Account Tag | string (50) | Left | 144 | The client-supplied unique identifier for the "to" account, aka the |
From Account Tag | string (50) | Left | 194 | The client-supplied unique identifier for the "from" account, aka the |
To Account Name | string (50) | Left | 244 | The name of the "to" account, aka the |
From Account Name | string (50) | Left | 294 | The name of the "from" account, aka the |
Nacha Description | string (255) | Left | 344 | The client-specified text describing this transfer which was supplied in the |
Error Number | string (10) | Right | 599 | Error number that occurred while processing the transfer. See /transfer/create for details. |
Error Message | string (255) | Left | 609 | The Helix-generated error description for a failed transfer request. This message may be culture-aware. If multiple errors exist for a transfer, only the first error will be returned. |
Take me to the Example Bulk Transfer Response File
Updated 16 days ago