Ruby lib for creating payments with Alpha Card Services

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', '~> 0.3'

And run:

bundle install

Otherwise simply install the gem:

gem install alpha_card

Dependencies required:

ruby >= 2.0.0;

Alpha Card Objects & Transactions

Alpha Card operates with next objects:

Account
Order
- Billing
- Shipping
Sale
Refund
Void
Capture
Update

Let us consider each of them.

Account

Account represents credentials data to access Alpha Card Gateway. All transactions (sale, refund, etc) will be created for the specified account.

Required fields:

username : String
password : String

Constructor:

AlphaCard::Account.new(username, password)

Order

Order represents itself.

Optional fields:

id : String
description : String
po_number : String
tax : String
ip_address : String (format: xxx.xxx.xxx.xxx)
billing : AlphaCard::Billing
shipping : AlphaCard::Shipping

Constructor:

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

Billing

Specify Billing information for Order.

Optional fields:

first_name : String
last_name : String
email : String
fax : String
phone : String
company : String
address_1 : String
address_2 : String
city : String
state : String (format: CC)
zip : String
country : String (format: CC. Country codes are as shown in ISO 3166)
website : String

Constructor:

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

Shipping

Specify Shipping information for Order.

Optional fields:

first_name : String
last_name : String
company : String
address_1 : String
address_2 : String
city : String
state : String (format: CC)
zip_code : String
country : String (format: CC. Country codes are as shown in ISO 3166)
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:

card_expiration_date : String (format: MMYY)
card_number : String
amount : String (format: x.xx)

Optional fields:

cvv : String
payment : String (default: 'creditcard', values: 'creditcard' or 'check')
customer_receipt : String (values 'true' or 'false')

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(amount: 10)
success, alpha_card_response = sale.create(order, account)

# => [true, #<AlphaCard::AlphaCardResponse:0x1a0fda ...>]

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

Refund

Represents refund transaction.

Required fields:

transaction_id : String

Optional fields:

amount : String (format: x.xx)

Constructor:

AlphaCard::Refund.new(field_name: value, ...)

To create the refund transaction you must call create(alpha_card_account) method:

# ...
refund = AlphaCard::Refund.new(transaction_id: '12312312', amount: 10)
refund.create(account)

Void

Represents void transaction.

Required fields:

transaction_id : String

Constructor:

AlphaCard::Void.new(field_name: value, ...)

To create the void transaction you must call create(alpha_card_account) method:

# ...
void = AlphaCard::Void.new(transaction_id: '12312312')
void.create(account)

Capture

Represents capture transaction.

Required fields:

transaction_id : String
amount : String (format: x.xx)

Constructor:

AlphaCard::Capture.new(field_name: value, ...)

To create the capture transaction you must call create(alpha_card_account) method:

# ...
capture = AlphaCard::Capture.new(transaction_id: '12312312', amount: '5.05')
capture.create(account)

Update

Represents update transaction.

Required fields:

transaction_id : String

Optional fields:

shipping: String
shipping_postal: String
ship_from_postal: String
shipping_country: String
shipping_carrier: String (values: 'ups', 'fedex', 'dhl' or 'usps')
shipping_date: String (format: YYYYMMDD)
order_description: String
order_date: String
customer_receipt: String (values: 'true' or 'false')
po_number: String
summary_commodity_code: String
duty_amount: String (format: x.xx)
discount_amount: String (format: x.xx)
tax: String (format: x.xx)
national_tax_amount: String (format: x.xx)
alternate_tax_amount: String (format: x.xx)
alternate_tax_id: String
vat_tax_amount: String
vat_tax_rate: String
vat_invoice_reference_number: String
customer_vat_registration: String
merchant_vat_registration: String

Constructor:

AlphaCard::Update.new(field_name: value, ...)

To create update transaction you must call create(alpha_card_account) method:

# ...
update = AlphaCard::Update.new(tax: '10.02', shipping_carrier: 'ups', transaction_id: '66928')
update.create(account)

Example of usage

Create AlphaCard sale (pay for the order):

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(id: 1, description: 'Test order', billing: billing, shipping: shipping)

  # Format of amount: "XX.XX" ("%.2f" % Float)
  sale = AlphaCard::Sale.new(card_epiration_date: '0117', card_number: '4111111111111111', amount: '1.50', cvv: '123')
  success, response = sale.create(order, account)
  #=> [true, #<AlphaCard::AlphaCardResponse:0x1a0fda ...>]
  puts "Order payed successfully: transaction ID = #{response.transaction_id} if success
rescue AlphaCard::AlphaCardError => e
  puts "Error message: #{e.response.message}"
  puts "CVV response: #{e.response.cvv_response}"
  puts "AVS response: #{e.response.avs_response}"
  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 the 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

AlphaCard Response

AlphaCardResponse contains all the necessary information about Alpha Card Gateway response. You can use the following API:

.text — textual response of the Alpha Card Gateway;
.message — response message be response code;
.transaction_id — payment gateway transaction ID;
.order_id — original order ID passed in the transaction request;
.code — numeric mapping of processor responses;
.auth_code — transaction authorization code;
.success?, .error?, .declined? — state of the request;
.cvv_response — CVV response message;
.avs_response — AVS response message.

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).
Implement your feature or bug fix.
Add documentation for your feature or bug fix.
Run rake doc:yard. If your changes are not 100% documented, go back to step 4.
Add tests for your feature or bug fix.
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.

License

Alpha Card gem is released under the MIT License.