Digital Gift Services


The Digital Services Developer Hub

Welcome to the Digital Services developer hub. You'll find comprehensive guides and documentation to help you start working with Digital Services as quickly as possible, as well as support if you get stuck. Let's jump right in!

Dropship Ordering Overview

Introduction

Blackhawk provides a Dropship interface for partners to place batch orders as an alternative to the REST APIs.

This interface can be useful when sending larger B2B orders or batching multiple B2C order together. The file specifications are XML-based and securely transferred between the parter and Blackhawk Network via Secure FTP (SFTP) with/without PGP file encryption.

Your Implementation Manager will work with you to setup the Managed File Transfer (MFT) connections.

Overview

Blackhawk Network's Order Central Dropship Order specifications XMLs’ is a flexible file specification used by Blackhawk’s Digital Distribution Partner (DDP) for drop shipping e-commerce customer sales orders.

These specifications allow for a partner order management platform to integrate to Order Central (OC) to handle:
a) Inbound Dropship Order request
b) Outbound Order Confirmation notification (OC)
c) Outbound Shipment Notification (SN)

The inbound dropship order has the flexibility to place new CUSTOMER card orders that are B2C, B2B and B2B2C in nature. To support the different user-experiences, the dropship order request specification provides the option to specify:

  • Type of card [Physical]
  • Card details [quantity, denomination]
  • How to package the physical card with inserts, greeting cards, etc.
  • How to personalize the card (when applicable)
  • Where to ship the card [Shipping address/email]
  • How to ship the card [Shipping Method]
  • Shipping Cost
  • (Optionally) Personalize Custom Carrier Message
  • (Optionally) Personalize Activation Characteristics
  • etc.

Fulfillment Process Overview

  1. Digital Distribution Partner places an order-request (OR) for new card(s)
  2. Upon receipt of the OR, Order Central will validate and verify if
    a. The order is compatible with Order Central's dropship order specifications. If not, the entire file will be rejected immediately.
    b. The order includes mandatory minimal info [packaging type, product, denomination, shipping info, etc.,] to properly fulfill
    c. The product(s) requested are in DDP’s catalog
    d. Etc.
  3. Upon validation, Order Central sends back an Order Confirmation to Digital Distribution Partner, indicating acceptance or rejection of the order request.
  4. Post order acceptance Order Central
    a. Enriches the order with mandatory data
    b. Submits OFR file to specified FSP
    c. Manages life cycle of order fulfillment process.
    i. When order is shipped, several OPTIONAL card transactions are generated including activation.
  5. Order Central sends Shipment Notification (SN) back to Digital Distribution Partner as each item is fulfilled.
  6. CSR have access to operational console for order tracking
Dropship Process Flow Diagram

Dropship Process Flow Diagram

Changes to Blackhawk Network Specification Elements

Blackhawk Network reserves the right to make minor enhancements to the dropship specifications. Minor enhancements will be backward compatible.

Distribution Partner should build their client applications to gracefully handle the following types of changes to Blackhawk Network responses:

  • New request/response elements. Your client applications should handle new, unrecognized request/response elements.
  • New request/response element values. Your client applications should handle new, unrecognized request/response element values.

Best Practices

What does it mean to "gracefully handle" changes? Here are some examples:

  • Expect changes. At a minimum, ensure that your client applications do not break when new request/response elements, request/response element values, file fields or file field values are introduced by Blackhawk. Don’t code your client applications to expect only certain elements, fields, and values.
  • Log unrecognized elements, fields, or values. Keep a log of all unrecognized elements, fields, or values returned by Blackhawk. You can use this log to flag new functionality that has been introduced by Blackhawk, and then update your client application to take advantage of this functionality.
  • Surface unrecognized elements, fields, or values. If Blackhawk begins sending a file with a new field, for example, you might devise a way to automatically surface the new field values in your client application in a way that is useful to your users.
  • Expect request elements in any order. Request elements can be submitted in any order within a structure. Ensure that your client applications do not depend on the order in which Blackhawk sends request/response elements.

Basic Structure

The basic structure of Order Central’s XML is

  • A dropship xml file is a collection of orders
  • An Order element is a collection of Line Items
  • A line item describes;
    • Product Item Identifier – Unique product IID that identifies which card is ordered
    • Carrier identifier – Unique carrier ID that identifies which carrier will be used to affix card on
    • Denomination – Denomination value per card
    • Quantity – Number of cards ordered
    • Card personalization – Name on card and message on card
    • Carrier Personalization – Name and Message on carrier
    • Shipping information – Where to ship, shipping method, shipping cost
    • BOMID – The Bill of Material to be packaged with the card product

Before examining the XML, it is worth going over a couple important points about file and XML formatting:

  • xsd validation should be run against the xml file and xsds before sending the xml files.
  • All attributes and free text must be properly escaped, i.e., XML-safe. Alternatively, free text can be enclosed in a CDATA tag to avoid the need for escaping, but the string “]]>” will terminate a CDATA block, and so must be stripped from the enclosed text to ensure valid XML. Most of the examples in this document use CDATA sections for free text, especially for address fields.
  • OC requires the file encoding to match the encoding specified in the XML tag. If the two encodings disagree, the file encoding will be observed.
  • The use of extended Unicode characters is highly discouraged. This is because many fonts OC uses for printing are limited to ASCII characters.
  • Additionally, many of OC shippers will not accept packages addressed with non-ASCII characters.
  • FSP shall share either a whitelist or blacklist of acceptable characters, for shipping, card embossing, and carrier, etc.
  • Pass thru attributes (e.g., fulfillment instructions) may be encoded (base64, etc.) from the Digital Partner and pass-thru as-is to the FSP. Order Central does not perform any content validation and its expected that the FSP will decode these values (specifically, fulfillment instructions)

Checks and Balances

XSD Validation

Blackhawk expect all files received from DDP conforms to the files specifications. It is highly recommended that DDP perform real-time XSD validation of any order-request XML file generated prior to sending the file to Order Central.

Where to find XSDs

The XSD for each order file is presented in-line on each file page in this section and can be copied in a single click.

Monitoring of Order Confirmation and Shipment Notification files

Where possible, it is highly recommended the partner monitor for files not received. Example, if an Order Confirmation is expected within 1hr of sending an Order Request, a suitable notification or follow-on action may be appropriate.

Also, should Order Confirmation include REJECTION messages, a suitable notification or proactive follow-on action may be appropriate.

Rejection reasons vary and may include (but not limited to):

  • Invalid Product Specified resulting in fulfillment delays
  • Invalid Ship To Info (due to special characters, incomplete address, etc.) resulting in rejected items

Escalate to your Account Manager or contact Blackhawk Network's OCC as soon as possible to remediate issues as soon as possible.

File Rejections

It is possible that due to invalid file format/ xml format the file is rejected. Order central tries to send Order confirmation for most of the invalid file scenarios but it may not capture partnerordernumber since order request file was completely read due to invalid format. Please refer the external dropship id in the file for reference to the actual order request.

<?xml version="1.0" encoding="UTF-8"?> 
<dropshiporderconfirmation> 
<version>3.0</version> 
<externaldropshipid>77143925</externaldropshipid> 
<partneridentifier>ORDERCENTRAL10</partneridentifier> 
<status>rejected</status> 
<reasonforrejection><![CDATA[cvc-type.3.1.3: The value 'HELLO, thanks for the' of element 'messageoncard' is not valid.]]></reasonforrejection> 
</dropshiporderconfirmation>

Updated 5 months ago

Dropship Ordering Overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Developer Central Agreement

  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.

I Agree