Introduction

Bulk ordering allows you to acquire multiple virtual prepaid accounts to distribute directly. When placing a bulk order Blackhawk Network will not send the virtual account notification/information to the recipients on your behalf. You will be responsible for distributing the notifications, with the registration URL and virtual account redemption code, to the recipients directly.

There are two main steps to placing a bulk order:

1. Submit the order using submitVirtualBulk
2. Retrieve the codes using virtualCodeRetrievalInfo

In this guide we will be placing an order for two $50 Mastercard® Virtual Accounts.

📘

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

Step 1: Placing the Order

Our first step is to place the order via submitVirtualBulk.

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

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-06-12T15:35:28-0500
millisecondsToWait: 30000

Body Parameters

In the body of the POST request we need 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:

Submitting the Order

In our example we're going to place an order for two $50 Mastercard® Virtual Accounts.

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

{
    "clientProgramNumber": "43251255",
    "paymentType": "ACH_DEBIT",
    "poNumber": "1324",
    "orderDetails": [{
        "quantity": "2",
        "amount": "50"
    }]
}

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

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 accounts that we just ordered.

Step 2: Retrieving the Virtual Account Information

Now we have successfully placed our order we need to retrieve codes for the virtual accounts we have ordered.

To retrieve the codes we will be using virtualCodeRetrievalInfo.

URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/virtualCodeRetrievalInfo/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:

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 account information.

To do that we make an HTTP GET request to https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/virtualCodeRetrievalInfo/byKeys?orderNumber=401087290, sending the header parameters outlined above.

GET https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/virtualCodeRetrievalInfo/byKeys?orderNumber=401087290 HTTP/1.1
Content-Type: application/json
merchantId: 60300004707
requestId: 2019-06-19T15:25:42-0500

If the order has not yet finished processing the response will have a quantity of 0 and will not contain any virtual codes.. Below is an example of what that response:

{
   "clientProgramNumber": 43287904,
   "orderNumber": "401087290",
   "quantity": 0
}

Let's assume in our case the order has finished processing and the codes are ready for pickup.

We now receive a JSON response providing us our account information.

{
   "clientProgramNumber": 43287904,
   "orderNumber": "401087290",
   "quantity": 2,
   "virtualCodes":[{
         "code": "NN4QSHZSTNKF",
         "amount": 50
      },{
         "code": "DMSZ2YAZ6ASK",
         "amount": 50
      }
   ]
}

In order to use the virtual prepaid account the recipient needs to register their card. You will need to provide the required information, along with the code and registration URL so that the recipient can register the card to themselves.

❗️

Registering Virtual Accounts

Virtual account recipients need to be instructed to visit https://www.myprepaidcenter.com/redeem/ in order to redeem, activate and register their virtual account before it can be used.