Workarea Gift Cards

A Workarea Commerce plugin that enables customers to purchase physical and digital gift cards and redeem them for other merchandise within the catalog.

Overview

Create gift card products, both digital and physical
Allow gift card customization with recipient name, email, and personal message
Automatically deliver digital gift card information to recipient upon purchase
Use any number of gift cards as payment in checkout (with configurable limit)
Check the balance of a digital gift card
Manage digital gift cards from the admin
View gift card redemptions from the admin
Admin API management of gift cards
Storefront API support for using gift cards in checkout
Gateway support for easily using a third-party gift card service (see below)

Getting Started

Add the gem to your application's Gemfile:

# ...
gem 'workarea-gift_cards'
# ...

Update your application's bundle.

cd path/to/application
bundle

Using a custom gift card gateway

The workarea-gift_cards plugin comes fully functional with management of gift cards, tracking of redemptions and balances within the Workarea admin. However, using a third-party gift card service is not uncommon. Taking that into consideration, the plugin allows for the use of a custom gateway for looking up balances, validating gift card info, and processing gift card payments. This allows a retailer to utilize the plugin for the gift card product behaviors, but continue using a third-party service for generating gift card codes and tracking the use of purchased gift cards.

Setup a custom gateway

The plugin adds a configuration value of Workarea.config.gateways.gift_card. By default, this is set to Workarea::GiftCards::Gateway, which utilizes the existing Workarea::Payment::GiftCard collection. This configuration value can be changed to a custom class of your choice that responds to the same methods.

class ThirdPartyGiftCardGateway
  # setup any relevant configuration required for connecting to a
  # third-party service
  #
  def initialize; end

  # Optional. Define this method to tell the system you are using the
  # Workarea::Payment::GiftCard collection. This will turn on a number of
  # behaviors only relevant when using the collection. If the gateway does not
  # respond to this method, it will assume false.
  #
  def uses_system_cards?
    true
  end

  # These are the transactional methods expected from the gateway. They each
  # take two arguments:
  #   amount - is the value (in cents) that transaction is looking to apply.
  #   tender - will be a Workarea::Payment::Tender::GiftCard which you can use
  #            to find the relevant card number or other info stored on the
  #            tender associated to this transaction.
  #
  # The system expects these method to return an object that responds to
  # two methods:
  #   success? - a boolean that determines if the transaction was successful
  #   message - information around the transaction result
  #
  def authorize(amount, tender); end
  def cancel(amount, tender); end
  def capture(amount, tender); end
  def purchase(amount, tender); end
  def refund(amount, tender); end

  # This passes in one or more tokens/numbers as strings and returns a Money
  # object that represents the total balance of all valid card numbers.
  #
  def balance(token); end

  # This method is used when a customer looks up their balance from the
  # storefront. This will often require them to provide some unique info
  # to protect against malicious attempts at discovering gift card numbers.
  # The request parameters are passed directly into the method to allow
  # flexibility in the information you request from the user to show them
  # the balance. By default, the system expects this method to return an
  # object that responds to #balance, #token, and #to. This is entirely
  # dependent on the resulting view rendered, which can be customized.
  #
  def lookup(params); end
end

After building a custom class, set the config value to the custom class.

Workarea.configure do |config|
  config.gateways.gift_card = 'ThirdPartyGiftCardGateway'
end

Note that it is set to a string of the class constant, and not an instance of the class. The system constantizes and initializes a new instance whenever it uses the gateway to ensure autoloading works correctly and so a gateway that cares about the current state of the application is applied correctly. This is most relevant in multi-site environments where each site might want to use their own gift card gateway.

Testing Your Custom Gateway

Workarea comes with unit tests for the main Gateway class, and you can decorate this test to provide your own setup code. A minimal implementation would look as follows:

module Workarea
  module GiftCards
    decorate GatewayTest do
      # Provide your own Gateway instance here to use it in each test.
      def gateway
        CustomGiftCardGateway.new
      end

      # Provide a custom object representing a Gift Card on your
      # 3rd-party service.
      def gift_card
        CustomGiftCard.new(balance: 10.to_m)
      end
    end
  end
end

Workarea Commerce Documentation

See https://developer.workarea.com for Workarea Commerce documentation

License

Workarea Gift Cards is released under the Business Software License