Ruby lib for creating payments with Alpha Card Services

Gem Version Dependency Status Code Climate Coverage Status Build Status Inline docs

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

Alpha Card Services:

Payment Gateway Integration Portal:


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;

Alpha Card Objects

Alpha Card operates with next 5 objects:

  • Account (represent your Alpha Card credentials)
  • Order
    • Billing
    • Shipping
  • Sale

Let us consider each of them.


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

Required fields:

  • username : String
  • password : String

Constructor:, password)


Order represents itself.

Unnecessary fields:

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

Constructor:{field_name: value, ...})


Specify Billing information for Order.

Unnecessary fields:

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

Constructor:{field_name: value, ...})


Specify Shipping information for Order.

Unnecessary fields:

  • firstname : String
  • lastname : String
  • company : String
  • address_1 : String
  • address_2 : String
  • city : String
  • state : String
  • zip_code : String
  • country : String
  • email : String

Constructor:{field_name: value, ...})


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:{field_name: value, ...})

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

sale ={})
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
   ='demo', 'password')

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

  order ={ orderid: 1, orderdescription: 'Test order' })

  # Format of amount: "XX.XX" ("%.2f" % Float)
  sale ={ ccexp: '0117', ccnumber: '4111111111111111', amount: "1.50", cvv: '123' })
  sale.create(order, )
rescue AlphaCard::AlphaCardError => e
  puts e.message

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


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. Implement your feature or bug fix.
  4. Add documentation for your feature or bug fix.
  5. Run rake doc:yard. If your changes are not 100% documented, go back to step 4.
  6. Add tests for your feature or bug fix.
  7. Run rake to make sure all tests pass.
  8. Commit your changes (git commit -am 'Add new feature').
  9. Push to the branch (git push origin my-new-feature).
  10. Create new pull request.


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