Class: ActiveMerchant::Billing::BalancedGateway

Inherits:
Gateway
  • Object
show all
Defined in:
lib/active_merchant/billing/gateways/balanced.rb

Overview

For more information on Balanced visit www.balancedpayments.com or visit #balanced on irc.freenode.net

Instantiate a instance of BalancedGateway by passing through your Balanced API key secret.

To obtain an API key of your own

  1. Visit www.balancedpayments.com

  2. Click “Get started”

  3. The next screen will give you a test API key of your own

  4. When you’re ready to generate a production API key click the “Go live” button on the Balanced dashboard and fill in your marketplace details.

Overview

Balanced provides a RESTful API, all entities within Balanced are represented by their respective URIs, these are returned in the ‘authorization` parameter of the Active Merchant Response object.

All Response objects will contain a hash property called ‘params` which holds the raw JSON dictionary returned by Balanced. You can find properties about the operation performed and the object that represents it within this hash.

All operations within Balanced are tied to an account, as such, when you perform an ‘authorization` or a `capture` with a new credit card you must ensure you also pass the `:email` property within the `options` parameter.

For more details about Balanced’s API visit: www.balancedpayments.com/docs

Terminology & Transaction Flow

  • An ‘authorization` operation will return a Hold URI. An `authorization` within Balanced is valid until the `expires_at` property. You can see the exact date of the expiry on the Response object by inspecting the property `response.params`. The resulting Hold may be `capture`d or `void`ed at any time before the `expires_at` date for any amount up to the full amount of the original `authorization`.

  • A ‘capture` operation will return a Debit URI. You must pass the URI of the previously performed `authorization`

  • A ‘purchase` will create a Hold and Debit in a single operation and return the URI of the resulting Debit.

  • A ‘void` operation must be performed on an existing `authorization` and will result in releasing the funds reserved by the `authorization`.

  • The ‘refund` operation must be performed on a previously captured Debit URI. You may refund any fraction of the original amount of the debit up to the original total.

Defined Under Namespace

Classes: CardDeclined, Error

Constant Summary collapse

VERSION = 
'1.0.0'
TEST_URL = 
LIVE_URL = 'https://api.balancedpayments.com'

Constants inherited from Gateway

Gateway::CREDIT_DEPRECATION_MESSAGE, Gateway::CURRENCIES_WITHOUT_FRACTIONS, Gateway::DEBIT_CARDS

Instance Attribute Summary

Attributes inherited from Gateway

#options

Instance Method Summary collapse

Methods inherited from Gateway

#card_brand, card_brand, inherited, supports?, #test?

Methods included from CreditCardFormatting

#format

Constructor Details

#initialize(options = {}) ⇒ BalancedGateway

Creates a new BalancedGateway

The gateway requires that a valid api_key be passed in the options hash.

Options

  • :login – The Balanced API Secret (REQUIRED)



92
93
94
95
96
97
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 92

def initialize(options = {})
  requires!(options, :login)
  @options = options
  initialize_marketplace(options[:marketplace] || load_marketplace)
  super
end

Instance Method Details

#authorize(money, credit_card, options = {}) ⇒ Object

Performs an authorization (Hold in Balanced nonclementure), which reserves the funds on the customer’s credit card, but does not charge the card. An authorization is valid until the ‘expires_at` field in the params Hash passes. See `response.params`. The exact amount of time until an authorization expires depends on the card issuer.

If you pass a previously tokenized ‘credit_card` URI the only other parameter required is `money`. If you pass `credit_card` as a hash of credit card information you must also pass `options` with a `:email` entry.

Parameters

  • money – The amount to be authorized as an Integer value in cents.

  • credit_card – A hash of credit card details for this transaction or the URI of a card previously stored in Balanced.

  • options – A hash of optional parameters.

Options

If you are passing a new credit card you must pass one of these two parameters

  • email – the email address of user associated with this purchase.

  • account_uri – ‘account_uri` is the URI of an existing Balanced account.



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 127

def authorize(money, credit_card, options = {})
  if credit_card.respond_to?(:number)
    requires!(options, :email) unless options[:account_uri]
  end

  post = {}
  post[:amount] = money
  post[:description] = options[:description]

  (post, options)
  add_credit_card(post, credit_card, options)
  add_address(credit_card, options)

  create_transaction(:post, @holds_uri, post)
rescue Error => ex
  failed_response(ex.response)
end

#capture(money, authorization, options = {}) ⇒ Object

Captures the funds from an authorized transaction (Hold).

Parameters

  • money – The amount to be captured as an Integer value in cents. If omitted the full amount of the original authorization transaction will be captured.

  • authorization – The uri of an authorization returned from an authorize request.

Options

  • description – A string that will be displayed on the Balanced dashboard



196
197
198
199
200
201
202
203
204
205
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 196

def capture(money, authorization, options = {})
  post = {}
  post[:hold_uri] = authorization
  post[:amount] = money if money
  post[:description] = options[:description] if options[:description]

  create_transaction(:post, @debits_uri, post)
rescue Error => ex
  failed_response(ex.response)
end

#purchase(money, credit_card, options = {}) ⇒ Object

Perform a purchase, which is an authorization and capture in a single operation.

Parameters

  • money – The amount to be purchased as an Integer value in cents.

  • credit_card – A hash of credit card details for this transaction or the URI of a card previously stored in Balanced.

  • options – A hash of optional parameters.

Options

If you are passing a new credit card you must pass one of these two parameters

  • email – the email address of user associated with this purchase.

  • account_uri – ‘account_uri` is the URI of an existing Balanced account.



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 164

def purchase(money, credit_card, options = {})
  if credit_card.respond_to?('number')
    requires!(options, :email) unless options[:account_uri]
  end

  post = {}
  post[:amount] = money
  post[:description] = options[:description]

  (post, options)
  add_credit_card(post, credit_card, options)
  add_address(credit_card, options)

  create_transaction(:post, @debits_uri, post)
rescue Error => ex
  failed_response(ex.response)
end

#refund(debit_uri, options = {}) ⇒ Object

Refund a transaction.

Returns the money debited from a card to the card from the marketplace’s escrow balance.

Parameters

  • debit_uri – The uri of the original transaction against which the refund is being issued.

  • options – A hash of parameters.

Options

  • <tt>‘:amount`<tt> – specify an amount if you want to perform a partial refund. This value will default to the total amount of the debit that has not been refunded so far.



238
239
240
241
242
243
244
245
246
247
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 238

def refund(debit_uri, options = {})
  requires!(debit_uri)
  post = {}
  post[:debit_uri] = debit_uri
  post[:amount] = options[:amount] if options[:amount]
  post[:description] = options[:description]
  create_transaction(:post, @refunds_uri, post)
rescue Error => ex
  failed_response(ex.response)
end

#store(credit_card, options = {}) ⇒ Object

Stores a card and email address

Parameters

  • credit_card –



254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 254

def store(credit_card, options = {})
  requires!(options, :email)
  post = {}
   = (post, options)
  if credit_card.respond_to? :number
    add_credit_card(post, credit_card, options)
  else
    (, credit_card)
    credit_card
  end
rescue Error => ex
  failed_response(ex.response)
end

#void(authorization) ⇒ Object

Void a previous authorization (Hold)

Parameters

  • authorization – The uri of the authorization returned from an ‘authorize` request.



213
214
215
216
217
218
219
220
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 213

def void(authorization)
  post = {}
  post[:is_void] = true

  create_transaction(:put, authorization, post)
rescue Error => ex
  failed_response(ex.response)
end