FTP File Format - Digital
Introduction
This document provides an overview of the FTP File Format used to submit eGift and Virtual Open Loop orders to Blackhawk Network’s Hawk Marketplace Platform.
-
Order File: This file contains the orders to be placed and is uploaded to Blackhawk Network’s FTP server.
-
Success File: This file is created by Blackhawk Network as a confirmation the order was processed successfully.
-
Exception File: This file is created by Blackhawk Network as a confirmation that the order contained invalid records. Invalid records must be corrected and the entire order file resent to Blackhawk Network for processing.
-
Bulk Return File: This file is created by Blackhawk Network and contains eGift URL’s that the client sends to their recipients. This file is only produced for bulk eGift orders and is not supported for Virtual Open Loop orders.
Blackhawk Network recommends a maximum of 5,000 order line items per order file. If you have more than 5,000 line items you will need to break your order into multiple order files of 5,000 records each.
Order File Spec Summary
The client creates an order file with consumer information and other relevant data and uploads it to the Hawk Marketplace FTP server. The format of the file is described in the following section.
Note: Separate files must be provided for bulk and individual orders.
Source: Client
Destination: Blackhawk Network
File Name Convention:
- _YYYYMMDDHHmmSS.txt
- Client - name of the client
- QuoteNumber - quote number provided by the account manager.
- YYYY - four digit year.
- MM - two digit month.
- DD - two digit day.
- HH - two digit hour of the day.
- mm - two digit minute of the hour.
- SS - two digit second of the minute.
Example: Client_ 42480501_INDIVIDUAL_20141124135222.txt
Delimiter used: Pipe Symbol (‘|’)
Order File Spec Structure
File Header Record: This record denotes the Order File Header and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | File Header | String | 6 | Yes | Allowed: HEADER | |
2 | FileName | String | N/A | Yes | Allowed: File naming convention of the order file | This is the name of the fulfillment file. |
3 | DeliveryType | String | 10 | Yes | Allowed: INDIVIDUAL or BULK | This is the delivery type for all the records in the order files. Note that BULK is only supported for eGift orders and cannot be used when ordering Virtual Open Loop. |
HEADER|BlackhawkNetwork_12345_BULK_20190917140601.txt|BULK
File Email Content Record: This record denotes the Email Content for the order and has the following format.
*This record only appears once in the file.
*This record is not used for Bulk orders.
This row is required when the
deliveryType
is INDIVIDUAL only. It should not be sent for BULK.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | EmailContent | String | 6 | No | Allowed Values: EMAILCONTENT | |
2 | CompanyName | String | 50 | No | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces, period (.), comma (,), forward slash (/), dash (-), and ampersand (&) , single quote (‘) | This is the client’s company name. |
3 | AddressLine1 | String | 200 | No | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces, period (.), comma (,), forward slash (/), dash (-), and ampersand (&) , single quote (‘) | This is the client’s address information. |
4 | AddressCity | String | 100 | No | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces, period (.), comma (,). | This is the client’s address information. |
5 | AddressState | String | 2 | No | Allowed Values: Alpha (a-z, A-Z) | This is the client’s address information. |
6 | AddressZip | US: Number Canada: String | USA: 5 Canada: 6 | No | Allowed Values: Digits (0-9), Alpha (a-z, A-Z) | This is the client’s address information. |
7 | AddressCountry | String | 13 | No | Allowed Values: UNITED STATES or CANADA | This is the client’s address information. |
8 | Method | String | 7 | No | Allowed Values: EMAIL or WEBSITE | This is the client’s unsubscribe method. |
9 | Value | String | 256 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), period (.),forward slash (/), colon(:) and spaces. If “Method” is email then Format: Must have an @ symbol and at least one dot. | This is the client’s unsubscribe value. |
10 | SenderName | String | 50 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces. | This is the name that appears in the recipient inbox. |
11 | SenderEmail | String | 254 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces. Format: Must have an @ symbol and at least one dot. | This is the email address that appears in the recipient inbox. |
12 | Subject | String | 200 | No | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces, period (.), comma (,), forward slash (/), dash (-), and ampersand (&) , single quote (‘) | This is the subject that will appear on the eGift. |
13 | EmailClosingName | String | 200 | No | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces, period (.), comma (,), forward slash (/), dash (-), and ampersand (&) , single quote (‘) | This is the closing signature for the email. |
14 | EmailMessage | String | N/A | No Not used for Bulk eGift orders | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), period (.) and spaces. | This is the custom message that will appear on the email. |
EMAILCONTENT|Acme|1400 S Hwy Dr.|Fenton|MO|63099|UNITED STATES|WEBSITE|http://www.blackhawknetwork.com|Blackhawk Network|[email protected]|Great Job|John|Thanks for all the hard work in 2015.
File Detail Record: This record denotes the Order File Detail and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Detail | String | 6 | No | Allowed Values: DETAIL | |
2 | QuoteNumber | Number | 17 | Yes | Allowed: Digits 0 - 9. | This is the quote number provided by the account manager. |
3 | PIDNumber | String | 30 | Yes | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), period (.) and comma (,). | This is a unique number that should not be reused for a quote number. |
4 | FirstName | String | 25 | Yes, for personalized quotes. *Not used for Bulk orders | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), space ( ), period (.), comma (,), hyphen (-), forward slash (/) and apostrophe ( ' ). | This is the recipient’s first name. |
5 | LastName | String | 25 | Yes, for personalized quotes. *Not used for Bulk orders | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), space ( ), period (.), comma (,), hyphen (-), forward slash (/) and apostrophe ( ' ). | This is the recipient’s last name. |
6 | Quantity | Number | N/A | Yes | Allowed Values: Digits 0 - 9 (minimum value 1) For Individual eGift and Virtual card delivery the quantity will always be 1. Values greater than 1 will be ignored and a single card will be processed and issued. | This is the number being ordered. |
7 | TransactionAmount | Decimal | 7,2 | Yes | Allowed Values: Digits 0 – 9 and period (.). Funding amount may not contain symbols (i.e. "$", "-", "()") and can have at most two digits after decimal separator. | This is the denomination (face value) for the eGift or Virtual Prepaid card. For example: If you are ordering a $50 eGift, this would contain the value 50. |
8 | RecipientEmail | String | 254 | Yes, for personalized quotes. *Not used for Bulk orders | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces. Format: Must have an @ symbol and at least one dot. | This is the recipient’s email. |
9 | IndicativeData1 | String | 17 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces | This is a custom field that will be returned on the shipping file. |
10 | IndicativeData2 | String | 17 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces | This is a custom field that will be returned on the shipping file. |
11 | IndicativeData3 | String | 17 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces | This is a custom field that will be returned on the shipping file. |
12 | IndicativeData4 | String | 17 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces | This is a custom field that will be returned on the shipping file. |
13 | IndicativeData5 | String | 17 | No | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), and spaces | This is a custom field that will be returned on the shipping file. |
14 | ContentProviderCode | String | 118 | Yes - eGift No - Virtual Open Loop | Allowed Values: Digits 0 – 9 and Alpha (a-z, A-Z). | This field specifies the eGift being ordered for this record. |
Content Provider Code for Virtual Open Loop
The ContentProviderCode should be left blank when ordering Virtual Open Loop products but must be provided when ordering eGifts.
File Trailer Record: This record denotes the Order File Trailer and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Trailer | String | 7 | Yes | Allowed: TRAILER | |
2 | RecordCount | Number | N/A | Yes | Allowed: Digits 0-9. | This is the number of detail records in the order file. |
TRAILER|20
Sample Order Files
Individual eGift
HEADER|Client_42480501_INDIVIDUAL_20141124135222.txt|INDIVIDUAL
EMAILCONTENT|Acme|1400 S Hwy Dr.|Fenton|MO|63099|UNITED STATES|WEBSITE|http://www.blackhawknetwork.com|Blackhawk Network|[email protected]|Great Job|John|Thanks for all the hard work in 2020.
DETAIL|42480401|0001|John|Sample|1|25.00|[email protected]|IndicativeData1|IndicativeData2|IndicativeData3|IndicativeData4|IndicativeData5|FootLocker
TRAILER|1
Individual Virtual Open Loop (no content provider code)
HEADER|Client_42480501_INDIVIDUAL_20141124135222.txt|INDIVIDUAL
EMAILCONTENT|Acme|1400 S Hwy Dr.|Fenton|MO|63099|UNITED STATES|WEBSITE|http://www.blackhawknetwork.com|Blackhawk Network|[email protected]|Great Job|John|Thanks for all the hard work in 2020.
DETAIL|42480401|0001|John|Sample|1|25.00|[email protected]|IndicativeData1|IndicativeData2|IndicativeData3|IndicativeData4|IndicativeData5|
TRAILER|1
Bulk eGift
HEADER|Client_42480501_BULK_20141124135222.txt|BULK
DETAIL|42480501|0002|||100|25.00||IndicativeData1|IndicativeData2|IndicativeData3|IndicativeData4|IndicativeData5|FootLocker|||||||||||||
TRAILER|1
Success File Spec Summary
Blackhawk Network generates a success acknowledgement for valid order files. The format of the file is described in the following section.
Source: Blackhawk Network
Destination: Client
File Name Convention:
- _Success.txt
- Order File Name – file name of the order being processed
- Success – static value in file name.
Example: Client_42480501_INDIVIDUAL_20141124135222_Success.txt
Delimiter: Pipe Symbol (‘|’)
Success File Spec Structure
File Header Record: This record is the Success File Header and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Header | String | 6 | Yes | Allowed Value: HEADER | |
2 | FileName | String | N/A | Yes | Allowed Value: File naming convention of success file. | This is the name of the success file |
HEADER|Client_20141124_1_Order_Success.txt
File Detail Record: This record denotes the Success File Detail and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Status | String | 7 | Yes | Allowed Values: SUCCESS | |
2 | OrderNumber | Number | N/A | Yes | Allowed: Digits 0 - 9. | This is the order number produced by Blackhawk's ordering system. |
3 | QuoteNumber | Number | N/A | Yes | Allowed Values: Digits 0 - 9. | This is the quote number provided by the account manager. |
4 | OrderFileName | String | N/A | Yes | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces and period (.) | This is the file name of the submitted order. |
File Trailer Record: This record denotes the Success File Trailer and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Trailer | String | 7 | Yes | Allowed Values: TRAILER | |
2 | RecordCount | Number | N/A | Yes | Allowed Values: Digits 0-9. | This is the number of detail records in the completion file |
TRAILER|20
Sample Success File
HEADER|Client_42480501_INDIVIDUAL_20141124135222_Success.txt
SUCCESS|100005830|42480501|Client_42480501_201411241352.txt
TRAILER|1
Bulk eGift Return File Summary
eGift Only!
This section is only applicable to bulk eGift orders. Virtual Open Loop cannot use the bulk ordering method.
Blackhawk Network generates a return file that contains eGift URLs for bulk orders. The format of the file is described in the following section.
Source: Blackhawk Network
Destination: Client
File Name Convention:
- __ReturnFile_YYYYMMDD.txt
- Client – name of the client
- OrderNumber – BES order number associated to the eGift URLs.
- ReturnFile – static value in file name.
- YYYY – four digit year.
- MM – two digit month.
- DD – two digit day.
Example: Client_100005830_ReturnFile_20141124.txt
Delimiter used: Pipe Symbol (‘|’)
Return File Spec Structure
File Header Record: This record is the Return File Header and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Header | String | 6 | Yes | Allowed: HEADER | |
2 | FileName | String | N/A | Yes | Allowed Value: File naming convention of exception file. | This is the name of the return file. |
File Detail Record: This record denotes the ReturnFile Detail and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Detail | String | 6 | No | Allowed Values: DETAIL | |
2 | OrderNumber | Number | N/A | Yes | Allowed: Digits 0 - 9. | This is the order number produced by Hawk Marketplace. |
3 | QuoteNumber | Number | 17 | Yes | Allowed: Digits 0 - 9. | This is the quote number provided by the account manager. |
4 | TransactionAmount | Decimal | 7,2 | Yes | Allowed Values: Digits 0 – 9 and period (.). Funding amount may not contain symbols (i.e. "$", "-", "()") and can have at most two digits after decimal separator. | This is the dollar amount for the eGift. |
5 | URL | String | N/A | Yes | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), period (.),equals (=),ampersand(&), forward slash(/), dash(-) and question mark (?). | This is egift URL that the client will send to the recipient. |
File Trailer Record: This record is the Return File Trailer and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Trailer | String | 7 | Yes | Allowed Values: TRAILER | |
2 | RecordCount | Number | N/A | Yes | Allowed Values: Digits 0-9. | This is the number of records in the file. |
TRAILER|20
Sample Return File
HEADER|Client_100005830_ReturnFile_20141124.txt
DETAIL|100005830|42480401|55.00|https://activationspotpp.blackhawk-net.com/egift.aspx?tid=S6AF2JZZWW23CL5L70H9HG1Y0W&gcm=n&gs=n&gw=n&eid=8LVYSH2CZCK7JAYB00Z4FZW6N8
TRAILER|1
Exception File Spec Summary
Blackhawk Network generates an exception acknowledgement for invalid records within the order file. The format of the file is described in the following section.
Source: Blackhawk Network
Destination: Client
File Name Convention:
- _Err.txt
- Order File Name – file name of the order being processed
- Err – static value in file name.
Example: Client_42480501_INDIVIDUAL_20141124135222_Err.txt
Delimiter used: Pipe Symbol (‘|’)
Exception File Spec Structure
File Header Record: This record is the Exception File Header and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Header | String | 6 | Yes | Allowed: HEADER | |
2 | FileName | String | N/A | Yes | Allowed Value: File naming convention of exception file. | This is the name of the exception file. |
HEADER|Client_20141124_1_Err.txt
File Detail Record: This record denotes the Exception File Detail and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Status | String | 5 | Yes | Allowed Values: ERROR | |
2 | ColumnName | String | 100 | Yes | Allowed: Alpha, Digits 0 – 9, Spaces | This is the name of the column that contains the error. |
3 | ErrorDescriptionCode | String | 3 | Yes | Allowed Values: Digits 0 – 9 | This is an error code that is used to look up the error description. The error table listed below. |
4 | CardholderPIDNumber | String | 30 | Yes | Allowed Values: Digits 0 – 9, Alpha (a-z, A-Z), period (.) and comma (,). | This is a unique number that was provided in the order file. |
5 | QuoteNumber | Number | 17 | Yes | Allowed: Digits 0 - 9. | This is the quote number provided by the Blackhawk Network account manager. |
6 | OrderFileName | String | N/A | Yes | Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces and period (.) | This is the file name of the submitted order. |
File Trailer Record: This record is the Exception File Trailer and has the following format.
Index | Name of Parameter | Data Type | Size | Required | Validation Rules | Description |
---|---|---|---|---|---|---|
1 | Trailer | String | 7 | Yes | Allowed Values: TRAILER | |
2 | RecordCount | Number | N/A | Yes | Allowed Values: Digits 0-9. | This is the number of records in the file |
TRAILER|20
HEADER|Client_42480501_INDIVIDUAL_20141124135222_Err.txt
ERROR|Demo_First_Name|465|0001|42480501|Client_42480501_201411241352.txt
TRAILER|1
Exception Codes and Messages
Code | Message | Data Field |
---|---|---|
000 | An error occurred processing the file. Please contact BES. | File Error |
001 | No data found in order file. | File Error |
002 | Transaction_Amount missing. | TransactionAmount |
004 | File format is incorrect. Please refer to BES FTP documentation. | File Format |
005 | Duplicate order file submitted. Please rename file and submit order again. | Duplicate File. |
006 | Invalid quote number. Please correct quote number and submit order again. | QuoteNumber |
007 | Could not process records for quote . Please contact BES. | QuoteNumber |
420 | The PID has already been used for this Quote number. | CardholderPIDNumber |
465 | [Card Holder First Name] is required and cannot exceed 25 letters. Also, allowed punctuation includes: space ( ), period (.), comma (,), hyphen (-), underscore(_), forward slash (/) and apostrophe (') | Demo_First_Name |
470 | [Card Holder Last Name] is required and cannot exceed 25 characters. Also, allowed punctuation includes: space ( ), period (.), comma (,), hyphen (-), underscore(_), forward slash (/) and apostrophe (') | Demo_Last_Name |
477 | [Email] must be a valid e-mail address | Internet_Element_1 |
620 | [Funding Amount] may not contain symbols (i.e. ""$"", ""-"", ""()"") and must be whole dollar amount. | TransactionAmount |
637 | Quantity must contain a numeric value greater than 0 | Quantity |
720 | State must be a valid 2-character uppercase abbreviation for a U.S. state, territory, or military base; or a Canadian province. | State |
723 | Your funding amount is less than the required minimum for this product. | TransactionAmount |
724 | Your funding amount exceeds the maximum allowed for this product. | TransactionAmount |
725 | Transaction_Amount missing | TransactionAmount |
863 | Email must be 254 characters or less. | InternetElement1 |
7001 | Your eGift links are being processed. Please try again once you’ve received an email indicating the order is complete. | OrderNumber |
7002 | Order details for individual distribution eGifts cannot be viewed here. Please log in at http://my.intelispend.com/orders/details/{order#} for more information, including links and email notification status. | OrderNumber |
7003 | Order {Order#} is not an eGift order. | OrderNumber |
8001 | [EmailContent/Unsubscribe_Method and EmailContent/Unsubscribe_Value] are required together and the value must match the method | UnsubscribeMethod and UnsubscribeValue |
8002 | [EmailContent/Unsubscribe_Method] is required and must be either EMAIL or WEBSITE | UnsubscribeMethod |
8003 | [EmailContent/Unsubscribe_Value] must be a valid email address OR [EmailContent/Unsubscribe_Value] cannot exceed 256 characters | UnsubscribeValue |
8004 | [EmailContent/UnsubscribeData/AddressCity] is required and cannot exceed 100 characters | Unsubscribe Address City name |
8005 | [EmailContent/UnsubscribeData/AddressCountry] is required and must either be UNITED STATES or CANADA | Unsubscribe Address Country |
8006 | [EmailContent/UnsubscribeData/AddressLine1] is required and cannot exceed 200 characters | Unsubscribe Address Line 1 |
8007 | [EmailContent/UnsubscribeData/AddressState] must be a valid 2-character uppercase abbreviation for a U.S. state, territory, or military base; a Canadian province; or contain an international region less than 36 characters. | Unsubscribe Address State/Province |
8008 | [EmailContent/UnsubscribeData/AddressZip] must be a valid 5-digit U.S. zip code or a valid international postal code less than 11 characters | Unsubscribe Address ZIP/Postal Code |
8009 | [EmailContent/UnsubscribeData/CompanyName] is required and cannot exceed 50 characters | EmailContent/UnsubscribeData/CompanyName |
8010 | [EmailContent/EmailClosingName] is required and cannot exceed 200 characters | EmailClosingName |
8011 | [EmailContent/Subject] is required and cannot exceed 256 characters | Subject |
8013 | [EmailContent/Sender Email] is not a valid email address | SenderEmail |
8014 | [EmailContent/Sender Email] is required and cannot exceed 254 characters | SenderEmail |
8015 | [EmailContent/Sender Name] is required and cannot exceed 50 characters | SenderName |
8016 | Multiple required email fields are missing. Please contact your account manager for assistance. | Email Content |
1001 | General error in placing order, potentially user/password related. | WebServiceCredentials |
Updated about 1 month ago