Introduction

This tutorial describes the processes to create an an account using Blackhawk Digital Services. It summarizes steps taken by the consumer and processes undertaken in the background via Blackhawk Digital Services in support of creating the account and associating the account with a card. It also details the services and operations that provide the functionality enabling the account creation. Use it to learn how your application creates an account when a customer purchases a card from your application.

Process Summary

A Blackhawk distribution partner's application lists available products for purchase, as defined by the product catalog provided by Blackhawk. A consumer using the application selects a product and provides required product information and payment information, to complete the card purchase. This results in the customer being sent either a redemption code or stored value card for viewing. The customer can then send the redemption code or stored value card to a recipient.

Offline Processes

1. The partner application calls the Read All Product Catalogs API from the Product Catalog Management Service and receives a response containing a list of product catalog IDs.
2. The application calls Read Product Catalog API from the Product Catalog Management Service for all productIds return from Step 1 above and receives a response containing a list of product IDs.
3. The application calls Read Product from the Product Management Service for every productId provided by the response in Step 2. The response includes product information for each productId -- such as product image, terms and conditions, activation instructions product description, and so on -- which is cached by the application in order to display the list of products for sale.
4. If the application displays brand information, then it calls Read Product Line from the Product Line Management Service with the productLineId associated to every product in the product catalog, which is cached by the application in order to display the list of available brands.

📘

Offline Processes

Offline process refers to a process used by a client application to execute a set of API calls that retrieve all brand and product metadata. Learn More

Create account: What happens

1. The user opens the application, either on the desktop or on a mobile device, and navigates to the list of available products for purchase. The application uses the data cached from the offline processes (Steps 3 and 4, above) to display brand and product information.

2. The user selects a product to purchase and provides payment information. Note: Blackhawk doesn't require a user to be notified to review/accept terms and conditions.

3. The application calls the createAccount API from the Account Processing services, passing the following product information:

   1. The product entityId is mapped to the productId.
   2. Product currency is mapped to currency.
   3. Map the product amount to amount. amount needs to be on or between the product minimum and maximum.
   4. Map a unique GUID value to the requestId.
   5. Map a unique 12-digit value to retrievalReferenceNumber to be used for reconciliation on the Settlement Detail file.

4. If the createAccount does not return a response:

   1. Call the createAccount with the same parameters from Step 3 above at least three times over a period of time.
   2. Set previousAttempts to 1 and for each subsequent call of createAccount increment by 1, so the next value is 2.
   3. If the createAccount does not return a response, then call reverseTransaction from the Account Processing Service and map the requestId from Step 3 to reversalTxnRequestId
   4. If the reverseTransaction does not respond, contact Blackhawk Customer Service

5. If the createAccount returns a 502 or 504 timeout, do the following:

   1. Call reverseTransaction from the Account Processing Service and map the requestId from Step 3 to reversalTxnRequestId.
   2. If reverseTransaction does not respond, contact Blackhawk Customer Service. Note: the reverseTransaction operation is time bound and usually can be called after a certain time frame. The reverseTransaction API should not be confused with voidAccount; reverseTransaction is to be used only for system exceptions (see How Reverse Works).

6. The user has the following options for delivery:

   1. If the application provides the redemption display, then it can use a combination of the cached product assets from the Read Product call (offline processes, Step 3) and account assets from the createAccount call. It then uses the account’s accountNumber (card number/redemption code) and security code (PIN) to display card information.
   2. If the application enables the user to save the account to a digital wallet (bag) with other stored value cards, then the user clicks to save the card to the application. If a bag is not created by the app, see the steps below, otherwise update cards in the bag and call Update Bag from the Bag Management Service.
      1. To create a bag, the app calls Create Person from the Person Management Service , providing information about the user.
      2. The application calls Create Bag from the Bag Management Service mapping the Person ID mapped to ownerId created in Step 1.
      3. The application maps the account’s accountNumber and securityCode (optional) from the createAccount response to a card in the bag.
         4.The application calls Update Bag
   3. If the application enables the user to send the card to a recipient, then the user can elect to do so. The application provides information about the card and associated account through SMS, in-app gift acceptance, email, or another method for delivering the card to the recipient.

7. If the product sold supports void in the case a user that purchased a prepaid product/gift card and wants to return it, then the application can call the voidAccount from the Account Processing Service.

   1. Check the cached brand information to see if the product can be voided. The product line supported feature section should have VOID_ACTIVATION.
   2. If supported, call voidAccount with the account entityId mapped to the accountTxnId.
   3. Check that isVoid is set to true on the account transaction.

📘

Note

Offline process refers to a process used by a partner application to execute a set of API calls that retrieve all brand and product metadata. That data is cached by the partner’s application. With that data, the partner can manage the content displayed through their application and optimize the user experience for selling eGifts or managing a gift card in a digital wallet.

Blackhawk recommends partners retrieving product and product line information in an offline process in order to minimize the number of calls made by the application and to control when content is updated on their application.