Frequently Asked Questions

Product Questions

What is a Client Program Number, a Quote ID or a Product ID?

This is the program identification number automatically assigned when a quote is created. It is an eight digit long number.

Note: Client Program Number, Quote ID and Product ID are different names for the same number.

How can I get my Client Program Number

Your account manager will provide details for your product setup and Client Program Number.

Is there a website that can be used to check orders and product details?

Yes, the Hawk Marketplace portal can be used to check order status and product details. Your account manager will be able to share the details with you on how to access the portal.

How many products can I add under one Client Program Number?

For open loop reward, gift or disbursement programs only one product can be added to a client program number. If more than one product is required, a separate client program number will be provided for each product.

For closed loop merchant digital and physical gift products multiple products can be added to a single client program number. When ordering the content provider code is used to specify which product you would like to order within the client program.

Connectivity Questions

How can I connect to the Hawk Marketplace pre-production and production environment?

Please work with your project manager to obtain a signed client certificate. Certificates are different for both pre-production and production environments.

What is the base URL for pre-production environment?

https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1

What is the base URL for production environment?

https://api.blackhawknetwork.com/rewardsOrderProcessing/v1

What SSL/TLS versions are supported for digital certificates?

TLSv1.2 and above.

Are digital certificates required for ordering via APIs?

Digital certificates are required in both pre-production and production environments and must be sent with every request.

Hawk Marketplace Portal

How can I get access to the Hawk Marketplace portal?

Your account manager will provide the credentials and URLs for the Hawk Marketplace portal.

What type of details can be checked on the Hawk Marketplace portal?

The Hawk Marketplace portal is useful for placing orders manually, checking the status of orders, seeing the product details, fees, merchants and discounts.

Technical Questions

What is a Merchant ID?

The Merchant ID (MID) is a string identifier, provided by your account manager that varies based on the product type you are ordering.

What is a Request ID?

The Request ID is a globally unique string identifier specified by your client application, to be used during reconciliation. Every request must have a unique Request ID.

What is the purpose of MillisecondsToWait?

The MillisecondsToWait HTTP header value indicates that how long your application is willing to wait for a response. A value of 0 milliseconds means that the transaction type will be processed asynchronously. The maximum value is 30000 (30 seconds). Different products and program types have different recommended best practice values for the millisecondsToWait parameter. Please consult with your implementation project manager to ensure you use the value recommended for your program and implementation type.

What is the purpose of SYNCHRONOUS_ONLY?

The SYNCHRONOUS_ONLY HTTP header only applies to real-time eGift orders. The purpose of this parameter is to specify if the behavior of the POST call will be asynchronous or synchronous.

If the value is true and order processing is not completed within the initial order request's millisecondsToWait time, then the order request will be cancelled.

If false is provided (or the header is omitted) the order request will continue to process after the millisecondsToWait period has expired and any reward URLs or codes will need to be retrieved separately by calling /eGiftBulkCodeRetrievalInfo/byKeys.

Which API method is used for retrieving eGift card details?

GET - /eGiftBulkCodeRetrievalInfo/byKeys is the method for retrieving eGift card information by passing orderNumber or requestId and clientProgramNumber.

What is the difference between submitRealTimeEgiftBulk and submitRealTimeEgiftIndividual ordering POST methods?

Both methods are used for ordering closed loop merchant eGifts in the real-time environment.

When using the submitRealTimeEgiftBulk you are required to retrieve the ordered eGift details (URL, card number, code and PIN) and deliver them to the recipient. When using submitRealTimeEgiftIndividual Blackhawk Network will send the eGift to the recipient via email.

Note: The maximum quantity for a real-time order is 1. The maximum line items for a real-time order is 1

What is the difference between submitRealTimeVirtualBulk and submitRealTimeVirtualIndividual ordering POST methods?

Both methods are used for ordering open loop virtual cards in the real-time environment. When using the bulk endpoint you are required to fetch the ordered virtual product code and deliver it to the recipient. When using the individual endpoint Blackhawk Network will send the virtual code and redemption URL to the recipient via email. The maximum quantity for a real-time order is 1. The maximum line items for a real-time order is 1

Which API method is used for retrieving virtual codes?

GET - /virtualCodeRetrievalInfo/byKeys is the method for retrieving virtual code information by passing orderNumber or requestId and clientProgramNumber.

Which API method is used to check status after order submission?

GET - /orderInfo/byKeys is the method used to get the order information by passing orderNumber or requestId and clientProgramNumber

Do these API methods support an Asynchronous Service Model?

The ordering APIs are a hybrid synchronous-asynchronous model, where the response behavior may be either synchronous or asynchronous depending on current processing load, request complexity, and input from your client application. The MillisecondsToWait parameter is used to indicate how long the client application is willing to wait for a response.

A response object or error object (if the operation was unsuccessful) will be returned within that time frame. If the request is still in process after the time specified in the MillisecondsToWait parameter has been exceeded, the interaction becomes asynchronous, and a transactionId value is provided. All GET requests within Rewards Order Processing API are synchronous.

Learn More

What types of HTTP response codes API will return?

The following response codes may be returned from these APIs.

  • 200: Operation complete - Your request completed successfully, no further action is needed.
  • 201: Operation complete - Your request completed successfully, no further action is needed.
  • 202: Operation is in process - Your request is still in process. Check back later by making a GET request using the transaction id.
  • 400: Invalid Request - There was an error in the request. Check your request payload and retry with a new request id.
  • 409: Conflict - Usually this means you used a duplicate request id. Retry the request with a new request id.
  • 5XX: Gateway or service error - There is a temporary issue with the service or gateway. Please try again later.

Which characters are allowed for placing orders via API?

Allowed characters vary by field. Please refer to the appropriate order guide and specific field for more information.

Is there any method for checking order shipping status?

GET - /queryShippingInfo is the method used to get the shipping information by passing orderNumber, cardholderFirstName, cardholderLastName.


Did this page help you?