Ruby lib for creating payments with Alpha Card Services

This gem can help your Ruby, JRuby 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
• Configuration
• Alpha Card Objects & Transactions
  • Order
    • Billing
    • Shipping
  • Sale
  • Refund
  • Void
  • Capture
  • Update
  • Authorization
  • Credit
  • Validate
• Example of usage
• AlphaCard Response
• Testing
• Contributing
• License

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

gem 'alpha_card', '~> 0.4'

And run:

bundle install

Otherwise simply install the gem:

gem install alpha_card -v '0.4'

Dependencies required:

• ruby >= 2.2.2 or jruby >= 9.0.5.0;

In order to use Alpha Card Gateway API you need to have a Merchant account credentials such as username and password.

If your project will always use only one account for processing payments, then you can configure gem as follows:

AlphaCard::Account.username = 'username'
AlphaCard::Account.password = 'password'

In Rails applications you can create an initializer:

# config/initializers/alpha_card.rb
if Rails.env.test? || Rails.env.ci?
  AlphaCard::Account.use_demo_credentials!
else
  AlphaCard::Account.username = 'username'
  AlphaCard::Account.password = 'password'
end

Another way is to pass the credentials as a last argument when creating some transactions or perform operations (it can be useful when you need to operate with multiple Alpha Card accounts):

void = AlphaCard::Void.new(transaction_id: '312110')
void.process(username: 'demo', password: 'demo')

Alpha Card operates with next objects:

• Order
  • Billing
  • Shipping
• Sale/Authorization/Credit/Validate
• Refund
• Void
• Capture
• Update

Let us consider each of them.

Order represents itself.

Optional attributes:

• 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(property: value, ...)

Specify Billing information for Order.

Optional attributes:

• 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(property: value, ...)

Contains Shipping information for the Order.

Optional attributes:

• 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(property: value, ...)

Sale transaction is the main object of the Alpha Card Services. It is used to processed common payments for orders.

Required attributes:

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

Optional attributes:

• cvv : String
• payment : String (default: 'creditcard', values: 'creditcard' or 'check')
• customer_receipt : String (values 'true' or 'false')
• check_name : String
• check_aba : String
• check_account : String
• account_holder_type : String (values: 'business' or 'personal')
• account_type : String (values: 'checking' or 'savings')
• sec_code : String (values: 'PPD', 'WEB', 'TEL', or 'CCD')

Constructor:

AlphaCard::Sale.new(property: value, ...)

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

# ...
sale = AlphaCard::Sale.new(amount: 10)
response = sale.process(order)

# => #<AlphaCard::Response:0x1a0fda ...>

Represents refund transaction.

Required attributes:

• transaction_id : String or Integer

Optional attributes:

• amount : String (format: x.xx)

Constructor:

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

To create the refund transaction you must call create or process method:

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

Represents void transaction.

Required attributes:

• transaction_id : String or Integer

Constructor:

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

To create the void transaction you must call create or process method:

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

Represents capture transaction.

Required attributes:

• transaction_id : String or Integer
• amount : String (format: xx.xx)

Optional attributes:

• tracking_number : String
• shipping_carrier : String
• order_id : String

Constructor:

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

To create the capture transaction you must call create or process method:

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

Represents update transaction.

Required attributes:

• transaction_id : String or Integer

Optional attributes:

• 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(property: value, ...)

To create update transaction you must call create or process method:

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

Has the same attributes and methods as Sale transaction.

Has the same attributes and methods as Sale transaction.

Has the same attributes and methods as Sale transaction, except amount — there is no need in it.

Create AlphaCard sale (pay for the order):

require 'alpha_card'

def create_payment
  # Setup merchant account credentials
  AlphaCard::Account.username = 'demo'
  AlphaCard::Account.password = 'password'

  billing = AlphaCard::Billing.new(email: 'test@example.com', 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 the amount: "XX.XX"
  sale = AlphaCard::Sale.new(card_expiration_date: '0117', card_number: '4111111111111111', amount: '1.50', cvv: '123')
  response = sale.create(order)
  #=> #<AlphaCard::Response:0x1a0fda ...>

  if response.success?
    puts "Order payed successfully: transaction ID = #{response.transaction_id}"
    true
  else
    puts "Error message: #{e.response.message}"
    puts "CVV response: #{e.response.cvv_response}"
    puts "AVS response: #{e.response.avs_response}"
    false
  end

  rescue AlphaCard::APIConnectionError => e
    puts "Connection problems: #{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 the information about variables formats can be found on Alpha Card Payment Gateway Integration Portal -> Direct Post API -> Documentation -> Transaction Variables

To simulate request that returns an error 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.

AlphaCard::Response 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.

It is recommended to mock Alpha Card gem functionality, but if you want to create a "real" specs, then you can use Alpha Card Services testing account:

AlphaCard::Account.use_demo_credentials!

Or you can pass the next credentials with any request: { username: 'demo', password: 'password' }

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.

Thanks.

Alpha Card gem is released under the MIT License.

Copyright (c) 2014-2017 Nikita Bulai (bulajnikita@gmail.com).