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.

Method	Service Name	Service Type
POST	submitRealTimeEgiftBulk → Explore	Hybrid synchronous/asynchronous based on millisecondToWait parameter.

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). This identifier will be used during reconciliation and facilitates idempotence.	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 required value is `15000` (15 seconds) or greater.	Integer	No	2000
SYNCHRONOUS_ONLY	Applies only to real-time orders against certain programs processed by Blackhawk Network. NOTE: If the value is true and the order processing is not completed within the initial order request's millisecondsToWait time, then the order will be cancelled.	Boolean	No	false

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

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	Specifies how you are going to pay for the order. This must be one of the specified allowed values.	String	Yes	ACH_DEBIT DRAW_DOWN
orderDetails	The product 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 for URL or Code Delivery

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	Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe.
quantity	Must be 1 for real-time orders.	Integer	Yes	Digits 0-9
amount	Specify the value of the eGift. 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	No	A valid content provider code as provided by your account manager or returned by the Catalog API.

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.

HTTP Status Code	Meaning	Notes
201	Operation Complete	If `isCompleted` is not equal to "true" and `percentComplete` is not 100 the order has not completed. For real-time orders with SYNCHRONOUS_ONLY set as true you will not receive a 201 or 202 response if the order has not completed within the `millisecondsToWait` time. Instead the order will be canceled and you will receive a 4XX code.
202	Operation is in Process	If `isCompleted` is not equal to "true" and `percentComplete` is not 100 the order has not completed. For real-time orders with SYNCHRONOUS_ONLY set as true you will not receive a 20X response if the order has not completed within the `millisecondsToWait` time. Instead the order will be canceled and you will receive a 4XX code.
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.

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"
}