Real-time eGift Orders
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 | API Service | Endpoint | Service Type |
|---|---|---|---|
| POST | rewardsOrderProcessing | submitRealTimeEgiftBulk → Explore | Hybrid synchronous/asynchronous based on millisecondToWait parameter. |
URI: https://api.certification.blackhawknetwork.com/rewardsOrderProcessing/v1/submitRealTimeEgiftBulk
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 required value is | Integer | No | 2000 |
| SYNCHRONOUS_ONLY | If the value provided is true and the order processing is not completed within the initial order request's millisecondsToWait time the order will be cancelled and an HTTP 504 status code returned. | Boolean | No | false |
In our example we will be sending the following values in the header:
Content-Type: application/json
merchantId: 20200009887
requestId: 7894561231
millisecondsToWait: 30000
SYNCHRONOUS_ONLY: trueBody 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. |
| 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 A value for | String | No | The value provided must match a valid financial account ID configured for your sub-organization |
| 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. Your Hawk Marketplace client program must be configured to allow the retrieval of card numbers to use this feature. Note: This feature is not available for programs in international regions, please consult with your Onboarding Project Manager for guidelines specific to your region. | 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://api.certification.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 | The order was created successfully. |
| 202 | Operation is in Process | If For real-time orders with SYNCHRONOUS_ONLY set as true you will not receive a 202 response if the order has not completed within the |
| 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 | There was an internal error trying to process your order. Try again later, if the error persists please reach out to your Account Manager. |
| 504 | timeout | For real-time orders with SYNCHRONOUS_ONLY set as true you will not receive a 202 response if the order has not completed within the millisecondsToWait time. Instead the order will be canceled and you will receive a 504 status code. |
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
}{
"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,
"securityCode": ABC1234567
}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",
"activationAccountNumber":"1234567890"
}{
"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",
"activationAccountNumber":"1234567890",
"securityCode": ABC1234567
}Response Attribute Definitions
| Attribute Name | Required | Type | Description |
|---|---|---|---|
| transactionId | Yes | String | The BHN internal transactionId. |
| isCompleted | Yes | Boolean | Indicates if the order request has completed processing. This is for the order request only and does not reflect the state of order processing. |
| percentComplete | Yes | Integer | If the request has not completed processing this attribute indicates how far through processing the request BHN was when the millisecondsToWait time expired. |
| success | Yes | Boolean | For requests that have completed processing this indicates if the order request was successful and an order was created. This is for the order request only and does not reflect the state of order processing. |
| orderNumber | No | Integer | The order number created in Hawk Marketplace for this request. Only returned for successful requests where order processing has completed. |
| url | No | String | The redemption URL for the digital content. Always returned for successful order requests that have completed processing. |
| contentProviderCode | No | String | The content provider code associated with the order request. |
| transactionAmount | No | Number | The value associated with the digital content. |
| cardNumber | No | String | The card number associated with the digital content. Only returned where authorized, available and requested. |
| pin | No | String | The PIN code associated with the digital content. Only returned where authorized, available and requested. |
| barCodeValue | No | String | The bar code value associated with the digital content. Only returned where authorized, available and requested. |
| activationAccountNumber | No | String | The activation account number associated with the digital content. Only returned where authorized, available and requested. |
| securityCode | No | String | Indicates a security code must stored and delivered to the end recipient with Activationspot URL. |
Important Notes
- The Hawk Marketplace client program must be approved for and configured to allow the retrieval of card numbers in order for them to be returned in the response payload. Returning cards number and PIN data is not available for all use-cases, products and geographic regions. Note: For the UK the use of redemption links is required and card number and PIN data can not be returned.
- If the content provider does not support or provide a value for a specific attribute it will not be included in the response. For example, if the content provider cards do not use a PIN there will be no PIN attribute included in the response.
Updated 2 months ago