This tutorial describes the processes that take place when a consumer reloads the value of a card using Blackhawk Digital Service. It summarizes steps taken by the consumer and processes undertaken in the background via Blackhawk Digital Services in support of the reload. It also details the services and operations involved. You can use it to help define and construct the parts of your application that enable your customers to reload the value of a card.
For best practices refer to our Reload a Gift Card Integration Guide
Reload feature is only available for Open loop cards
A Blackhawk distribution partner's application lets consumers reload gift cards. The consumer selects a card managed or purchased by the application and selects or enters an amount to add to the current value of the card, reloading it to a higher value. The diagram below shows the flow of a request initiated by a user to reload the value of a card.
- The partner application calls the Query All Product Catalogs API from the Product Catalog Management Service and receives a response containing a list of product catalog IDs.
- The application calls Read Product Catalog API from the Product Catalog Management Service for all product IDs return from Step 1 above and receives a response containing a list of product IDs.
- The application calls Read Product from the Product Management Service for every
productIdprovided 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.
- If the application displays brand information, then there is a call to Query Product Lines by Criteria API from Product Line Management Service based on locale and time stamp to get a list of available brands
- The application calls Read Product Line from the Product Line Management Service with the
productLineIdreturned in Step 4.
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
- If the user is purchasing a product for use through the application, follow Create an EGift for an application to get an account. The application uses the account's
entityIdto reload funds from a card created by generateEGift. Skip to Step 3.
- If the user has a physical card, then the user opens the application, either on the desktop or on a mobile device, and navigates to the feature that lets them manage a physical card.
- Using the product line data from the offline processes, the user's application can display a list of available Blackhawk Network brands for selection.
pinRequiredfield indicates if a PIN is required as input (with either a yes or no value).
- If the value is no, the display should indicate PIN is optional.
brandLogoImageto display the brand image for a product line.
productLineDescriptionto display the brand description.
defaultProductImagesto display visual images of the back of card to identify the card number and pin.
- Use Reload Characteristics
isReloadable, which indicates if a brand supports reload.
- If the brand supports reload, then use
- If the brand supports reload, then use
- The user selects one of the brands and provides the required card information, such as its number and PIN.
- The application calls the Verify Account API from the Account Processing services passing the product line
entityId(from the cached offline process) to
productLineId, card number in the
accountNumberfield, and the PIN in
pin. It also sets the
accountTypevalue to the type of the card – either CREDIT_CARD, GIFT_CARD, LOYALTY_CARD, or PHONE_CARD.
- Once the application stores the account of the card, the user can use the application to reload the card.
- The application calls Reload Value API from Account Processing services using the following:
entityIdfrom the account.
- The amount to redeem (which goes to
- The unique 12-digit retrieval reference number (which goes to
- The unique GUID (which goes to
- Currency from the account (which goes to
- The application checks the Reload Account response to know how about was approved (
approvedAmount) and the resulting balance (
- If the Reload Account does not return a response:
- Call the Reload Account with the same parameters from Step 5 above at least three times over period of time.
previousAttemptsto 1 and for each subsequent call of Reload Account increment by 1, so the next value is 2.
- If Reload Account is not responding contact Blackhawk Customer Service.
- If the Reload Account returns a timeout:
reverseTransactionfrom the Acccount Processing service and map the
requestIdfrom Step 3 to
Note: the reverseTransaction operation is timebound and usually can be called after a certain timeframe. The reverseTransaction API should not be confused with voidAccount. reverseTransaction is to be used only for system exceptions.
The following diagram shows the flow of a request initiated by a customer to reload the value of a card.
Updated almost 3 years ago