Ruby lib for creating payments with AlphaCard DirectPost API
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, account)
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
account = 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, account)
rescue AlphaCard::AlphaCardError => e
puts e.
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:
- Fork the project
- Create your feature branch (
git checkout -b my-new-feature
) - Make your changes
- Add tests
- Run
rake
to make sure all tests pass - Commit your changes (
git commit -am 'Add new feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new pull request
Thanks.
Copyright
Copyright (c) 2014 Nikita Bulaj ([email protected]).