Bulk Virtual Prepaid Orders

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.

Method

Service

API

Type

POST

rewardsOrderProcessing

submitVirtualBulk → Explore

Hybrid synchronous/asynchronous based on millisecondToWait parameter

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

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. The requestId must be unique with 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 recommended value is 15000 (15 seconds).

Integer

No

2000

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

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

This value in this attribute specifies the payment method to be used for the order.

Note: The payment type value provided must match one of the payment types setup on the client program you are placing an order in or your order request will be rejected.

String

No

ACH_DEBIT
WIRE_TRANSFER
DRAW_DOWN

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 financialAccountId the paymentType attribute is required.

A value for financialAccountId only needs to be provided when there are multiple financial accounts setup for a sub-organization. Your Implementation Project Manager or Account Manager will direct when you need to provide a value in this field.

String

No

The value provided must match a valid financial account ID configured for your sub-organization.

orderDetails

The products and quantities you wish to order.

Object

Yes

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

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

Parameter

Description

Type

Required

Allowed Values

clientRefId

Unique Client Reference Id 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

Provide a quantity greater than zero you wish to order.

Integer

Yes

Digits 0-9

amount

Specify the value of the accounts.

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

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.

HTTP Status Code

Meaning

Notes

201

Operation Complete

If isCompleted is not equal to "true" and percentComplete is not 100 check the status of the order before retrieving the codes to ensure it has completed.

202

Operation is in Process

If isCompleted is not equal to "true" and percentComplete is not 100 check the status of the order before retrieving the codes to ensure it has completed.

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.

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.

Method

Service Name

Service Type

GET

virtualCodeRetrievalInfo/byKeys → Explore

Synchronous

URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/virtualCodeRetrievalInfo/byKeys?orderNumber=<Order Number>

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:

Parameter

Description

Required

Provide In

orderNumber

The order number received in the response from the submitVirtualBulk service.

Yes

Query

requestId

A unique identifier for each order provided by the caller. This identifier will be used during reconciliation and facilitates idempotence.

Yes

Header

merchantId

The Merchant ID (MID) is a string identifier issued by BHN to each merchant for billing purposes.

Yes

Header

clientProgramNumber

The client program number the order was placed under

No

Header

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.

MyPrepaidCenter Virtual Account Redemption and Registration.MyPrepaidCenter Virtual Account Redemption and Registration.

MyPrepaidCenter Virtual Account Redemption and Registration.

❗️

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.


Did this page help you?