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

90

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.bhengagement.com|John Doe|[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.

Value is always 1 for individual eGift and Virtual quotes.

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 dollar amount for the eGift or Virtual Prepaid card.

8

RecipientEmail

String

50

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|John Doe|[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|John Doe|[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 the standard two-character uppercase abbreviation for a U.S. state

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 is required and cannot exceed 50 characters

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 or a Canadian province or contain an international region less than 36 character

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 90 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


Did this page help you?