Bulk eGift Orders
Introduction
Bulk ordering allows you to acquire multiple eGifts for you to distribute directly. When placing a bulk order Blackhawk Network will not send the eGifts to the recipients on your behalf. You will be responsible for distributing the eGifts to the recipients (although you may still use the Blackhawk Network eGift URL).
There are two main steps to placing a bulk order:
- Submit the eGift order using
submitEgiftBulk - Retrieve the eGifts using
eGiftBulkCodeRetrievalInfo
In this guide we will be placing an order for three $25 Best Buy® eGifts.
Want to skip the details? Jump right to the full order JSON
Step 1: Placing the eGift Order
Our first step is to place the order via submitEgiftBulk.
| Method | Service | API | Type |
|---|---|---|---|
| POST | rewardsOrderProcessing | submitEgiftBulk → Explore | Hybrid synchronous/asynchronous based on millisecondToWait parameter |
URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitEgiftBulk
HTTP Header
From our application we need to send the following parameters in the HTTP header:
| Parameter | Description | Type | Required | Default Value |
|---|---|---|---|---|
| merchantId | The Merchant ID (MID) is a string identifier, provided to you by your account manager that varies based on the product type you are ordering. | String | Yes | None |
| requestId | A unique identifier for each order provided by you (the caller). The requestId value must be unique for each request and can have a maximum of 50 characters. | String | Yes | None |
| millisecondsToWait | Provide a value between 0 - 30000 to indicate how long your application or service will wait for a response. Once this time is exceeded the request will become asynchronous. The recommended value is 15000 (15 seconds). | Integer | No | 2000 |
In our example we will be sending the following values in the header:
Content-Type: application/json
merchantId: 60300003779
requestId: 2019-06-12T15:35:28-0500
millisecondsToWait: 30000
Body Parameters
In the body of the POST request we need to send all the information needed to complete the order:
| Parameter | Description | Type | Required | Allowed Values |
|---|---|---|---|---|
| clientProgramNumber | The client program number supplied by your Account Manager for the program you are placing your order under. | Integer | Yes | Must be a valid client program number / quote number assigned to you. |
| paymentType | This value in this attribute specifies the payment method to be used for the order. Note: The payment type value provided must match one of the payment types setup on the client program you are placing an order in or your order request will be rejected. | String | No | ACH_DEBIT BANK_TRANSFER DRAW_DOWN |
| financialAccountId | The financial account ID (FAID) specifies the financial account associated with your sub-organization to be used for the order. When a value is provided for the financialAccountId the paymentType attribute is required. A value for financialAccountId only needs to be provided when there are multiple financial accounts setup for a sub-organization. Your Implementation Project Manager or Account Manager will direct when you need to provide a value in this field. | String | No | The value provided must match a valid financial account ID configured for your sub-organization. |
| orderDetails | The products and quantities you wish to order. | Object | Yes | |
| returnCardNumberAndPIN | If you need the card number and pin returned this value must be set to "true". By default only the Blackhawk Network URL to the eGift is returned. | Boolean | No | true false |
| poNumber | PO numbers must be 50 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period and hyphen. |
Providing the Order Details
We will pass the details for the order in the orderDetails object:
| Parameter | Description | Type | Required | Allowed Values |
|---|---|---|---|---|
| clientRefId | Unique client reference to identify duplicates. Must be 30 characters or less. | String | No (but recommended) | Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. |
| quantity | Provide a quantity greater than zero you wish to order. | Integer | Yes | Digits 0-9 |
| amount | Specify the value of the eGifts. Note: Allowed values vary based on the merchant and eGift. For more information consult with your Account Manager. | Number | Yes | Digits 0-9 and period. May not contain symbols and may have up to two digits after the decimal separator. Example: 25.00 |
| contentProvider | This identifier specifies which product you are ordering. | String | Yes | A valid content provider code as provided by your account manager or returned by the Catalog API. |
In our example we're going to place an order for three $25 Best Buy® eGifts, so our order details JSON will look like this:
{
"clientRefId": "ABC12345",
"quantity": "3",
"amount": "25",
"contentProvider": "BestBuy_eGift"
}
Submitting the Order
Now we will go ahead and put all that information together to place our eGift order.
To do that we will make an HTTP POST request to https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitEgiftBulk, sending the header parameters as we outlined above, with the following JSON in the body of the request.
{
"clientProgramNumber": "43251304",
"paymentType": "ACH_DEBIT",
"poNumber": "2345",
"returnCardNumberAndPIN" : "false",
"orderDetails": [{
"clientRefId": "ABC12345",
"quantity": "3",
"amount": "25",
"contentProvider": "BestBuy_eGift"
}]
}
The API will return a response containing an HTTP status code in the header and a JSON object in the body. This response will tell us if the order was successful and if it has been completed or not.
The following HTTP status codes may be returned in the response header.
| HTTP Status Code | Meaning | Notes |
|---|---|---|
| 201 | Operation Complete | If isCompleted is not equal to "true" and percentComplete is not 100 check the status of the order before retrieving the codes to ensure it has completed. |
| 202 | Operation is in Process | If isCompleted is not equal to "true" and percentComplete is not 100 check the status of the order before retrieving the codes to ensure it has completed. |
| 4XX | Invalid Request | Check the JSON error response provided. In most cases you will find the request had missing information or was formatted improperly. If you have any questions reach out to your Account Manager. |
| 5XX | System Error | Blackhawk Network encountered an internal error trying to process your order. Reach out to your Account Manager for more information. |
What to do if the order is still processing
If the order is still processing and we have exceeded the millisecondsToWait value (or the maximum timeout of 30 seconds) the JSON in the response returned will indicate that the order has not yet completed and the current percent complete. For example we may see a response like this:
{
"transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
"isCompleted": false,
"percentComplete": 66,
"success": false
}
When this happens the transaction becomes asynchronous. We need to wait some time and then make an HTTP GET request to orderInfo to see if the order has completed processing.
Next steps when the order has completed processing
Assuming our order was placed successfully we receive the following JSON in the response:
{
"transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
"isCompleted": true,
"percentComplete": 100,
"success": true,
"orderNumber": "401087290"
}
This indicates we have successfully placed an order. The next step is to fetch the eGifts that we just ordered.
Step 2: Retrieving the eGifts
Now we have successfully placed our order we need to fetch our eGifts.
To retrieve the eGifts we will be using eGiftBulkCodeRetrievalInfo/byKeys.
| Method | Service Name | Service Type |
|---|---|---|
| GET | eGiftBulkCodeRetrievalInfo/byKeys → Explore | Synchronous |
URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/eGiftBulkCodeRetrievalInfo/byKeys?orderNumber=<Order Number>
HTTP Header
Since this is an HTTP GET request, all our parameters are in the header or the URL query parameters. We are going to provide the following information in the request:
| Parameter | Description | Required | Provide In |
|---|---|---|---|
| orderNumber | The order number received in the response from the submitEgiftBulk service. | Yes | Query |
| requestId | A unique identifier for each request provided by the caller. | Yes | Header |
| merchantId | The Merchant ID (MID) is a string identifier issued by BHN to each merchant for billing purposes. | Yes | Header |
The orderNumber has to be provided in the query string but the requestId and clientProgramNumber need to be provided in the header.
Let's go ahead and send the request to retrieve our eCodes.
To do that we make an HTTP GET request to:
https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/eGiftBulkCodeRetrievalInfo/byKeys?orderNumber=401087290, sending the header parameters outlined above.
GET https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/eGiftBulkCodeRetrievalInfo/byKeys?orderNumber=401087290 HTTP/1.1
Content-Type: application/json
merchantId: 1234
requestId: 2019-06-19T15:25:42-0500
If the order has not yet finished processing the response will indicate this in the orderStatus property. Below is an example of what that response could look like:
{
"clientProgramNumber": 43287904,
"orderNumber": "401087307",
"orderStatus": "Funding Hold",
"quantity": 0
}
Note: The
orderStatusproperty is only returned when the eGifts are not ready for pickup. If they are ready to pickup the call will return the eGifts without theorderStatusproperty present.
Let's assume in our case the order has finished processing and the eGifts are ready for pickup.
We now receive a JSON response providing us our eGift details. In our case we did not request the card numbers and pins so we only receive the Blackhawk Network eGift URLs.
{
"clientProgramNumber": 43287904,
"orderNumber": "401087307",
"quantity": 3,
"eGifts": [
{
"url": "https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=489H0YMJRDG4LLPVMD3FGBQTQ4",
"contentProviderCode": "BestBuy_eGift",
"amount": 25
},
{
"url": "https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=F71SD1XH9KMTDF2APBCVLDQLJH",
"contentProviderCode": "BestBuy_eGift",
"amount": 25
},
{
"url": "https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=Z6BWA51S8BN9TZW4JPW719LNT8",
"contentProviderCode": "BestBuy_eGift",
"amount": 25
}
]
}
If we had passed the returnCardNumberAndPIN with a value of "true" in the original order request we would have received the following response instead:
{
"clientProgramNumber": 43287904,
"orderNumber": "401087311",
"quantity": 3,
"eGifts": [
{
"url": "https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=G5LT612T2W7RSM31C9MHJA7PCW",
"contentProviderCode": "BestBuy_eGift",
"amount": 25,
"pin": "1713",
"barCodeValue": "9877880000001851713",
"cardNumber":"9877880000001851713"
},
{
"url": "https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=SXJLYQC6588WQSVVRSTBXT00A0",
"contentProviderCode": "BestBuy_eGift",
"amount": 25,
"pin": "1353",
"barCodeValue": "9877880000001851353",
"cardNumber": "9877880000001851353"
},
{
"url": "https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=YD1KFVHH5N5C0W2FKM6T7YQ3S8",
"contentProviderCode": "BestBuy_eGift",
"amount": 25,
"pin": "8125",
"barCodeValue": "9877880000001858125",
"cardNumber": "9877880000001858125"
}
]
}
The URLs returned directly link to the eGift. The eGift can be presented to the retailer on the recipient's phone, printed out or added to a mobile wallet (where supported).
Example Best Buy eGift
We have now completed a successful bulk eGift order and have retrieved our codes.
Updated 24 days ago