Real-time Virtual Prepaid Orders
Introduction
Real-time ordering allows you to place single orders for virtual prepaid accounts quickly. You are limited to placing a single order at a time but the virtual prepaid account is delivered 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 the virtual prepaid account redemption code and associated information that you can use to present in your own application experience.
When using the real-time APIs you can only order one item at a time for a single recipient.
Placing the Order for Code Delivery
To place the order we will be using submitRealTimeVirtualBulk.
| Method | Service Name | Service Type |
|---|---|---|
| POST | submitRealTimeVirtualBulk â Explore | Hybrid synchronous/asynchronous based on millisecondToWait parameter. |
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 minimum required value for real-time requests is 15000 (15 seconds). | Integer | No | 2000 |
SYNCHRONOUS_ONLY | Applies only to real-time orders against certain programs processed by Blackhawk Network. If the value is true and the order processing is not completed within the initial order request's millisecondsToWait time, the order will be canceled 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: 60300004707
requestId: 2019-07-02T17:30:10-0500
millisecondsToWait: 30000
Body 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 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 |
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 | |
| thirdPartyInfo | Allows you to send end-client information needed for compliance with state and federal regulations. See Providing the Third Party Information for more information about the parameters in thirdPartyInfo.Your Implementation Project Manager will confirm if your integration requires you to pass the third party information. | Object | No | |
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 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 virtual prepaid account. | 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 |
In our example we're placing a single order for one $25 Virtual MasterCardÂŽ Prepaid Account, so our order details JSON will look like this:
{
"clientRefId": "123456",
"quantity": "1",
"amount": "25"
}
Submitting the Order
Now we will go ahead and put that information together to place our order.
To do that we will make an HTTP POST request to https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitRealTimeVirtualBulk, sending the header parameters as we outlined above, with the following JSON in the body of the request.
{
"clientProgramNumber": "43564408",
"paymentType": "ACH_DEBIT",
"poNumber": "2345",
"orderDetails": [{
"clientRefId": "123456",
"quantity": "1",
"amount": "25"
}]
}
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. |
| 202 | Operation is in Process | If isCompleted is not equal to "true" and percentComplete is not 100 the order has not 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. |
Order has Completed Processing (Code Delivery)
Assuming our order was placed successfully we will receive the virtual prepaid account information directly in the JSON response.
{
"transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
"isCompleted": true,
"percentComplete": 100,
"success": true,
"orderNumber": "401087978",
"virtualItemList":[{
"code": "NN4QSHZSTNKF",
"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.
Updated 15 days ago