The Q2 CorePro Developer Hub

Welcome to the Q2 CorePro developer hub. You'll find comprehensive guides and documentation to help you start working with the CorePro API as quickly as possible.

Get Started    

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

  1. You upload a Bulk Transfer Request File
  2. CorePro processes it then uploads a Bulk Transfer Response File containing the results

Detailed Workflow

  1. You upload a properly formatted Bulk Transfer Request File to sftp.corepro.io
  2. Later that same day CorePro calls the /transfer/create functionality for each content row in the file, but in a vastly more efficient manner
  3. CorePro writes the results to a Bulk Transfer Response File and uploads it to sftp.corepro.io
  4. 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:

  1. Fixed-length
  2. ANSI endocded
  3. Line endings are Windows-style CarriageReturn + LineFeed (\r\n, or 0x0D0A)
  4. File must be uploaded to the relative directory of /BulkTransfer/Request
  5. 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 the CreatedDate field.

🚧

Format Disclaimer
Q2 Open 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.
Format: yyyyMMddhhmm_BULKTRANSFER.txt
Example: 201407162348_BULKTRANSFER.txt

NOTE: This is for informational purposes on our end only; it is entirely optional. Any programmatic dependencies in CorePro will look at the actual file name, not the value in this field. i.e. if the file name and the value in this field do not match, it will not cause issues. This anomaly is to support the Recurring Contribution Simplified Workflow.

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-20T23:59:59.999-05:00
See data format guidelines

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

Data Type (Length)

Alignment

Start Position

Description

CustomerId

integer (10)

Right

1

The CorePro-assigned unique ID for a customer. This field is zero-padded on the left side.
Example: 0000000872
NOTE: Either 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: Either 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. Possible values:

  • TRF: A one-time transaction
  • RCR: A recurring transaction

TransferAmount

integer (10)

Right

114

The amount of funds to transfer from the FromAccountId to the ToAccountId. 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 bank 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 or an externalAccountId of an externalAccount object.

FromAccountId

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.
Example: 0008309285
This is NOT an account number . It is the accountId of an account object or an externalAccountId of an externalAccount object.

NachaDescription

string (255)

left

144

Client-specified text describing the transfer. It will be stored as the nachaDescription on the transaction object.


Bulk Transfer Response File Definition

The Bulk Transfer Response File is created by CorePro after CorePro processes a Bulk Transfer Request File. It has the following properties:

  1. Fixed-length
  2. ANSI encoded
  3. Line endings are Windows-style CarriageReturn + LineFeed (\r\n, or 0x0D0A)
  4. File will appear in the relative directory of /BulkTransfer/Response
  5. 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 be 201501080015_BULKTRANSFERRESPONSE.TXT regardless of the actual CreatedDate or EffectiveDate
  6. 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
Q2 Open 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.
Format: yyyyMMddhhmm_BULKTRANSFERRESPONSE.TXT
Example: 201407162348_BULKTRANSFERRESPONSE.TXT
NOTE: File name will not contain the CreatedDate. It will consist of the same file name as the Bulk Transfer Request File that caused this file to be generated but with "RESPONSE" appended to the end of the file name prior to the file extension.

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. This field is zero-padded on the left side.
Example: 0000000003

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-20T23:59:59.999-05:00
See data format guidelines

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. This field is zero-padded on the left side.
Example: 0000000001

FailedCount

integer (10)

Right

190

The number of records that failed processing by CorePro. This field is zero-padded on the left side.
Example: 0000000003

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. This field is zero-padded on the left side
Example: 0000000003

Content Row

Property

Data Type (Length)

Alignment

Start Position

Description

CustomerId

integer (10)

Right

1

The CorePro-assigned unique ID for a customer. This field is zero-padded on the left side.
Example: 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. Possible values:

  • TRF: A one-time transaction
  • RCR : A recurring transaction

TransferAmount

integer (10)

Right

114

The amount of funds to transfer from the FromAccountId to the ToAccountId. 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 bank 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 or an externalAccountId of an externalAccount object.

FromAccountId

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.
Example: 0008309285
This is NOT an account number. It is the accountId of an account object or an 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 or externalAccount 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 account or 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.
If multiple errors exist for a transfer only the first error will be returned. This field is zero-padded on the left side.
Example: 0000060101

ErrorMessage

string (255)

Left

609

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

Updated 4 months ago

Bulk Transfer Process


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.