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

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>