Introduction

Individual ordering allows you to order one or many virtual prepaid accounts at the same time that are associated to an individual. In this case Blackhawk Network will send an email to the individual they can use to redeem and register their virtual prepaid account so it can be used for purchases or added to a digital wallet.

In this guide we will be placing an order for one virtual prepaid account with a value of $50.

Note: Blackhawk Network recommends a maximum of 1,000 order line items per order request. If you have more than 1,000 line items you will need to break your order into multiple order requests of 1,000 records each.

📘

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

Placing the Virtual Account Order

To place the order we will be using submitVirtualIndividual.

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

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: 60300004707
requestId: 2019-08-19T10:23:22-0600
millisecondsToWait: 30000

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

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

Providing the Recipient Information

We need to provide information about each recipient we are delivering a virtual card to:

Since we are placing a single order for $50 our JSON will look like this:

"orderDetails": [{
  "recipient": {
   "id": "",
   "firstName": "Abraham",
   "lastName": "Lincoln",
   "email": "[email protected]"
  },
  "amount": "50",
  "description": "This is a reward for Abraham Lincoln."
 }]

Providing Email Content

Email Content becomes required if email is not configured within Hawk Marketplace. Since these orders will be delivered via email, we need to provide some details for the order template that will be used in the emails that get sent to the end recipients.

Providing Unsubscribe Data

As you can see from the table above we also need to supply information about how the recipient can unsubscribe:

For our example we will populate the following information:

"unsubscribeData" : {
    "companyName" : "Blackhawk Network",
    "addressLine1" : "700 State Highway 121 Bypass Ste. 200",
    "addressCity" : "Lewisville",
    "addressState" : "TX",
    "addressZip" : "75067",
    "addressCountry" : "USA",
    "methodType" : "EMAIL",
    "value" : "[email protected]"
}

We need to take that JSON and add it to the JSON for our email content. Here is the sample JSON:

"emailContent": {
    "senderName": "Blackhawk Network",
    "senderEmail": "[email protected]",
    "subject": "Your Reward Has Arrived!",
    "emailMessage": "Dear {first name}, Thank you for participating in our program! Please enjoy your reward as a token of our appreciation",
    "unsubscribeData" : {
      "companyName" : "Blackhawk Network",
      "addressLine1" : "700 State Highway 121 Bypass Ste. 200",
      "addressCity" : "Lewisville",
      "addressState" : "TX",
      "addressZip" : "75067",
      "addressCountry" : "USA",
      "methodType" : "EMAIL",
      "value" : "[email protected]"
    }
  },

"emailContent": {},

Below we can see how all of this information maps to the email that gets sent to the recipient. Note that the unsubscribe information is at the very bottom of the email.

🚧

In order for the first and last name to show in the recipient email you must include the tokens {first name} and/or {last name} in the emailMessage attribute (dependent on your requirements).

Submitting the Order

Now it is time for us to combine all the information we have put together and actually place the egift order.

To do that we will make an HTTP POST request to https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitVirtualIndividual, sending the header parameters as we outlined above, with the following combined JSON in the body of the request.

{
 "clientProgramNumber": "12345",
 "paymentType":"ACH_CREDIT",
  "emailContent": {
    "senderName": "Blackhawk Network",
    "senderEmail": "[email protected]",
    "subject": "Your Reward Has Arrived!",
    "emailMessage": "Dear {first name}, Thank you for participating in our program! Please enjoy your reward as a token of our appreciation",
    "unsubscribeData" : {
      "companyName" : "Blackhawk Network",
      "addressLine1" : "700 State Highway 121 Bypass Ste. 200",
      "addressCity" : "Lewisville",
      "addressState" : "TX",
      "addressZip" : "75067",
      "addressCountry" : "USA",
      "methodType" : "EMAIL",
      "value" : "[email protected]"
    }
  },
 "orderDetails": [{
  "clientRefId":"1234567890",
   "recipient": {
   "id": "",
   "firstName": "Abraham",
   "lastName": "Lincoln",
   "email": "[email protected]"
  },
  "amount": "50",
  "description": "This is a reward for Abraham Lincoln."
 }]
}

{
 "clientProgramNumber": "12345",
 "paymentType":"ACH_CREDIT",
  "emailContent": {},
 "orderDetails": [{
  "clientRefId":"1234567890",
   "recipient": {
   "id": "",
   "firstName": "Abraham",
   "lastName": "Lincoln",
   "email": "[email protected]"
  },
  "amount": "50",
  "description": "This is a reward for Abraham Lincoln."
 }]
}

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.

What to do if the order is still processing aka isCompleted is not true

This happens if the order is still processing and we have exceeded the millisecondsToWait value (or the maximum timeout of 30 seconds). In that case 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 recipient email will now be automatically placed into a queue for delivery.