Ruby lib for creating payments with AlphaCard DirectPost API

Gem Version Dependency Status Code Climate Coverage Status Build Status

This gem can help your Ruby or Ruby on Rails application to integrate with Alpha Card Service, Inc.

Alpha Card Services: http://www.alphacardservices.com/

Payment Gateway Integration Portal: https://secure.alphacardgateway.com/merchants/resources/integration/integration_portal.php

Installation

If using bundler, first add 'alpha_card' to your Gemfile:

gem "alpha_card"

And run:

bundle install

Otherwise simply install the gem:

gem install alpha_card

Dependencies required:

  • ruby >= 1.9.3;
  • rack;
  • rest_client;
  • virtus (for nice OOP objects of AlphaCard).

Objects

Alpha Card sales operates with next 5 objects:

  • Account
  • Order
    • Billing
    • Shipping
  • Sale

Account

Account represents credentials data to access Alpha Card Services, Inc. All sales will be created for the specified account.

Required fields:

  • username : String
  • password : String

Constructor:

AlphaCard::Account.new(username, password)

Order

Order represents itself.

Unnecessary fields:

  • orderid : String
  • orderdescription : String
  • ponumber : String
  • tax : String
  • billing : AlphaCard::Billing
  • shipping : AlphaCard::Shipping

Constructor:

AlphaCard::Order.new({field_name: value, ...})

Billing

Specify Billing information for Order.

Unnecessary fields:

  • firstname : String
  • lastname : String
  • email : String
  • phone : String
  • company : String
  • address1 : String
  • address2 : String
  • city : String
  • state : String
  • zip : String
  • country : String
  • website : String

Constructor:

AlphaCard::Billing.new({field_name: value, ...})

Shipping

Specify Shipping information for Order.

Unnecessary fields:

  • address_1 : String
  • address_2 : String
  • city : String
  • state : String
  • zip_code : String
  • email : String

Constructor:

AlphaCard::Shipping.new({field_name: value, ...})

Sale

Sale is the main object of the Alpha Card Services. It processes fees associated with credit cards.

Required fields:

  • ccexp : String
  • ccnumber : String
  • amount : String

Unnecessary fields:

  • cvv : String

Constructor:

AlphaCard::Sale.new({field_name: value, ...})

To create the payment you must call create(alpha_card_order, alpha_card_account) method:

...
sale = AlphaCard::Sale.new({})
sale.create(order, )

This method returns true if sale was created successfully and raise an AlphaCardError exception if some of the fields is invalid.

Example of usage

Create AlphaCard sale:

require 'alpha_card'

def create_payment
   = AlphaCard::Account.new('demo', 'password')

  billing = AlphaCard::Billing.new({email: '[email protected]', phone: '+801311313111'})
  shipping = AlphaCard::Shipping.new({address_1: '33 N str', city: 'New York', state: 'NY', zip_code: '132'})

  order = AlphaCard::Order.new({orderid: 1, orderdescription: 'Test order'})
  order.billing = billing
  order.shipping = shipping

  sale = AlphaCard::Sale.new({ccexp: '0117', ccnumber: '4111111111111111', amount: "%.2f" % 1.5 , cvv: '123'})
  sale.create(order, )
rescue AlphaCard::AlphaCardError => e
  puts e.message
  false
end

Billing and shipping is an optional parameters and can be not specified.

Note: take a look at the amount of the Order. It's format must be 'xx.xx'. All information about variables formats can be found on Alpha Card Payment Gateway Integration Portal -> Direct Post API -> Documentation -> Transaction Variables

Naming convention of attributes (such as "ccexp" or "orderid") was saved for compatibility with AlphaCard API.

To raise some exceptions do the next:

  • to cause a declined message, pass an amount less than 1.00;
  • to trigger a fatal error message, pass an invalid card number;
  • to simulate an AVS match, pass 888 in the address1 field, 77777 for zip;
  • to simulate a CVV match, pass 999 in the cvv field.

Example of exception:

...
2.1.1 :019 >  sale.create(order, account)
AlphaCard::AlphaCardError: Invalid Credit Card Number REFID:127145481

Contributing

You are very welcome to help improve alpha_card if you have suggestions for features that other people can use.

To contribute:

  1. Fork the project
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Make your changes
  4. Add tests
  5. Run rake to make sure all tests pass
  6. Commit your changes (git commit -am 'Add new feature')
  7. Push to the branch (git push origin my-new-feature)
  8. Create new pull request

Thanks.

Copyright (c) 2014 Nikita Bulaj ([email protected]).