Introduction

Real-time ordering allows you to place single orders for eGifts quickly. You are limited to placing a single order at a time but the eGift is returned more quickly and skips our internal order batching process.

📘

Want to skip the details? Jump right to the full order JSON

With this option you will receive either the URL to the eGift, or the eGift code and associated information, that you can use to present in your own application experience.

📘

When using the real-time APIs you can order only one eGift at a time.

Placing the Order for URL or Code Delivery

To place the order we will be using submitRealTimeEgiftBulk.

HTTP Header

From our application we need to send the following parameters in the HTTP header:

In our example we will be sending the following values in the header:

Content-Type: application/json
merchantId: 60300003779
requestId: 2019-07-02T17:30:10-0500
millisecondsToWait: 30000
SYNCHRONOUS_ONLY: true

Body Parameters

In the body of the POST request we need to send all the information needed to complete the order:

Providing the Order Details for URL or Code Delivery

We will pass the details for the order in the orderDetails object:

In our example we're placing a single order for one $25 Best Buy® eGift, so our order details JSON will look like this:

{
    "clientRefId": "egift1",
    "quantity": "1",
    "amount": "25",
    "contentProvider": "BestBuy_eGift"
}

Submitting the Order

Now we will go ahead and put 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/submitRealTimeEgiftBulk, 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": "egift1",
        "quantity": "1",
        "amount": "25",
        "contentProvider": "BestBuy_eGift"
    }]
}

The API will return a response to us 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.

Order has Completed Processing (URL or Code Delivery)

Assuming our order was placed successfully we will receive the eGift information directly in the JSON response.

{
   "transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
   "isCompleted": true,
   "percentComplete": 100,
   "success": true,
   "orderNumber": "401087978",
   "url":"https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=Z6BWA51S8BN9TZW4JPW719LNT8",
   "contentProviderCode": "BestBuy_eGift",
   "transactionAmount": 25
}

If we had passed the returnCardNumberAndPIN with a value of "true" in the original order request we would have received a response as follows instead:

{
   "transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
   "isCompleted": true,
   "percentComplete": 100,
   "success": true,
   "orderNumber": "401087978",
   "url":"https://egiftpp.blackhawknetwork.com/egift?tid=657Q0RGVTJTZKC50AW2P8STYQC&gcm=n&gs=n&gw=n&eid=Z6BWA51S8BN9TZW4JPW719LNT8",
   "contentProviderCode": "BestBuy_eGift",
   "transactionAmount": 25,
   "pin":"8125",
   "barCodeValue":"9877880000001851353",
   "cardNumber":"9877880000001851353"
}