Frequently Asked Questions



How can I keep up with changes to the Blackhawk Network Digital Services APIs?

Blackhawk Network Digital Services evolve constantly according to the requirements of our partners and users. Be sure to follow the Release Notes to see the latest changes.

About this website

Questions about using Blackhawk Network Developer Portal.

One of the pages about the Blackhawk Network Digital Services APIs isn’t displaying correctly. What should I do?

Occasionally, part or the entire site is undergoing change or has been taken offline for maintenance and updates. Go back to the page in question and click refresh to see if that fixes the problem.


Questions business analysts and others on the business team have about Blackhawk Network Digital Services.

Are there standard image assets for displaying gift cards in an online/mobile application?

Standard images are available at the brand and product level. Partners can retrieve both levels of images using Blackhawk Network Digital Services. These are content partner approved images that can be used to provide a brand or product list on an application. Please ask the Blackhawk Network implementation manager about the image sizes you can use for brands and products.

Can product and brand image assets be modified or overlaid with data?

Card partners provide art assets for their cards and set their own policies for use of the art. The assets cannot be changed without approval.

If I want to provide customer service or lost/stolen support information for a gift card sold or stored on my application, can I get that information using the digital services?

If a retailer has provided customer service or lost/stolen support, then the information can be retrieved by looking at the brand information in the Product Line Management service. Not every brand provides this information in support of its products.

Do Blackhawk Network Digital Services provide a payment service?

Blackhawk Network does not provide a payment service. We can work with you and suggest best practices to use, but it’s up to you to provide a payment acceptance solution.

If a user’s application is compromised, does Blackhawk Network provide a way to lock the user’s data?

Blackhawk Network does not offer a method for locking user data. The application you build has to handle security and fraud detection/prevention. Your application can suspend the Blackhawk Network eGift Application view so that a user can’t see an eGift.

Does Blackhawk Network require purchasers of eGifts to accept terms and conditions before making the purchase?

Blackhawk Network does not require a purchaser to accept product terms and conditions before an eGift is purchased, but your application should present terms and conditions to a purchaser at some point during the purchase process. If you use Blackhawk Network’s redemption display, then terms and conditions are presented with the eGift on the Blackhawk Network eGift Application and can be printed by the recipient of the eGift.

Does Blackhawk Network charge for each transaction made by an application?

Charges or commissions Blackhawk Network collects from you are spelled out in your contract and are subject to our negotiations with you. Contact your Blackhawk Network business representative for details about all contract-related questions.

What does merchant of record mean when using the Blackhawk Network Digital Services?

A merchant of record is a company responsible for the taking payment for goods or services issued by the company.

What is a distribution partner?

A distribution partner is a company/individual with a formal agreement to distribute eGifts and/or other prepayment products using the Blackhawk Network. Typically, they have customer facing applications their customers use to purchase and manage prepaid products.

What is a service provider?

A card processing service provider is a company that provides a set of services to process account transaction requests for the retailer card products they manage, such as activation, reload, redemption, void, and balance inquiry. Blackhawk Network integrates with service providers based on the service provider's defined specification and approved transactions sets.

How can I reconcile purchases made by my application with the settlement files I received from Blackhawk Network?

You application can associate a retrieval reference number with each purchase that is reflected in the settlement file provided by Blackhawk Network.

How do I alert Blackhawk Network to fraud reported by users?

To report fraud, contact Blackhawk Network Customer Service, as follows:

US & Canada:- National Partners: 877-246-6255
BHN NOC (Circuit/Connection) : 925-226-9952 (12:00am – 6:00am CST)

Does Blackhawk Network provide customer services for issues with its digital services?

Yes, Blackhawk Network Customer Service is designed to provide a positive customer service experience by staffing qualified agents who respond to customer inquiries. Agents are available from 6 AM to 12 AM CST, 7 days a week including holidays.

US & Canada:- National Partners: 877-246-6255
BHN NOC (Circuit/Connection) : 925-226-9952 (12:00am – 6:00am CST)

What does Blackhawk Network suggest as a delivery mechanism for an eGift?

Blackhawk Network does not dictate the fulfillment method utilized by an application, although certain merchants may request a review of the consumer flow if it does not follow the industry standard prior to approval. We suggest using the Blackhawk Network eGift Application to view all eGifts given no matter how the eGift is delivered.

Technical questions

Questions developers and system analysts have about Blackhawk Network Digital Services

What's the best way for my application code to handle optional fields?

When you use optional fields, you need to be sure your application code can handle new attributes that it doesn't recognize when you get responses back from API requests. For more details, see Coding Practices for Optional Fields on Developer Central.

Do the Blackhawk Network digital service sort returned data?

The digital APIs do not sort returned data.

What Digital APIs does an application use to get brand and product information?

To get product information:

  • Use the Product Catalog Management service by making calls to Query all Product Catalogs and Read Product Catalog to get an entire list of products for sale.
  • Use the Product Management service by calling Read Product to get specific information about individual products.

To get brand information:

  • Use the Product Line Management services by calling Query Product Lines by Criteria, passing locale and updatetimestamp to get a list of retailers/brands. Call Read Product Line to get brand level information.

Can an account created through the Account Processing or eGift Processing Services be deleted?

No. Once an account is created it will not be deleted from Blackhawk Network servers by calling a digital service. Your application can use our services to remove an association between an account and a user or void an account (depending on retailer support).

How does an application determine which products have fixed or variable activation amount? Who enforces the amount activated on the card?

Use the Product Management service by calling the Read Product API to retrieve a card’s activation characteristics. If the isVariablevalue value is true, the product can be activated for any amount on or between the activation minimum and maximum amount. If the isVariablevalue value is false, then the product's minimum and maximum values will be the same value, which means the amount of the product is fixed.

How do I determine if a card is reloadable? If a gift card is reloadable, who enforces the amount reloaded to the card?

To determine which cards are reloadable use Product Line data returned when calling the Read Product Line API. The Product Line is the brand of the gift card selected during the digitizing of a physical gift card or the purchase of an eGift. If the isReloadable value is set to true in the Reload Characteristics resource, then the card is reloadable.

Blackhawk Network neither determines the amounts that can be reloaded onto cards nor enforces card maximums or minimums. After a partner sends a request for a reload the Service Provider/Processor determine the actual amount that can be reload to a gift card.

What are the advantages of using the Person Management Service?

With Person Management, your application creates a person object representing the card user. This enables the app to associate a card or account with that person. Doing this lets you track cards purchased by a user in order to provide customer service support for potential fraud charges and other reasons

What are the advantages of using the Bag Management Service?

With Bag Management, you create a virtual container (a “bag”) in which users can store and manage cards. An example of a bag is a digital wallet. Some of the advantages of doing this are:

  • A bag gives users a centralized location for managing cards that use Blackhawk Network Digital Services
  • You can track all cards associated with a user, seeing what products they purchase and how they use them. This can help you determined what products to offer in the future.

How can I determine when a product catalog, product, and product line contain updated information? How often is the information updated?

  • Product Catalog
    • Do this with the Product Catalog Management API version element within the Product Catalog Summary, which identifies the latest version and should be compared against the current version cached on your application.
  • Product
    • Do this with the Product Management API Read Product updateTimestamp element within the Product Details, which identifies the date and time when an entity was updated
  • Product Line
    • Do this with the Product Line Management API Read Product Line updateTimestamp element within the Product Line Details, which identifies the date and time when an entity was updated

How does my application determine if a balance inquiry call has successfully returned a card's updated balance from the processor?

Your application calls the Get Account Information from the Account Processing Service and checks balanceAsOf and isBalanceStale to determine if the balance inquiry request was successful. Here's what they should indicate:

  • balanceAsOf indicates precise date and time of the last successful balance inquiry request
  • isBalanceStale sets a flag (boolean) to indicate whether the balance is "stale," that is, if the returned balance has been cached by the application, or if has been refreshed by the processor. If balance inquiry failed, it will be true, meaning that the application is using the result of a previous inquiry. If it succeeded, the flag will be set to false, meaning the balance shown is "fresh" from the processor.

What is the difference between createAccount and generateEGift when selling a product?

You use the generateEGift operation to display digital content representing a card or other product based on information from the product catalog. That information includes product, currency amount, To Recipient, From Sender amount, product ID, and so on, which is used to present a virtual product for purchase as an eGift. In order to use your application must use generateEGift. The createAccount API handles the details of creating an account that is associated with the eGift for activation, redemption, reloading, balance inquiries, etc.

How do I determine which products support mobile barcode redemption at a POS?

Do this with the Product Line Management API Read Product Line service by checking if the Supported Feature element has HAS_PHONE_SUPPORT_AT_POS

When does my application make idempotent requests using Blackhawk Network Digital Services?

See our tech note about the use of requestID for idempotent retries.

How does Blackhawk Network handle generation of bar codes for use in my products?

  • Blackhawk Network uses Zint for bar code generation and Zbar for reading on iOS devices.
  • Blackhawk Network uses zxing for generating and reading bar codes on Android devices.

Is there a way to categorize the products I sell using the Digital Services?

The digital services do not offer a way to categorize brands or products managed or sold by your application. It is entirely up the application to build in categorization

What do I need to manage on my side?

This depends on what services are used by the application. An application should cache the Product Line and Product information for assets presented on the application for the brand and production information.

An application that uses the person and bag management service Blackhawk Network will manage the person and card information.

What is the recommended size of a barcode display for a mobile application?

The C128 barcode specification recommends use of the following dimensions:

  • Minimum of 330 pixels wide with 10 pixels padding on left and right, for total of 350 pixel minimum.
  • Maximum can help with scan success rate and can be derived from expanding the x-dimension as the screen pixel width changes. (X dimension = the size of the smallest bar. Be sure to maintain padding)

For an example of how to expand the x-dimension w/barcode library see

What high resolution image sizes are available for my application?

Blackhawk Network supports the following high resolution images for Product Line Management and Product Management

  • Product Line has a 500x500 JPG with a white background
  • Product has a 700 x 442 PNG with transparent corners for International brands
  • Product has a 308 x 198 PNG with transparent corners for US brands

Did this page help you?