FTP File Format - Physical

📘

Supported Products

This file format supports ordering physical open loop prepaid and closed loop gift card products only.

Introduction

This document provides an overview of the FTP File Format used to submit orders to Blackhawk Network’s Hawk Marketplace Ordering 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.

👍

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:

  • MM_DD_YYYY.txt
  • Client – name of the client
  • MM – two digit month.
  • DD – two digit day.
  • YYYY – four digit year.
  • SQ – sequence number starts with 1 and is incremented by one every time the same file is uploaded to the FTP server.

Example: Client_12_14_2015_1.txt

Delimiter: Pipe Symbol (‘|’)

Order File Spec Structure

File Header Record

This record denotes the Order File Header and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

FileHeader

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
order file.

3

DeliveryType

String

15

Yes

Allowed:
INDIVIDUAL
BULK
BULK NO CARRIER

This is the delivery type
for all the records in the
order files.
BulkNOCarrier - Closed
Physical only

4

CardType

String

12

Yes

Allowed:
PERSONALIZED
ANONYMOUS

This is the card type for
all the records in the
order files.
Virtual/Egift will be
ordered in a separate
format.

5

OrderType

String

14

Yes

Allowed:
PREDENOMINATED
RELOADABLE
CLOSEDLOOP

This is the order type for
all the records in the
order files.

Header|Client_12_14_2015_1.txt|INDIVIDUAL|PERSONALIZED|PREDENOMINATED

Detail Header Record

This record denotes the Detail Header Record and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

1

Detail Header

String

6

Yes

Allowed:
Detail|QuoteNumber|CardholderPIDNumber|Title1|First
_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_E
mboss_Text|Address_Element_1|Address_Element_2|A
ddress_Element_3|City|State|PostalCode|PostalCode_E
xt|Area_Code|Phone_Number|Phone_Ext|Indicative_Dat
a_1|Indicative_Data_2|Indicative_Data_3|Indicative_Dat
a_4|Indicative_Data_5|Quantity|Content_Provider_Code|
Grouping_Id|Transaction_Amount|Transaction_Descripti
on|Transaction_Type|Program_Participation_Status|Fun
d_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indi
cative_Data_3|Fund_Indicative_Data_4|Fund_Indicative
_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship
_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address

3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_C
ode|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Messag
e|Shipping_Method|KYC_Company_Name|KYC_Contac
t_Name|KYC_Address_Line_1|KYC_Address_Line_2|K
YC_City|KYC_State|KYC_Zip|KYC_Tax_ID

Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_State|KYC_Zip|KYC_Tax_ID

File Detail Record

This record denotes the Order File Detail and has the following format.

  Required  
 Index  Parameter Name Data Type Size Open Loop Personalized Open Loop Reloadable Open Loop Anonymous Closed Loop Personalized Carrier Closed Loop Anonymous (No Carrier) Validation Rules / Allowed Values Short Description
1 Detail String 6 Yes Yes Yes Yes Yes DETAIL
2 QuoteNumber String 17 Yes Yes Yes Yes Yes Digits 0-9 Quote number or client program number provided by your account manager.
3 CardholderPIDNumber Char 30 Yes Yes Yes Yes Yes Digits 0-9, Alpha (a-z, A-Z), period and comma. This is a unique number that can never be reused within a quote or client program.
4 Title_1 Char 5 No No No No No Mr, Mrs, Miss. Ms or blank. Recipient's name prefix.
5 First_Name Char 25 Yes Yes No Yes No Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen. Recipient's first name.
6 Middle_Name Char 25 No No No No No Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen. Recipient's middle name.
7 Last_Name Char 25 Yes Yes No Yes No Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen. Recipient's last name.
8 Title_2 Char 5 No No No No No Alpha (a-z, A-Z) Recipient's name suffix.
9 Fourth_Line_Emboss_Text Char 21 No No No N/A N/A Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Fourth line emboss value that appears below the Card_Emboss_Name value.
Leave Blank for Closed Loop Physical.
10 Address_Element_1 Char 35 Yes Yes No Yes No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Recipient's address information.
This is also the shipping information for individually shipped cards
11 Address_Element_2 Char 35 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/) and apostrophe. Recipient's address information.
This is also the shipping information for individually shipped cards.
12 Address_Element_3 Char 35 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Recipient's address information.
This is also the shipping information for individually shipped cards.
13 City Char 30 Yes Yes No Yes No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. City for the recipient's address information.
This is also the shipping information for individually shipped cards
14 State Char 2 Yes Yes No Yes No Alpha (a-z, A-Z) State for the recipient's address information.
This is also the shipping information for individually shipped cards.
15 PostalCode Char 6 Yes Yes No Yes No Digits 0-9 and alpha (a-z, A-Z) Postal code for the recipient's address information.
This is also the shipping information for individually shipped cards
 Index  Parameter Name Data Type Size Open Loop Personalized Open Loop Reloadable Open Loop Anonymous Closed Loop Personalized Carrier Closed Loop Anonymous (No Carrier) Validation Rules / Allowed Values Short Description
16 PostalCode_Ext Number 4 No No No No No Digits 0-9 Postal code extension for the recipient's address information.
This is also the shipping information for individually shipped cards.
17 Area_Code Number 3 No No No No No Digits 0-9 Recipient's area code.
18 Phone_Number Number 7 No No No No No Digits 0-9 Recipient's phone number.
19 Phone_Ext Number 6 No No No No No Digits 0-9 Recipient's phone number extension.
20 Indicative_Data_1 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z), and space A custom field that will be returned on the shipping file.
21 Indicative_Data_2 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z), and space A custom field that will be returned on the shipping file.
22 Indicative_Data_3 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z), and space A custom field that will be returned on the shipping file.
23 Indicative_Data_4 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z), and space A custom field that will be returned on the shipping file.
24 Indicative_Data_5 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z), and space A custom field that will be returned on the shipping file.
25 Quantity Number 5 No No No
Yes, for bulk quotes.
No No
Yes, for bulk quotes.
Digits 0-9 The quantity of cards for a bulk order.
26 Content_Provider_Code Char 118 N/A N/A N/A Yes Yes will be provided with quote approval process and are quote specific The merchant for Closed Loop Physical cards orders.
27 Grouping_Id String 50 N/A N/A N/A Yes, for Multi Affix N/A Digits 0-9 and alpha (a-z, A-Z) This is the Id used for Closed Loop Physical cards to be affixed to the same carrier.
28 Transaction_Amount Char 17 Yes Yes Yes Yes Yes Digits 0-9 and period.
Funding amount may not contain symbols, i.e. "$", "-", "()" and can have only two digits after decimal separator.
Dollar amount for the order.
29 Transaction_Description Char 40 No No No N/A N/A Digits 0-9, alpha (a-z, A-Z), and space The description that will appear next to the recipient's load transaction.
30 Transaction_Type Char 4 No Yes No N/A N/A Allowed Values:
  • 0001 - Load Funds
  • 0002 - Reverse Funds
This value is used to determine if funds are loaded or reversed.
 Index  Parameter Name Data Type Size Open Loop Personalized Open Loop Reloadable Open Loop Anonymous Closed Loop Personalized Carrier Closed Loop Anonymous (No Carrier) Validation Rules / Allowed Values Short Description
31 Program_Participation_ Status Char 1 No Yes No No No Allowed Values:
  • A - Active
  • I - Inactive
  • C - Cancelled
  • S -Suspended
  • R - Under Review
  • V - VIP
This determines the card status.
32 Fund_Indicative_Data_1 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z) and space This is a custom field.
33 Fund_Indicative_Data_2 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z) and space This is a custom field.
34 Fund_Indicative_Data_3 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z) and space This is a custom field.
35 Fund_Indicative_Data_4 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z) and space This is a custom field.
36 Fund_Indicative_Data_5 Char 17 No No No No No Digits 0-9, alpha (a-z, A-Z) and space This is a custom field.
37 Email Char 50 No No No No No Digits 0-9, alpha (a-z, A-Z), period and space.
Format: Must have an @ symbol and at least one period.
Recipient's email address.
38 Bulk_Ship_Contact_Company Char 35 No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
Digits 0-9, alpha (a-z, A-Z) space, period, comma, hyphen, forward slash (/) and apostrophe. Company and contact name for the shipping address.
39 Bulk_Ship_Address_1 Char 35 No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
Digits 0-9, alpha (a-z, A-Z) space, period, comma, hyphen, forward slash (/) and apostrophe.
Note: PO Boxes are not allowed and will be rejected.
Shipping address information (first line).
40 Bulk_Ship_Address_2 Char 35 No No No No No Digits 0-9, alpha (a-z, A-Z) space, period, comma, hyphen, forward slash (/) and apostrophe. Shipping address information (second line).
41 Bulk_Ship_Address_3 Char 35 No No No No No Digits 0-9, alpha (a-z, A-Z) space, period, comma, hyphen, forward slash (/) and apostrophe. Shipping address information (third line).
42 Bulk_Ship_City Char 30 No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe City for the shipping address information.
43 Bulk_ Ship_State Char 2 No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
alpha (a-z A-Z). State for the shipping address information.
44 Bulk_Ship_Postal_Code Char 6 No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
Digits 0-9 and alpha (a-z, A-Z). Postal code for the shipping address information.
45 Bulk_Ship_Postal_Code_Ext Number 4 No No. No. No No Digits 0-9 Postal code extension for the shipping address information.
 Index  Parameter Name Data Type Size Open Loop Personalized Open Loop Reloadable Open Loop Anonymous Closed Loop Personalized Carrier Closed Loop Anonymous (No Carrier) Validation Rules / Allowed Values Short Description
46 Card_Carrier_Message Char 80 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. This is the custom message on the carrier.
47 Shipping_Method Char 21 No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
No
Yes, for bulk quotes.
Allowed Values:
  • UPS Ground
  • UPS Second Day
  • UPS Next Day
  • USPS First Class Mail
This is the shipping method for the order.
48 KYC_ Company_Name Char 20 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Company name for Know Your Customer (KYC) Information.
49 KYC_Contact_ Name Char 60 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Contact name for Know Your Customer (KYC) Information.
50 KYC_Address_Line_1 Char 35 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Address for Know Your Customer (KYC) Information.
51 KYC_Address_Line_2 Char 35 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. Address for Know Your Customer (KYC) Information.
52 KYC_City Char 30 No No No No No Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. City for Know Your Customer (KYC) Information.
53 KYC_State Char 2 No No No No No Alpha (a-z, A-Z) State for Know Your Customer (KYC) Information.
54 KYC_Zip Char 6 No No No No No Digits 0-9 and alpha (a-z, A-Z). Postal code for Know Your Customer (KYC) Information.
55 KYC_Tax_ID Number 9 No No No No No Digits 0-9 TaxID for Know Your Customer (KYC) Information.

File Trailer Record

This record denotes the Order File Trailer and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

Trailer

String

17

Yes

Allowed:
NUMBER OF
RECORDS

2

RecordCount

Number

N/A

Yes

Allowed:
Digits 0-9

This is the number of detail
records in the order file.

NUMBER OF RECORDS |20

Sample Order Files

Header|Client_12_14_2015_1.txt|INDIVIDUAL|PERSONALIZED|PREDENOMINATED
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_State|KYC_Zip|KYC_Tax_ID
Detail|40731701|TestPID1||James||Smith|||PO Box 111|||Chicago|IL|62026||314|2262000||Hello World||POXYZ||||||50|Holiday Bonus||||||||[email protected]|||||||||||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731701|TestPID2||Nancy||Jones|||18903 Fake St|||St. Louis|MO|63117||314|2262000||Hello World||PO987||||||50|Holiday Bonus||||||||[email protected]|||||||||||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2
Header|Client_12_14_2015_1.txt|BULK|PERSONALIZED|PREDENOMINATED
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_State|KYC_Zip|KYC_Tax_ID
Detail|40731702|TestPID1||John||May|||PO Box 341|||Chicago|IL|62026||314|2262000||Hello World||PO123||||||50|Holiday Bonus||||||||[email protected]|Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026|||UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731702|TestPID2||Amy ||Cole|||103 Adams St|||St. Louis|MO|63117||314|2262001||Hello World||PO456||||||50|Holiday Bonus||||||||[email protected]|Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026|||UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2
Header|Client_12_14_2015_1.txt|INDIVIDUAL|PERSONALIZED|RELOADABLE
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_State|KYC_Zip|KYC_Tax_ID
Detail|40731703|TestPID1||James||Smith|||PO Box 111|||Chicago|IL|62026||314|2262000||Hello World||POXYZ||||||50|Holiday Bonus||||||||[email protected]|||||||||||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731703|TestPID2||Nancy||Jones|||18903 Fake St|||St. Louis|MO|63117||314|2262000||Hello World||PO987||||||50|Holiday Bonus||||||||[email protected]|||||||||||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2
Header|Client_12_14_2015_1.txt|BULK|PERSONALIZED|RELOADABLE
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_Sta te|KYC_Zip|KYC_Tax_ID
Detail|40731704|TestPID1||James||Martin|||PO Box 252|||Chicago|IL|62026||314|2262000||Hello World||PO789||||||50|Holiday Bonus|0001|A||||||[email protected]|Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026|||UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731704|TestPID2||Mark||Smith|||467 Butler Dr|||St. Louis|MO|63117||314|2262001||Hello World||PO684||||||50|Holiday Bonus|0001|A||||||[email protected]|Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026|||UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2
Header|Client_12_14_2015_1.txt|BULK|ANONYMOUS|PREDENOMINATED
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_State|KYC_Zip|KYC_Tax_ID
Detail|40731705|TestPID1|||||||||||||||||Hello World||PO852|||10|||50|Holiday Bonus|||||||||Acme Company -Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026|||UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731705|TestPID2|||||||||||||||||Hello World||PO528|||20|||25|Holiday Bonus|||||||||Acme Company -Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026|||UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2
Header|Client_12_14_2015_1.txt|INDIVIDUAL|PERSONALIZED|CLOSEDLOOP
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_Sta te|KYC_Zip|KYC_Tax_ID
Detail|40731706|TestPID1||Jody||Sommer|||PO Box 789|||Chicago|IL|62026||314|2262000||Hello World||PO669||||Cabelas|12345|200|||||||||[email protected]|||||||||E njoy shopping when you redeem your points!||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731706|TestPID1||Jody||Sommer|||PO Box 789|||Chicago|IL|62026||314|2262000||Hello World||PO669||||iTunes|12345|25|||||||||[email protected]|||||||||Enj oy shopping when you redeem your points!||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731706|TestPID2||George||Winter|||5648 Market St|||St. Louis|MO|63117||314|2262000||Hello World||PO445||||GameStop||50|||||||||[email protected]|||||||||Enjoy shopping when you redeem your points!||ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|3
Header|Client_12_14_2015_1.txt|BULK NO CARRIER|ANONYMOUS|CLOSEDLOOP
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_Sta te|KYC_Zip|KYC_Tax_ID
Detail|40731707|TestPID1|||||||||||||||||Hello World||PO5150|||25|GameStop||200||||||||||Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026||Enjoy shopping when you redeem your points!|UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731707|TestPID1|||||||||||||||||Hello World||PO5150|||100|iTunes||50||||||||||Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026||Enjoy shopping when you redeem your points!|UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2
Header|Client_12_14_2015_1.txt|BULK|ANONYMOUS|CLOSEDLOOP
Detail|QuoteNumber|CardholderPIDNumber|Title_1|First_Name|Middle_Name|Last_Name|Title_2|Fourth_Line_Emboss_Text|Address_Element_1|Address_Element_2|Address_Element_3|City|State|PostalCode|PostalCode_Ext|Area_Code|Phone_Number|Phone_Ext|Indicative_Data_1|Indicative_Data_2|Indicative_Data_3|Indicative_Data_4|Indicative_Data_5|Quantity|Content_Provider_Code|Grouping_Id|Transaction_Amount|Transaction_Description|Transaction_Type|Program_Participation_Status|Fund_Indicative_Data_1|Fund_Indicative_Data_2|Fund_Indicative_Data_3|Fund_Indicative_Data_4|Fund_Indicative_Data_5|Email|Bulk_Ship_Contact_Company|Bulk_Ship_Address_1|Bulk_Ship_Address_2|Bulk_Ship_Address_3|Bulk_Ship_City|Bulk_Ship_State|Bulk_Ship_Postal_Code|Bulk_Ship_Postal_Code_Ext|Card_Carrier_Message|Shipping_Method|KYC_Company_Name|KYC_Contact_Name|KYC_Address_Line_1|KYC_Address_Line_2|KYC_City|KYC_Sta te|KYC_Zip|KYC_Tax_ID
Detail|40731708|TestPID1|||||||||||||||||Hello World||PO1812|||100|Lowes||100||||||||||Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026||Enjoy shopping when you redeem your points!|UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
Detail|40731708|TestPID1|||||||||||||||||Hello World||PO1812|||100|iTunes||50||||||||||Acme Company - Harry Smith|4567 Olive Rd.|Suite 200||Chicago|IL|62026||Enjoy shopping when you redeem your points!|UPS Ground|ABC Company|James Dean|456 Green Rd|Suite 55B|Atlanta|GA|30302|987654321
NUMBER OF RECORDS|2

Success File

Success File Spec Summary

Blackhawk Network generates a success acknowledge 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
  • OrderNumber – order number from Blackhawk Network’s ordering system
  • Success – static value in file name.
  • SQ – sequence number starts with 1 and is incremented by 1 for every response generated for the order.

Example: Client_12_14_2015_1_11112234_Success_1.txt
Delimiter: Pipe Symbol (‘|’)

Success File Spec Structure

File Detail Record: This record denotes the Success File Detail and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

Status

Char

7

Yes

Allowed Values:
SUCCESS

2

Order Number

Number

N/A

Yes

Allowed:
Digits 0 - 9.

This is the order number
produced by Blackhawk Network’s ordering system.

3

Quote Number

Number

N/A

Yes

Allowed Values:
Digits 0 - 9.

This is the quote number
provided by the Blackhawk Network account manager.

4

File Name

Char

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 Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

Trailer

String

17

Yes

Allowed Values:
NUMBER OF
RECORDS

2

RecordCount

Number

N/A

Yes

Allowed Values:
Digits 0-9.

This is the number of
records in the file

NUMBER OF RECORDS|1
Success|11112234|22676703| Client_12_14_2015_1.txt
NUMBER OF RECORDS|1

Exception Files

Blackhawk Network generates an exception file in the case of errors with the file format, order or order line items.

There are two kinds of exception file formats that can be generated:

1. Order Error Format
This file format is used when there is an issue that is not specific to an order line item. For example, an incorrect file format or an invalid quote number.

2. Order Line Item Error Format
This file format is used when the file format is correct but there is an issue with the data for a specific order line item.

Exception File Specification - Order Error

Blackhawk Network generates an exception file in the following defined format when there is a general order level error that is not specific to any order line item. For example, in the case of a file format error or an invalid quote number.

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.
  • SQ – sequence number starts with 1 and is incremented by 1 for every response generated for the order.

Example: Client_12_14_2015_1_Err_1.txt
Delimiter used: Pipe Symbol (‘|’)

Exception File Structure - Order Error

File Detail Record: This record denotes the Exception File Detail and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

Error Description Code

Char

3

Yes

Allowed Values: Digits 0 – 9

This is an error code that is used to look up the error description. The error table is listed below.

2

Error Description Text

Char

100

No

Allowed Values: Digits (0-9), Alpha (a-z, A-Z), spaces and period (.)

This is the textual representation of the error from the system.

File Trailer Record: This record is the Exception File Trailer and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

Trailer

String

7

Yes

Allowed Values:
NUMBER OF
RECORDS

2

RecordCount

Number

N/A

Yes

Allowed Values:
Digits 0-9.

This is the number of
records in the file

NUMBER OF RECORDS|20
007|Could not process records for quote number: 93458101. Please contact Hawk Incentives.
NUMBER OF RECORDS|1

Exception Codes and Messages - Order Error

Exception Code

Message

Data Field

000

An error occurred processing the file. Please contact Hawk Incentives.

File Error

001

Quote number invalid

File Error

004

File format is incorrect. Please refer to Hawk Incentives 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 Hawk Incentives.

QuoteNumber

Exception File Specification - Order Line Item Error

Blackhawk Network generates an exception file for invalid order line item 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.
  • SQ – sequence number starts with 1 and is incremented by 1 for every response generated for the order.

Example: Client_12_14_2015_1_Err_1.txt
Delimiter: Pipe Symbol (‘|’)

Resolving Order Line Item Exceptions

When handling an exception file of this type follow these instructions to resolve:

  1. Reference the code reported for the row in the Exception Codes and Messages table listed below
  2. Find the correct row in the order file that needs to be updated, making sure to read the important note about item numbers below to ensure you are looking at the correct row
  3. Correct the bad data in the row referenced
  4. Repeat steps 1 through 3 for each exception
  5. Upload the new order file to the FTP site for processing

Exception File Structure - Order Line Item Error

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

Short Description

1

Item Number

Char

N/A

Yes

Allowed Values:
Digits 0-9

Detail record with the error in the order file. Note that this is not the file row number.

2

Column Name

Char

100

Yes

Allowed: Alpha,
Digits 0-9, Spaces

Name of the column containing the error.

3

Error Description Code

Char

3

Yes

Allowed Values:
Digits 0-9

The error code used to look up the description. The error table is listed below.

4

PID Number

Char

30

No

Allowed Values:
Digits 0-9, Alpha (a-z, A-Z), period (.) and comma (,)

A unique number that was provided in the order file.

5

Quote Number

Number

17

Yes

Allowed Values:
Digits 0-9

The quote number provided by Blackhawk Network.

6

File Name

Char

N/A

Yes

Allowed Values:
Digits 0-9, Alpha (a-z, A-Z), and period (.)

The file name of the submitted order

7

Indicative_Data_1

Char

17

No

Allowed Values:
Digits 0-9, Alpha (a-z, A-Z) and spaces

Contain the value for this field as provided in the order file.

8

Indicative_Data_2

Char

17

No

Allowed Values:
Digits 0-9, Alpha (a-z, A-Z) and spaces

Contain the value for this field as provided in the order file.

File Trailer Record: This record is the Exception File Trailer and has the following format.

Index

Name of Parameters

Data Type

Size

Required

Validation Rules

Short Description

1

Trailer

String

7

Yes

Allowed Values:
NUMBER OF
RECORDS

2

RecordCount

Number

N/A

Yes

Allowed Values:
Digits 0-9.

This is the number of
records in the file

NUMBER OF RECORDS|20
01|City|120|2784|22676703|Client_12_14_2015_1.txt||
02|State|130|2785|22676703|Client_12_14_2015_1.txt||
NUMBER OF RECORDS|2

Important Note - Exception File Item Numbers

The Item Number in the exception file references the detail record processed. It does not reference the line number in the original order file. The line number in the original order file can be determined by adding three to the Item Number specified in the exception file (to account for the header row and column headings).

Example Order File:

01|City|120||12345678|ParkAndCompany_SampleFile_05_30_2019_1.txt||
NUMBER OF RECORDS|1

The Item Number above shows an issue with detail record 01. This indicates an issue with row four in the original order (highlighted below).

❗️

Warning - Windows Notepad

Do not use Windows Notepad to view response, exception or order files as it does not always handle line endings correctly. This can lead to a misidentification of the row numbers. Tools such as Notepad++ and Textpad are safe alternatives.

Using Indicative Data in Exception Files

The Indicative_Data_1 and Indicative_Data_2 values passed in the Order File are included in the Exception File. This can be a useful way to quickly find and identify the specific records generating the exception.

Exception Codes and Messages - Order Line Item Error

Exception CodeMessageData Field
002Transaction Amount missingTransactionAmount
003Duplicate PID NumbersCardholderPIDNumber
100Address line 1 is required and cannot exceed 30 characters for Gift Cheque orders or 35 characters for Card orders.Address_Element_1
110Address line 2 cannot exceed 30 characters for Gift Cheque orders or 35 characters for Card orders.Address_Element_2
120City name cannot exceed 20 characters for Gift Cheque orders or 30 characters for Card orders. Allowed Punctuation: space ( ), period (.), hyphen (-), and apostrophe ( ' ).City
130State/Province must be a valid 2 character (upper case) abbreviation for a US state or a Canadian province.State
140Postal Code must be a valid, 5 digit, US zip code or a valid Canadian postal code.PostalCode
140Postal Code must be a valid, 5 digit, US zip code or a valid Canadian postal code.Address_Element_10
150Must be a valid extended postal code for US addresses or a valid country name for non-US addresses.PostalCode_Ext
205Area Code contains a 3 digit area code for US phone or 6 digits or less for international phone.Area_Code
206Local Phone Number contains the local phone number; 7 digits for US phone or 16 digits or less for international phone.Phone_Number3
207Extension for US, UK, or Int'l card holders this contains the phone extension and cannot exceed 6 digits.Phone_Ext
420The 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 (')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 (')Last_Name
4754th Line Embossing cannot exceed 21 characters. Allowed Punctuation: space ( ), period (.), comma (,), hyphen (-), forward slash (/), apostrophe ( ' ) and ampersand (&).Fourth_Line_Emboss_Text
477Email must be a valid e-mail address.Email
479Card holder middle initial cannot exceed 25 characters. Allowed punctuation includes: space ( ), period (.), comma (,), hyphen (-), forward slash (/) and apostrophe ( ' ).Name_or_Initial
493Card holder title cannot contain punctuation. Available options are: Mr, Mrs, Miss, Ms or blank.Title_1
494Card holder title 2 cannot exceed 5 characters.Title_2
500Bulk Ship address line 1 is required and includes a company name and contact name but cannot exceed 35 characters.Bulk_Ship_Address_Element_1
505Bulk Ship address line 2 is required and cannot exceed 35 characters. Shipment to a PO Box is not allowed.Bulk_Ship_Address_Element_2
510Bulk Ship address line 3 is required and cannot exceed 35 characters. Shipment to a PO Box is not allowed.Bulk_Ship_Address_Element_3
515Bulk Ship city is required and cannot exceed 20 characters for Gift Cheque orders or 30 characters for Card orders.Bulk_Ship_City
520Bulk Ship State is required and must be a valid 2 character abbreviation for a US state or a Canadian province or contain an international region less than 36 characters.Bulk_Ship_State
525Bulk Ship Postal Code must be a valid, 5 digit, US zip code or a valid Canadian postal code.Bulk_Ship_Postal_Code
530Bulk Ship extended Postal Code must be a valid extended zip code for US addresses or a valid country name for non-US addresses.Bulk_Ship_Postal_Code_Ext
535Card Carrier Message cannot exceed 40 charactersCard_Carrier_Message
606Not more than 17 characters.Fund_Indicative_Data_1
607Not more than 17 characters.Fund_Indicative_Data_2
608Not more than 17 characters.Fund_Indicative_Data_3
609Not more than 17 characters.Fund_Indicative_Data_4
610Not more than 17 characters.Fund_Indicative_Data_5
621Funding amount may not contain symbols (i.e. "$", "-", "()") and can have at most two digits after decimal separator.Transaction_Amount
625Funding Transaction description cannot exceed 40 characters.Transaction_Description
626Valid values are: '0001' (Funding/Load); '0002' (Reversal of Funding/Load). To process a Reversal a funding must have been processed within the last 10 days and match the exact amount of the earlier funding.Transaction_Type
637Quantity must contain a numeric value greater than 0Quantity
720Non-US value provided in state field for US only programAddress_Element_9
723Your funding amount is less than the required minimum for this productTransaction_Amount (Closed Loop)
724Your funding amount exceeds the maximum allowed for this productTransaction_Amount (Closed Loop)
726Must be a valid Canadian postal code matching the province provided. Note: The exception file will reference Address_Element_10. Verify the province in the State parameter matches the PostalCode parameter.Address_Element_10
801Content Provider Code is required and cannot exceed 118 characters.Content_Provider_Code
802Content Provider Code is not valid for this program.Content_Provider_Code
805Grouping ID cannot exceed 50 charactersGrouping_Id
915PID must be unique. The PID provided has already been used for this QuoteNumber.Cardholder_PID_number
999NRI_Delayed_Record, among othersShipping_Method
6000KYC Company Name must not be more than 20 charactersKYC_Company_Name
6001KYC Contact Name must not be more than 60 characters.KYC_Contact_Name
6002KYC Address Line 1 must not be more than 35 characters.KYC_Address_Line_1
6003KYC Address Line 2 must not be more than 35 characters.KYC_Address_Line_2
6004KYC City name cannot exceed 20 characters for Gift Cheque orders or 30 characters for Card orders. Allowed Punctuation: space ( ), period (.), hyphen (-), and apostrophe ( ' ).KYC_City
6005KYC State/Province must be a valid 2 character (upper case) abbreviation for a US state or a Canadian province.KYC_State
6006KYC Zip must be a valid zip code for US addresses.KYC_Zip
6007KYC Tax ID must be 9 digits.KYC_Tax_ID
6008KYC State/Zip code combination is invalid.
9101Not more than 17 characters.Indicative_Data_1
9102Not more than 17 characters.Indicative_Data_2
9103Not more than 17 characters.Indicative_Data_3
9104Not more than 17 characters.Indicative_Data_4
9105Not more than 17 characters.Indicative_Data_5

Did this page help you?