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
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 92

def initialize(options = {})
  requires!(options, :login)
  super
  initialize_marketplace(options[:marketplace] || load_marketplace)
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.



126
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 126

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[:appears_on_statement_as] = options[:appears_on_statement_as] if options[:appears_on_statement_as]

  (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



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

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

  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
181
 
# 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[:appears_on_statement_as] = options[:appears_on_statement_as] if options[:appears_on_statement_as]

  (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(amount, debit_uri = "deprecated", 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.



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 242

def refund(amount, debit_uri = "deprecated", options = {})
  if(debit_uri == "deprecated" || debit_uri.kind_of?(Hash))
    deprecated "Calling the refund method without an amount parameter is deprecated and will be removed in a future version."
    return refund(options[:amount], amount, options)
  end

  requires!(debit_uri)
  post = {}
  post[:debit_uri] = debit_uri
  post[:amount] = amount
  post[:description] = options[:description]
  post[:appears_on_statement_as] = options[:appears_on_statement_as] if options[:appears_on_statement_as]
  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 –



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 264

def store(credit_card, options = {})
  requires!(options, :email)
  post = {}
   = (post, options)
  if credit_card.respond_to? :number
    card_uri = add_credit_card(post, credit_card, options)
  else
    card_uri = (, credit_card)
  end

  is_test = false
  if @marketplace_uri
    is_test = (@marketplace_uri.index("TEST") ? true : false)
  end

  Response.new(true, "Card stored", {}, :test => is_test, :authorization => [card_uri, ].compact.join(';'))
rescue Error => ex
  failed_response(ex.response)
end

#void(authorization, options = {}) ⇒ Object

Void a previous authorization (Hold)

Parameters

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



216
217
218
219
220
221
222
223
224
 
# File 'lib/active_merchant/billing/gateways/balanced.rb', line 216

def void(authorization, options = {})
  post = {}
  post[:is_void] = true
  post[:appears_on_statement_as] = options[:appears_on_statement_as] if options[:appears_on_statement_as]

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