Cayan
A Ruby gem for talking to the Cayan Merchantware API
Installation (not published yet)
Add this line to your application's Gemfile:
gem 'cayan'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cayan
Merchantware Credit Usage
- Initialize a Merchantware Credit Client
- AdjustTip
- AttachSignature
- Authorize
- BoardCard
- Capture
- FindBoardedCard
- UpdateBoardedCard
- ForceCapture
- Refund
- Sale
- SettleBatch
- UnboardCard
- Void
Initialize a Merchantware Credit Client
@client = Cayan::Merchantware::Credit::Client.new({
merchant_name: 'Zero Inc',
merchant_site_id: '00000000',
merchant_key: '00000-00000-00000-00000-00000'
})
AdjustTip
Adds or alters the tip amount to a prior transaction
result = @client.adjust_tip({ token: '1236559', amount: '1.00' })
result[:approval_status] # 'APPROVED'
result[:token] # '1236560'
result[:transaction_date] # '3/14/2016 7:54:23 PM'
AttachSignature
Appends a signature record to an existing transaction
result = @client.attach_signature({
token: '608957',
vector_image_data: '10,10^110,110^0,65535^10,110^110,10^0,65535^~'
})
result[:upload_status] # 'ACCEPTED'
result[:token] # '608957'
result[:transaction_date] # '3/14/2016 7:57:32 PM'
Authorize
Applies an authorization to a credit card which can be captured at a later time
result = @client.authorize({
source: 'Keyed',
card_number: '4012000033330026',
expiration_date: '1218',
card_holder: 'John Doe',
avs_street_address: '1 Federal Street',
avs_zip_code: '02110',
card_verification_value: '123'
},
{
amount: 1.05,
invoice_number: '1556',
register_number: '35',
merchant_transaction_id: '167901',
card_acceptor_terminal_id: '3'
})
result[:approval_status] # 'APPROVED'
result[:token] # '608958'
result[:authorization_code] # 'OK785C'
result[:transaction_date] # '3/14/2016 7:58:33 PM'
result[:amount] # '1.05'
result[:card_number] # '************0026'
result[:cardholder] # 'John Doe'
result[:card_type] # '4'
result[:reader_entry_mode] # '1'
result[:avs_response] # 'Y'
BoardCard
Stores payment information for a credit card into the Merchantware Vault
result = @client.board_card({
source: 'Keyed',
card_number: '4012000033330026',
expiration_date: '1218',
card_holder: 'John Doe',
avs_street_address: '1 Federal Street',
avs_zip_code: '02110'
})
result[:vault_token] # '1000000000002WSZECPL'
Capture
Completes a transaction for a prior authorization
result = @client.capture({
token: '608939',
amount: 1.50,
invoice_number: '1556',
register_number: '35',
merchant_transaction_id: '167902',
card_acceptor_terminal_id: '3'
})
result[:approval_status] # 'APPROVED'
result[:token] # '608961'
result[:authorization_code] # 'OK036C'
result[:transaction_date] # '3/14/2016 8:09:31 PM'
result[:amount] # '1.50'
FindBoardedCard
Retrieves the payment data stored inside the Merchantware Vault
result = @client.find_boarded_card({ vault_token: '127MMEIIQVEW2WSZECPL' })
result[:card_number] # '0026'
result[:expiration_date] # '1218'
result[:card_type] # '4'
result[:avs_street_address] # '1 Federal Street'
result[:avs_zip_code] # '02110'
UpdateBoardedCard
Changes the expiration date for an existing payment method stored inside the Merchantware Vault
result = @client.update_boarded_card({
token: '127MMEIIQVEW2WSZECPL',
expiration_date: '0118'
})
result[:vault_token] # '127MMEIIQVEW2WSZECPL'
ForceCapture
Forces a charge to be issued upon a customer’s credit card
result = @client.force_capture(
{
source: 'Keyed',
card_number: '4012000033330026',
expiration_date: '1218',
card_holder: 'John Doe'
}, {
amount: '3.06',
authorization_code: 'V00546C',
invoice_number: '1559',
register_number: '35',
merchant_transaction_id: '168901',
card_acceptor_terminal_id: '3',
ecommerce_transaction_indicator: nil
}
)
result[:approval_status] # 'APPROVED'
result[:token] # '608962'
result[:authorization_code] # 'V00546C'
result[:transaction_date] # '3/14/2016 8:11:01 PM'
result[:amount] # '3.06'
result[:card_number] # '************0026'
result[:cardholder] # 'John Doe'
result[:card_type] # '4'
Refund
Issues a credit card refund to a customer.
result = @client.refund(
{
source: 'Keyed',
card_number: '4012000033330026',
expiration_date: '1218',
card_holder: 'John Doe'
}, {
amount: '4.01',
invoice_number: '1701',
register_number: '35',
merchant_transaction_id: '165901',
card_acceptor_terminal_id: '3',
ecommerce_transaction_indicator: nil
}
)
result[:approval_status] # 'APPROVED'
result[:token] # '608963'
result[:transaction_date] # '3/14/2016 8:12:50 PM'
result[:amount] # '4.01'
result[:card_number] # '************0026'
result[:cardholder] # 'John Doe'
result[:card_type] # '4'
Sale
Charges a credit or debit card
result = @client.sale(
{
source: 'Keyed',
card_number: '4012000033330026',
expiration_date: '1218',
card_holder: 'John Doe',
avs_street_address: '1 Federal Street',
avs_zip_code: '02110',
card_verification_value: '123'
}, {
amount: '1.05',
cashback_amount: '0.00',
surcharge_amount: '0.00',
tax_amount: '0.00',
invoice_number: '1556',
purchase_order_number: '17801',
customer_code: '20',
register_number: '35',
merchant_transaction_id: '166901',
card_acceptor_terminal_id: '3',
enable_partial_authorization: 'False',
force_duplicate: 'False',
ecommerce_transaction_indicator: nil
}
)
result[:approval_status] # 'APPROVED'
result[:token] # '608957'
result[:authorization_code] # 'OK775C'
result[:transaction_date] # '3/14/2016 7:57:22 PM'
result[:amount] # '1.05'
result[:card_number] # '************0026'
result[:cardholder] # 'John Doe'
result[:card_type] # '4'
result[:avs_response] # 'Y'
SettleBatch
Batches out a merchant’s outstanding transactions for settlement.
result = @client.settle_batch
result[:batch_status] # 'SUCCESS'
result[:authorization_code] # '0314160001'
result[:batch_amount] # '2.19'
result[:transaction_count] # '8'
result[:transaction_date] # '3/14/2016 8:28:30 PM'
UnboardCard
Removes existing payment information from the Merchantware Vault
result = @client.unboard_card({ vault_token: "MYTOKENVALUEX" })
result[:vault_token] # 'MYTOKENVALUEX'
Void
Voids a prior unsettled transaction
result = @client.void({
token: "608973",
register_number: '35',
merchant_transaction_id: '167901',
card_acceptor_terminal_id: '3'
})
result[:approval_status] # 'APPROVED'
result[:token] # '608974'
result[:authorization_code] # 'VOID'
result[:transaction_date] # '3/14/2016 8:30:18 PM'
All Credit transactions are supported. Check and GiftCard transactions coming soon. Cayan Merchantware API Docs
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/cohubinc/cayan-ruby.
Disclaimer
This software is not developed by or supported by Cayan & TSYS.