Awesome Open Source
Awesome Open Source

Ruby lib for creating payments with Alpha Card Services

Gem Version Build Status Code Climate Coverage Status Inline docs License

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

Table of Contents

Installation

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;

Configuration

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 Objects & Transactions

Alpha Card operates with next objects:

Let us consider each of them.

Order

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, ...)

Billing

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, ...)

Shipping

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

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 ...>

Refund

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

Void

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

Capture

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

Update

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

Authorization

Has the same attributes and methods as Sale transaction.

Credit

Has the same attributes and methods as Sale transaction.

Validate

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

Example of usage

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: '[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 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

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.

Testing

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' }

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. 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.

License

Alpha Card gem is released under the MIT License.

Copyright (c) 2014-2017 Nikita Bulai ([email protected]).


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Ruby (312,071
Payment Gateway (777
Sales (187
Related Projects