ArrowPayments gateway for Ruby
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE
README.md
REFERENCE.md
Rakefile
arrow_payments.gemspec

README.md

ArrowPayments

Ruby wrapper for Arrow Payments gateway

Status

  • Build Status
  • Code Climate
  • Gem Version

Installation

Add dependency to your Gemfile:

gem 'arrow_payments'

Or install manually:

gem install arrow_payments

Configuration

To configure gateway globally, add an initializer with the following:

ArrowPayments::Configuration.api_key = 'foo'
ArrowPayments::Configuration.mode = 'production'
ArrowPayments::Configuration.merchant_id = '1231231'

Another way is to configure on the instance level:

client = ArrowPayments::Client.new(
  :api_key     => 'foo', 
  :mode        => 'production',
  :merchant_id => '123451',
  :debug       => true
)

A set of helper methods:

client.production? # => true
client.sandbox?    # => false
client.debug?      # => true

Usage

Check the API reference section for objects details.

Initialize a new client:

client = ArrowPayments::Client.new(
  :api_key     => 'foo',
  :mode        => 'sandbox',
  :merchant_id => '12345'
)

Customers

# Get all customers. 
# Does not include recurring billings and payment methods.
client.customers # => [Customer, ...]

# Get customer details. 
# Returns nil if not found
client.customer('12345')

# Create a new customer. 
# Raises ArrowPayments::Error if unable to create.
customer = client.create_customer(
  :name => 'John Doe',
  :contact => 'John Doe',
  :code => 'JOHN',
  :email => 'john@doe.com',
  :phone => '(123) 123-12-12'
)

# Update an existing customer
customer = client.customer('12345')
customer.name = 'Foo Bar'
client.update_customer(customer) # => true

# Delete an existing customer
client.delete_customer('12345') # => true

Payment Methods

Example: Add a new payment method to an existing customer

client_id = '12345'

# Initialize a new billing address instance
address = ArrowPayments::Address.new(
  :address  => 'Some Street',
  :address2 => 'Apt 1',
  :city     => 'Chicago',
  :state    => 'IL',
  :zip      => '60657',
  :phone    => '123123123'
)

# Initialize a new payment method instance
cc = ArrowPayments::PaymentMethod.new(
  :first_name       => 'John',
  :last_name        => 'Doe',
  :number           => '4111111111111111',
  :security_code    => '123',
  :expiration_month => 12,
  :expiration_year  => 14
)

# Step 1: Provide payment method customer and billing address
url = client.start_payment_method(customer_id, address)

# Step 2: Add credit card information
token = client.setup_payment_method(url, cc)

# Step 3: Finalize payment method creation
cc = client.complete_payment_methodtoken)

# Delete an existing payment method
client.delete_payment_method('123456') # => true

You can also create a payment method using a wrapper method:

address = ArrowPayments::Address.new( ... data ... )
cc      = ArrowPayments::PaymentMethod.new( ... data ... )

# Returns a new PaymentMethod instance or raises errors
client.create_payment_method(customer_id, address, cc)

Transactions

# Get list of transactions by customer. 
# Only unsettled transactions will be returns as ArrowPayments does not support
# any other filters for now
client.transactions('12345')

# Get a single transaction details.
# Raises ArrowPayments::NotFound if not found
client.transaction('45678')

# Capture a transaction for a specified amount. 
# Returns success result or raises ArrowPayments::Error exception
client.capture_transaction('45678', 123.00)

# Void an existing unsettled transaction
# Returns a success result or raises ArrowPayments::NotFound if not found
client.void_transaction('45678')

# Create a new transaction for an existing custromer and payment method.
# Returns a new Transaction instance if request was successfull, otherwise
# raises ArrowPayments::Error exception with error message.
transaction = client.create_transaction(
  :customer_id        => 'Customer ID', 
  :payment_method_id  => 'Payment Method ID',
  :transaction_type   => 'sale',
  :total_amount       => 250,
  :tax_amount         => 0,
  :shipping_amount    => 0
)

Reference

List of all gateway errors:

  • ArrowPayments::Error - Raised on invalid data. Generic error.
  • ArrowPayments::NotFound - Raised on invalid API token or non-existing object
  • ArrowPayments::NotImplemented - Raised when API endpoint is not implemented

List of all gateway objects:

  • Customer - Gateway customer object
  • PaymentMethod - Gateway payment method (credit card) object
  • Transaction - Contains all information about transaction
  • Address - User for shipping and billing addresses
  • LineItem - Contains information about transaction item

Check REFERENCE.md file for details

Testing

To run a test suite:

rake test

License

See LICENSE file for details