Class: CloverSandboxSimulator::Services::Clover::GiftCardService

Inherits:
BaseService
  • Object
show all
Defined in:
lib/clover_sandbox_simulator/services/clover/gift_card_service.rb

Overview

Manages Clover gift card operations Handles balance management, purchase, reload, and redemption

Constant Summary collapse

DENOMINATIONS =

Standard gift card denominations in cents

[2500, 5000, 10000, 2000, 7500].freeze
CARD_NUMBER_LENGTH =

Gift card number format: 16 digits

16

Instance Attribute Summary

Attributes inherited from BaseService

#config, #logger

Instance Method Summary collapse

Methods inherited from BaseService

#initialize

Constructor Details

This class inherits a constructor from CloverSandboxSimulator::Services::BaseService

Instance Method Details

#check_balance(gift_card_id) ⇒ Integer

Check balance for a gift card

Parameters:

  • gift_card_id (String) —

    The gift card ID

Returns:

  • (Integer) —

    Balance in cents, or 0 if not found



65
66
67
68
69
70
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 65

def check_balance(gift_card_id)
  gift_card = get_gift_card(gift_card_id)
  balance = gift_card&.dig("balance") || 0
  logger.info "Gift card #{gift_card_id} balance: $#{balance / 100.0}"
  balance
end

#create_gift_card(amount:, card_number: nil) ⇒ Hash?

Create/activate a new gift card

Parameters:

  • amount (Integer) —

    Initial balance in cents

  • card_number (String, nil) (defaults to: nil) —

    Optional 16-digit card number (auto-generated if nil)

Returns:

  • (Hash, nil) —

    Created gift card or nil on failure



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 31

def create_gift_card(amount:, card_number: nil)
  card_number ||= generate_card_number
  logger.info "Creating gift card #{mask_card_number(card_number)} with balance $#{amount / 100.0}"

  payload = {
    "cardNumber" => card_number,
    "amount" => amount,
    "status" => "ACTIVE"
  }

  response = request(:post, endpoint("gift_cards"), payload: payload)

  if response && response["id"]
    logger.info "Gift card created: #{response['id']}"
  else
    logger.error "Failed to create gift card: #{response.inspect}"
  end

  response
end

#fetch_gift_cards ⇒ Array<Hash>

Fetch all gift cards for the merchant

Returns:

  • (Array<Hash>) —

    List of gift cards



18
19
20
21
22
23
24
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 18

def fetch_gift_cards
  logger.info "Fetching gift cards..."
  response = request(:get, endpoint("gift_cards"))
  elements = response&.dig("elements") || []
  logger.info "Found #{elements.size} gift cards"
  elements
end

#find_card_with_balance(minimum_balance: 0) ⇒ Hash?

Find a gift card with sufficient balance

Parameters:

  • minimum_balance (Integer) (defaults to: 0) —

    Minimum balance required in cents

Returns:

  • (Hash, nil) —

    Gift card with sufficient balance or nil



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 158

def find_card_with_balance(minimum_balance: 0)
  gift_cards = fetch_gift_cards
  eligible = gift_cards.select do |gc|
    gc["status"] == "ACTIVE" && (gc["balance"] || 0) >= minimum_balance
  end

  if eligible.any?
    selected = eligible.sample
    logger.info "Found eligible gift card: #{selected['id']} with balance $#{(selected['balance'] || 0) / 100.0}"
    selected
  else
    logger.info "No gift cards found with minimum balance $#{minimum_balance / 100.0}"
    nil
  end
end

#generate_card_number ⇒ String

Generate a valid 16-digit gift card number

Returns:

  • (String) —

    16-digit card number



193
194
195
196
197
198
199
200
201
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 193

def generate_card_number
  # Format: 4 groups of 4 digits, starting with 6xxx (common gift card prefix)
  prefix = "6#{rand(0..9)}#{rand(0..9)}#{rand(0..9)}"
  middle1 = format("%04d", rand(0..9999))
  middle2 = format("%04d", rand(0..9999))
  suffix = format("%04d", rand(0..9999))

  "#{prefix}#{middle1}#{middle2}#{suffix}"
end

#get_gift_card(gift_card_id) ⇒ Hash?

Get a specific gift card by ID

Parameters:

  • gift_card_id (String) —

    The gift card ID

Returns:

  • (Hash, nil) —

    Gift card details or nil



56
57
58
59
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 56

def get_gift_card(gift_card_id)
  logger.info "Fetching gift card: #{gift_card_id}"
  request(:get, endpoint("gift_cards/#{gift_card_id}"))
end

#random_denomination ⇒ Integer

Get a random denomination amount

Returns:

  • (Integer) —

    Amount in cents



206
207
208
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 206

def random_denomination
  DENOMINATIONS.sample
end

#random_gift_card ⇒ Hash?

Select a random gift card for payment May return a card with insufficient balance for partial payment scenarios

Returns:

  • (Hash, nil) —

    Random active gift card or nil



178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 178

def random_gift_card
  gift_cards = fetch_gift_cards
  active_cards = gift_cards.select { |gc| gc["status"] == "ACTIVE" }

  if active_cards.any?
    active_cards.sample
  else
    logger.info "No active gift cards available"
    nil
  end
end

#redeem_gift_card(gift_card_id, amount:) ⇒ Hash

Redeem/use balance from a gift card

Parameters:

  • gift_card_id (String) —

    The gift card ID

  • amount (Integer) —

    Amount to redeem in cents

Returns:

  • (Hash) —

    Result with :success, :amount_redeemed, :remaining_balance, :shortfall



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 101

def redeem_gift_card(gift_card_id, amount:)
  logger.info "Redeeming $#{amount / 100.0} from gift card #{gift_card_id}"

  current_balance = check_balance(gift_card_id)

  if current_balance <= 0
    logger.warn "Gift card has no balance"
    return {
      success: false,
      amount_redeemed: 0,
      remaining_balance: 0,
      shortfall: amount,
      message: "Gift card has no balance"
    }
  end

  # Calculate redemption amount (may be partial if insufficient balance)
  redeem_amount = [amount, current_balance].min
  shortfall = amount - redeem_amount

  payload = {
    "amount" => redeem_amount
  }

  response = request(:post, endpoint("gift_cards/#{gift_card_id}/redeem"), payload: payload)

  if response
    remaining = response["balance"] || 0
    logger.info "Redeemed $#{redeem_amount / 100.0}. Remaining balance: $#{remaining / 100.0}"

    if shortfall > 0
      logger.info "Shortfall of $#{shortfall / 100.0} - will need additional payment"
    end

    {
      success: true,
      amount_redeemed: redeem_amount,
      remaining_balance: remaining,
      shortfall: shortfall,
      gift_card: response
    }
  else
    logger.error "Failed to redeem gift card"
    {
      success: false,
      amount_redeemed: 0,
      remaining_balance: current_balance,
      shortfall: amount,
      message: "Failed to redeem gift card"
    }
  end
end

#reload_gift_card(gift_card_id, amount:) ⇒ Hash?

Reload/add balance to a gift card

Parameters:

  • gift_card_id (String) —

    The gift card ID

  • amount (Integer) —

    Amount to add in cents

Returns:

  • (Hash, nil) —

    Updated gift card or nil on failure



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/clover_sandbox_simulator/services/clover/gift_card_service.rb', line 77

def reload_gift_card(gift_card_id, amount:)
  logger.info "Reloading gift card #{gift_card_id} with $#{amount / 100.0}"

  payload = {
    "amount" => amount
  }

  response = request(:post, endpoint("gift_cards/#{gift_card_id}/reload"), payload: payload)

  if response
    new_balance = response["balance"] || 0
    logger.info "Gift card reloaded. New balance: $#{new_balance / 100.0}"
  else
    logger.error "Failed to reload gift card"
  end

  response
end