Individual Virtual Prepaid Orders

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.

Method

Service

API

Type

POST

rewardsOrderProcessing

submitVirtualIndividual → Explore

Hybrid synchronous/asynchronous based on millisecondToWait parameter

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

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

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.

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

emailContent

Content for the email delivered to the recipient

Object

Yes

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

recipient

Information about the recipient for this virtual account

Object

Yes

Valid Recipient Object

amount

Specify the value of the account. Note: Allowed values vary by product. 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

description

Description for the order. Must be 40 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space and period.

Providing the Recipient Information

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

Parameter

Description

Type

Required

Allowed Values

id

Id must be 30 characters or less.

String

No

Digits 0-9, Alpha (a-z, A-Z) and period.

firstName

First name of the recipient, this must be 50 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

lastName

Last name of the recipient, this must be 50 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

email

The email address of the intended recipient. Must be 90 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), period and hyphen.
Format: Must have an @ symbol and at least one period.

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

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.

Parameter

Description

Type

Required

senderName

This is the name of the sender as shown on the email. This cannot exceed 50 characters.

String

Yes

senderEmail

The sender email address as shown on the email. This cannot exceed 90 characters.

String

Yes

subject

The email subject line. This cannot exceed 200 characters.

String

Yes

emailMessage

The message to the recipient of the email. See the example template image below. This cannot exceed 10,000 characters.

The following tokens can be included and will be dynamically replaced in the recipient email:

  • {first name}
  • {last name}
  • {amount}
  • {email address}

String

Yes

emailClosingName

The name used to sign off at the bottom of the email. This cannot exceed 200 characters.

String

Yes

isDefaultTemplate

This can be used to save these values as the default for future use.

Boolean

No

unsubscribeData

Information required to inform recipients on how to unsubscribe from emails.

Object

Yes

Providing Unsubscribe Data

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

Parameter

Description

Type

Required

companyName

Cannot exceed 50 characters.

String

Yes

addressLine1

Cannot exceed 200 characters.

String

Yes

addressCity

Cannot exceed 100 characters.

String

Yes

addressState

addressState must be a valid 2-character uppercase abbreviation for a U.S. state
or a Canadian province or contain an international region less than 36 characters.

String

Yes

addressZip

Must be a valid 5-digit U.S. zip code or a valid international postal
code less than 11 characters.

String

Yes

addressCountry

Must be either USA or CAN.

String

Yes

methodType

Must be one of the following: EMAIL, WEBSITE, NONE.

String

Yes

value

This is the detail for the unsubscribe method. Typically an email address or website URL. Cannot exceed 255 characters.

String

Yes

For our example we will be 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",
    "emailClosingName": "Jane Doe",
    "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]"
    }
  },

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.

14911491

🚧

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",
    "emailClosingName": "Jane Doe",
    "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."
 }]
}

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

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.


Did this page help you?

Developer Agreement

Note: You will not be able to click "I Agree" until you have reached the bottom of this agreement.

This Developer Agreement (“Agreement”) is an agreement between you and Blackhawk Network, Inc. (“Blackhawk”) that applies to your access to and use of Blackhawk Developer Central (“Developer Portal”) located at https://developer.blackhawknetwork.com and related application programming interfaces (API), sandbox environments, digital certificates, tools, materials and documentation made available by Blackhawk (collectively, including all updates and other modifications thereto, the “Blackhawk Developer Tools”). You must read, agree with and accept all of the terms and conditions contained in this Agreement. By registering for or accessing the Developer Portal, and/or using the Blackhawk Developer Tools, you or the entity that you represent acknowledge that you have read, understand and agree to be bound by this Agreement. If you do not agree to these terms and conditions, you may not access the Developer Portal or use the Blackhawk Developer Tools.

This Agreement and the Terms of Use apply to your access to and use of the Blackhawk Developer Tools. For clarity, the Developer Portal and Blackhawk Developer Tools are “Services” provided to you under the Terms of Use, or “Blackhawk Services”. In the event of any inconsistency between this Agreement and the Terms of Use, the terms of this Agreement will control. Blackhawk reserves the right, at our sole discretion, to change or modify portions of this Agreement at any time. If we do this, we will post the changes on this page. Any such changes will become effective once they are posted.

  1. License from Blackhawk. Subject to your full compliance with all of the terms and conditions of this Agreement and the Terms of Use, Blackhawk grants you a non-exclusive, revocable, non-sublicensable, nontransferable license to use and integrate the Blackhawk Developer Tools into your Application solely to test them in Blackhawk’s sandbox environment.
  2. Passwords, Credentials and Access. Blackhawk will provide (or you will be requested to establish) a password or other procedures for verifying that only designated personnel have access to Blackhawk Developer Tools. Blackhawk may provide you with unique confidential identification codes, credentials and certificates that enable you to use the Blackhawk Developer Tools. You may not share any such items with any third party without the prior written consent of Blackhawk, and you agree to notify Blackhawk immediately of any violation of your foregoing obligations. You are responsible for maintaining the security of your account, passwords, credentials, codes, certificates and other files, and for all uses of your account, and you are liable for all activities performed under your account or otherwise with your credentials, codes and certificates.
  3. Restrictions and Obligations. You may not use the Blackhawk Developer Tools for any purpose other than as expressly set forth herein without Blackhawk’s prior written consent, including without limitation to access Blackhawk user data or information without authorization or in any manner or for any purpose that violates any law or regulation or any right of any person (including but not limited to intellectual property rights or rights of privacy). You may not use the Blackhawk Developer Tools to build a product or service that is competitive with the Blackhawk Services, or engage in any practices that discriminate against or discourage the use of Blackhawk Services. In addition, you shall not use the Blackhawk Developer Tools or Blackhawk Services in connection with or to promote any Applications or other products, services, or materials that constitute, promote or are used for the purpose of dealing in: spyware, adware, or other malicious programs or code; counterfeit goods; items subject to U.S. embargo; unsolicited mass distribution of email; multi-level marketing proposals; hate materials; hacking/surveillance/interception/descrambling equipment; libelous, defamatory, obscene, pornographic, abusive or otherwise offensive content; prostitution; gambling; stolen products or items used for theft; fireworks, explosives, or hazardous materials; or weapons. Without limiting the foregoing, you shall not use the Blackhawk Developer Tools or Blackhawk Services for any illegal purpose. Except as expressly and unambiguously authorized under this Agreement, you may not (i) copy, rent, lease, sell, transfer, assign, sublicense, disassemble, reverse engineer or decompile (except to the limited extent such restrictions are expressly prohibited by applicable statutory law), modify or alter any part of the Blackhawk Developer Tools or Blackhawk Services, or (ii) otherwise use the Blackhawk Developer Tools or Blackhawk Services on behalf of any third party.   You may not use any robot, spider, or other automatic device to create accounts for use of the Blackhawk Developer Tools and you will not take any action that imposes an unreasonable or disproportionately large load on Blackhawk’s infrastructure.
  4. Support; Other Conditions of Use. Blackhawk may provide you with support or modifications for the Blackhawk Developer Tools (collectively, “Support”) in its sole discretion. Blackhawk may terminate such Support at any time without notice to you. Blackhawk may change, suspend, or discontinue any aspect of the Blackhawk Developer Tools, at any time, including the availability of any APIs. Blackhawk may release subsequent versions of APIs, and you may be required to use those subsequent versions. Blackhawk may also impose limits on certain features and services or restrict your access to parts of or all of the Blackhawk Developer Tools without notice or liability. Your networks, operating systems, software, web server(s), routers, databases and other computer systems must be properly configured to Internet industry standards, as required to securely operate your Application.
  5. Sandbox Environment; Data. You may use the sandbox environment provided as part of the Blackhawk Developer Tools (“Sandbox”) in order to test the Blackhawk Services. If you access the Sandbox with a digital certificate provided by Blackhawk, your use of the Sandbox and any data or information you input into the Sandbox will be available only to users that access the Developer Portal with your account. Important: If you access the Sandbox without a digital certificate provided by Blackhawk, your use of the Sandbox, and any data or information that you input into the Sandbox, will be available to all users that access the Developer Portal. You may only use anonymous, non-live data and you may not enter any confidential, sensitive or personally identifiable information into the Sandbox. Data and other information provided to or made available in the Sandbox is not encrypted. Blackhawk will have no responsibility or liability for any information you enter into the Sandbox, or otherwise from your use of the Sandbox. You are fully responsible for the security of any data or information you provide in connection with the Developer Portal, and you must comply with all applicable laws and rules in connection with your provision and use of such data and information.
  6. Proprietary Rights. As between you and Blackhawk, the Blackhawk Developer Tools, Blackhawk Services and all intellectual property rights therein are and shall at all times remain the sole and exclusive property of Blackhawk and are protected by applicable intellectual property laws and treaties. As between you and Blackhawk, your Application and all intellectual property rights therein (but excluding any Blackhawk intellectual property therein) are and shall at all times remain your sole and exclusive property. You acknowledge and agree that any questions, comments, suggestions, ideas, feedback or other information about the Blackhawk Developer Tools or Blackhawk Services (“Submissions”), provided by you to Blackhawk are voluntary, non-confidential and Blackhawk will be entitled to the unrestricted use and dissemination of these Submissions for any purpose, commercial or otherwise, without acknowledgment or compensation to you.
  7. Trademarks. This Agreement does not include any right for you to use any trademark, service mark, trade name or any other mark of Blackhawk or any other party or licensor. You agree that Blackhawk may list your name and/or your Application (including by displaying any trademarks related thereto) and identify the business relationship between the parties on Blackhawk’s websites, the Blackhawk Services and in other marketing and advertising collateral. No rights or licenses are granted except as expressly and unambiguously set forth herein.
  8. Confidentiality. “Confidential Information” means all information related to the Developer Portal, including but not limited to the following: (i) any information you receive or enter via the Blackhawk Developer Tools (including the sandbox environment), (ii) the Blackhawk Developer Tools and all related information and materials, including without limitation API credentials and all access IDs and passwords, (iii) all information disclosed in writing and marked “confidential”, proprietary,” or with a substantially similar marking, (iv) all information disclosed orally and identified as confidential at the time of the disclosure, and (v) any other information that by its nature you understand or would reasonably be expected to understand to be Blackhawk’s confidential information. You must maintain Blackhawk’s Confidential Information in confidence and must not disclose it to third parties or use it for any purpose other than as necessary and required to develop your Application as permitted herein. In the event that Confidential Information is required to be disclosed by a court, government agency, regulatory requirement, or similar disclosure requirement, you shall immediately notify Blackhawk and use reasonable efforts to obtain confidential treatment or a protection order of any disclosed Confidential Information. Your obligations hereunder shall survive the termination of this Agreement. You acknowledge that monetary damages may not be a sufficient remedy for unauthorized use or disclosure of Confidential Information and that Blackhawk will be entitled (without waiving any other rights or remedies) to injunctive or equitable relief as may be deemed proper by a court of competent jurisdiction, without obligation to post any bond.
  9. Warranty Disclaimer. THE BLACKHAWK DEVELOPER TOOLS AND BLACKHAWK SERVICES ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND. BLACKHAWK AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, REGARDING THE BLACKHAWK DEVELOPER TOOLS AND BLACKHAWK SERVICES, INCLUDING WITHOUT LIMITATION ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, ACCURACY, RESULTS OF USE, RELIABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, INTERFERENCE WITH QUIET ENJOYMENT, AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. FURTHER, BLACKHAWK DISCLAIMS ANY WARRANTY THAT YOUR USE OF THE BLACKHAWK DEVELOPER TOOLS OR BLACKHAWK SERVICES WILL BE UNINTERRUPTED OR ERROR FREE.
  10. Limitation of Liability. REGARDLESS OF WHETHER ANY REMEDY SET FORTH HEREIN FAILS OF ITS ESSENTIAL PURPOSE OR OTHERWISE, AND EXCEPT FOR BODILY INJURY, IN NO EVENT WILL BLACKHAWK OR ITS SUPPLIERS BE LIABLE TO YOU OR TO ANY THIRD PARTY UNDER ANY TORT, CONTRACT, NEGLIGENCE, STRICT LIABILITY OR OTHER LEGAL OR EQUITABLE THEORY FOR (A) ANY LOST PROFITS, LOST OR CORRUPTED DATA, COMPUTER FAILURE OR MALFUNCTION, INTERRUPTION OF BUSINESS, OR OTHER SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING OUT OF THE USE OR INABILITY TO USE THE BLACKHAWK DEVELOPER TOOLS OR BLACKHAWK SERVICES, EVEN IF BLACKHAWK HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES AND WHETHER OR NOT SUCH LOSS OR DAMAGES ARE FORESEEABLE, OR (B) ANY DAMAGES RELATING TO THE BLACKHAWK DEVELOPER TOOLS OR YOUR USE THEREOF. 
  11. Indemnification. You agree that Blackhawk shall have no liability whatsoever for any use you make of the Blackhawk Developer Tools or Blackhawk Services. You shall indemnify and hold harmless Blackhawk from any and all claims, damages, liabilities, costs and fees (including reasonable attorneys’ fees) arising from your Applications or otherwise from your use of the Blackhawk Developer Tools or Blackhawk Services, or your breach of this Agreement.
  12. Term and Termination. This Agreement shall continue until terminated as set forth in this Section. Either party may terminate this Agreement upon written notice to the other party at any time, for any reason, or for no reason including, but not limited to, if you violate any provision of this Agreement. Any termination of this Agreement shall also terminate the license(s) granted hereunder. Upon termination of this Agreement for any reason, you shall destroy and remove from all computers, hard drives, networks and other storage media all copies of the Blackhawk Developer Tools, and shall so certify to Blackhawk upon request that such actions have occurred. Sections 2, 3 and 6 through 13 and all accrued rights to payment (if any) shall survive termination of this Agreement.
  13. Government Use. If you are part of an agency, department, or other entity of the United States Government (“Government”), the use, duplication, reproduction, release, modification, disclosure or transfer of the Blackhawk Developer Tools are restricted in accordance with the Federal Acquisition Regulations as applied to civilian agencies and the Defense Federal Acquisition Regulation Supplement as applied to military agencies. The Blackhawk Developer Tools is a “commercial item,” “commercial computer software” and “commercial computer software documentation.” In accordance with such provisions, any use of the Blackhawk Developer Tools by the Government shall be governed solely by the terms of this Agreement.
  14. Export Controls. You shall comply with all export laws and restrictions and regulations of the Department of Commerce, the United States Department of Treasury Office of Foreign Assets Control (“OFAC”), or other United States or foreign agency or authority, and you shall not export, or allow the export or re-export of the Blackhawk Developer Tools or Blackhawk Services in violation of any such restrictions, laws or regulations. By accessing or using the Blackhawk Developer Tools, you agree to the foregoing and represent and warrant that you (and the organization you represent, if any) are not located in, under the control of, or a national or resident of any restricted country.
  15. Miscellaneous. Unless the parties have entered into a written amendment to this agreement that is signed by both parties regarding the Blackhawk Developer Tools or the Blackhawk Services, this Agreement constitutes the entire agreement between you and Blackhawk pertaining to the subject matter hereof, and supersedes any and all written or oral agreements with respect to such subject matter. This Agreement, and any disputes arising from or relating to the interpretation thereof, shall be governed by and construed under California law without reference to its conflict of laws principles or the United Nations Conventions on Contracts for the International Sale of Goods. Except to the extent otherwise elected by Blackhawk, any action or proceeding arising from or relating to this Agreement must be brought in a federal court in the Northern District of California or in state court in San Francisco County, California, and each party irrevocably submits to the jurisdiction and venue of any such court in any such action or proceeding. The prevailing party in any action arising out of this Agreement shall be entitled to an award of its costs and attorneys’ fees. If any provision of this Agreement is held to be unenforceable for any reason, such provision shall be reformed only to the extent necessary to make it enforceable. The failure of Blackhawk to act with respect to a breach of this Agreement by you or others does not constitute a waiver and shall not limit Blackhawk’s rights with respect to such breach or any subsequent breaches. This Agreement is personal to you and may not be assigned or transferred for any reason whatsoever without Blackhawk’s prior written consent and any action or conduct in violation of the foregoing shall be void and without effect. Blackhawk may freely transfer or assign this Agreement and delegate any of its obligations hereunder.