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
- 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:
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
orInteger
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
orInteger
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
orInteger
- 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
orInteger
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:
- 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.
Alpha Card gem is released under the MIT License.
Copyright (c) 2014-2017 Nikita Bulai (bulajnikita@gmail.com).