A Ruby / JRuby / Rails gem for integrating with Alpha Card Services
MIT 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
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:
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:
Let us consider each of them.
Order represents itself.
Optional attributes:
String
String
String
String
String
(format: xxx.xxx.xxx.xxx
)AlphaCard::Billing
AlphaCard::Shipping
Constructor:
AlphaCard::Order.new(property: value, ...)
Specify Billing information for Order.
Optional attributes:
String
String
String
String
String
String
String
String
String
String
(format: CC
)String
String
(format: CC
. Country codes are as shown in ISO 3166)String
Constructor:
AlphaCard::Billing.new(property: value, ...)
Contains Shipping information for the Order.
Optional attributes:
String
String
String
String
String
String
String
(format: CC
)String
String
(format: CC
. Country codes are as shown in ISO 3166)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:
String
(format: MMYY
)String
String
(format: x.xx
)Optional attributes:
String
String
(default: 'creditcard'
, values: 'creditcard'
or 'check'
)String
(values 'true'
or 'false'
)String
String
String
String
(values: 'business'
or 'personal'
)String
(values: 'checking'
or 'savings'
)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:
String
or Integer
Optional attributes:
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:
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:
String
or Integer
String
(format: xx.xx
)Optional attributes:
String
String
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:
String
or Integer
Optional attributes:
String
String
String
String
String
(values: 'ups'
, 'fedex'
, 'dhl'
or 'usps'
)String
(format: YYYYMMDD
)String
String
String
(values: 'true'
or 'false'
)String
String
String
(format: x.xx
)String
(format: x.xx
)String
(format: x.xx
)String
(format: x.xx
)String
(format: x.xx
)String
String
String
String
String
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: '[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:
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:
git checkout -b my-new-feature
).rake
to make sure all tests pass.git commit -am 'Add new feature'
).git push origin my-new-feature
).Thanks.
Alpha Card gem is released under the MIT License.
Copyright (c) 2014-2017 Nikita Bulai ([email protected]).