A few FAQ's shared by the development community


Q: What happens when an order is rejected, cancelled or error?

A: Once an order is rejected or cancelled, it can no longer be fulfilled. You will have to submit an alternate order (with the same partner order number if desired) for fulfillment, as long as there is no active (not rejected, not cancelled) orders in the system. If there is an 'active' order with the specified partner order number, the secondary request will be considered a duplicate and rejected accordingly.
Error is not a final status of an order. There is still an option for manual remediation in getting the order back on its fulfillment track. If manual remediation is not possible the order will be cancelled. There is no action required by the DDP.
All of these status will have a reason for the rejection, cancellation or error noted in the line item attribute.


Q: What happens when an order is submitted multiple times?

A: Once an order is submited to BHN, the FMS will verify if there is an existing 'active' order in the system, i.e., a duplicate order check. An 'active' order is defined as an order that is either not rejected or not cancelled.

To determine if an order is duplicate, FMS will look at "Partner Order Number", "PartnerPONumber" and "Fulfillment Status"

If there is an 'active' order, the secondary request will be considered a duplicate and rejected accordingly.


Q: Can I use the same certificate for Fulfillment Services as I use for eGift Services and Product Services?

A: Yes. The Fulfillment Mnaagement Services uses the same gateway endpoint https://api.blackhawknetwork.com


Q: Can I request partial fulfillment?

A: No. Blackhawk's FMS API is not merchant-of-record. As such, any changes to an order must be done on the merchants side in order for merchant to control the desired user-experience (notification, refunds, etc.) that is merchant specific.


Q: How often can I poll Blackhawk for my order status (assuming I am not leveraging callbacks).

A: You will typically poll for order status to determine if order was a) Rejected b) Shipped or c) Error. Depending on which status you are interested in, you will poll Blackhawk according to the following cadence (best practices)

Typically, you can follow the schedule below. However, we suggest you consult with your Account Manager to fine-tune the schdule based on your programs, region and which partners/FSP's BHN leverages to support your program.


Poll Blackhawk with 30min-60min after after was requested


Poll Blackhawk after 3-business days (for standard fulfillment) after 11PM PT
Poll Blackhawk after 1-business days (for expedited fulfillment) after 11PM PT


Poll Blackhawk within 12-48hrs after order was requested, with a frequency no more that once every 4hrs.


Q: My company does not allow callbacks due to security. What are my options? What if my company has its own end-points?

A: In the event your company does not support callbacks from Amazon SNS, your easiest options is to simply poll Blackhawk for your order status. Please see "Order or Item Status Values" for best practices.

If you company has an end-point for vendors to update order status, an adapter could be custom developed for you to mediate between Blackhawk callbacks and your API's. Please engage you account manager and inquire about our Professional Services offerings.


Q: How can I load funds (a.k.a., activate) my orders (or cards)?

A: There are several options available based on Order Central's Volume Activation API's

  •     Card Holder Activation Request API to activate by card
  •     Volume Card activation Request API to activate by order
  •     Volume Card Order Activation Status Request API to check on activation status (when activating by order) 


Q: What best-practices should I consider when developing against Blackhawk's FMS APIs?

A: To answer this question, you need to understand the following:

A) Order Central Consumer Fulfillment Process

Digital Distribution Partner places an order-request (OR) for new card(s)
Upon receipt of the OR, Order Central will validate and verify if
    The order includes mandatory minimal info [packaging type, product, denomination, shipping info, etc.,] to properly fulfill
    The product(s) requested are in DDP’s catalog
Upon validation, Order Central sends back an Order Confirmation Notification to DDP, indicating acceptance or rejection of the order request at both the order and line-item levels.
    Order Central does not support partial fulfillment. If 1 of N items cannot be fulfilled, Order Central will indicate the rejected and accepted items, but reject the entire order. DDP will have to review ‘rejected’ line items to remediate.
Post order acceptance Order Central
    Enriches the order with mandatory data
    Submits file to specified FSP
    Manages life cycle of order fulfillment process.
Order Central sends Shipment Notification (SN) per item (not card) back to DDP as each item is fulfilled.
    This implies shipped items within an order can be notified across multiple SN, potentially spanning hours/days

B) Changes to Blackhawk spec elements

Blackhawk reserves the right to make minor enhancements to the specifications. Minor enhancements will be backward compatible.

You should build your client applications to gracefully handle the following types of changes to Blackhawk responses:

New request/response elements. Your client applications should handle new, unrecognized request (optional) and response elements.
New request/response element values. Your client applications should handle new, unrecognized request (optiona) and response element values.

What does it mean to "gracefully handle" changes? Here are some examples:

Expect changes. At a minimum, ensure that your client applications do not break when new request/response elements, request/response element values, API  fields or field field values are introduced by minor revisions.
    Don’t code your client applications to expect only certain elements, fields, and values. Must be resilient and extensible.
Log unrecognized elements, fields, or values. Keep a log of all unrecognized elements, fields, or values returned by Blackhawk. You can use this log to flag new functionality that has been introduced by Blackhawk, and then update your client application to take advantage of this functionality.
Surface unrecognized elements, fields, or values. If Blackhawk begins sending a response/notification with a new field, for example, you might devise a way to automatically surface the new field values in your client application in a way that is useful to your users.

C) Basic Structure of an order

The basic structure of an Order Central’s order is

An Order element is a collection of Line Items
A line item describes;
    Product Item Identifier – Unique product IID that identifies which card is ordered
    Denomination – Denomination value per card
    Quantity – Number of cards ordered
    Shipping information – Where to ship, shipping method, shipping cost
    BOMID – The Bill of Material to be packaged with the card product

D) Monitoring of Order Confirmation and Shipment Notification

Where possible, it is highly recommended DDP monitor for notifications (files/events) not received.

Example, if an Order Confirmation is expected within 1hr of sending an Order Request, a suitable notification or follow-on action may be appropriate. Also, should Order Confirmation include REJECTION messages, a suitable alert or proactive follow-on action may be appropriate. Rejection reasons vary. See below for top rejection/cancellation reasons.

Please escalate to your Client Manager or contact Blackhawk OCC as soon as possible to remediate issue as soon as possible.

Below are the top reasons for fulfillment failures. Its is recommended these use-cases are tested (un-happy path certification).

Order Central REJECTED scenarios

    Invalid IID/UPC --> Product not certified w/ DP prior to launch
    Product Not In Catalog --> Product not certified w/ DP prior to launch or catalog content has changed.
    Invalid Product Setup --> Product not certified w/ DP prior to launch
    Invalid Denom specified --> DP must validate $ActivationAmt is valid (and within permissible range if  a variable load product)
    Invalid Address --> DP must validate all address (billing, shipping, etc.) conforms to specs
    Invalid Ship Method for PO Box / Military --> DP must validate selected shipmethod is compatible to ShipAddress

Order Central CANCELLED scenarios

    Out Of Stock --> BackOrder will be enabled to prevent this.
    Bad Data --> E.g., Special characters not wrapped in CDATA, etc.
    Rejected response from FSP (MID/BOM/Program Not Setup, etc..) --> Product not certified w/ DP prior to launch

Did this page help you?