{"id":15580909,"url":"https://github.com/nbulaj/alpha_card","last_synced_at":"2025-07-04T17:40:13.560Z","repository":{"id":62553226,"uuid":"21196131","full_name":"nbulaj/alpha_card","owner":"nbulaj","description":"A Ruby / JRuby / Rails gem for integrating with Alpha Card Services","archived":false,"fork":false,"pushed_at":"2019-06-26T10:45:39.000Z","size":258,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-24T01:17:55.460Z","etag":null,"topics":["alpha-card","jruby","payment-gateway","ruby","sales"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nbulaj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-25T08:41:41.000Z","updated_at":"2019-06-26T10:45:41.000Z","dependencies_parsed_at":"2022-11-03T04:30:33.058Z","dependency_job_id":null,"html_url":"https://github.com/nbulaj/alpha_card","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbulaj%2Falpha_card","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbulaj%2Falpha_card/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbulaj%2Falpha_card/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbulaj%2Falpha_card/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nbulaj","download_url":"https://codeload.github.com/nbulaj/alpha_card/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242627302,"owners_count":20160260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpha-card","jruby","payment-gateway","ruby","sales"],"created_at":"2024-10-02T19:40:38.573Z","updated_at":"2025-03-09T00:32:36.623Z","avatar_url":"https://github.com/nbulaj.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby lib for creating payments with Alpha Card Services\n[![Gem Version](https://badge.fury.io/rb/alpha_card.svg)](http://badge.fury.io/rb/alpha_card)\n[![Build Status](https://travis-ci.org/nbulaj/alpha_card.svg?branch=master)](https://travis-ci.org/nbulaj/alpha_card)\n[![Code Climate](https://codeclimate.com/github/nbulaj/alpha_card/badges/gpa.svg)](https://codeclimate.com/github/nbulaj/alpha_card)\n[![Coverage Status](https://coveralls.io/repos/github/nbulaj/alpha_card/badge.svg)](https://coveralls.io/github/nbulaj/alpha_card)\n[![Inline docs](http://inch-ci.org/github/nbulaj/alpha_card.png?branch=master)](http://inch-ci.org/github/nbulaj/alpha_card)\n[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg)](#license)\n\nThis gem can help your Ruby, JRuby or Ruby on Rails application to integrate with Alpha Card Service, Inc.\n\nAlpha Card Services: \nhttp://www.alphacardservices.com/\n\nPayment Gateway Integration Portal:\nhttps://secure.alphacardgateway.com/merchants/resources/integration/integration_portal.php\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Alpha Card Objects \u0026 Transactions](#alpha-card-objects--transactions)\n  - [Order](#order)\n    - [Billing](#billing)\n    - [Shipping](#shipping)\n  - [Sale](#sale)\n  - [Refund](#refund)\n  - [Void](#void)\n  - [Capture](#capture)\n  - [Update](#update)\n  - [Authorization](#authorization)\n  - [Credit](#credit)\n  - [Validate](#validate)\n- [Example of usage](#example-of-usage)\n- [AlphaCard Response](#alphacard-response)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nIf using bundler, first add 'alpha_card' to your Gemfile:\n\n```ruby\ngem 'alpha_card', '~\u003e 0.4'\n```\n\nAnd run:\n\n```sh\nbundle install\n```\n\nOtherwise simply install the gem:\n\n```sh\ngem install alpha_card -v '0.4'\n```\n\nDependencies required:\n\n*  ruby \u003e= 2.2.2 or [jruby](https://github.com/jruby/jruby) \u003e= 9.0.5.0;\n\n## Configuration\n\nIn order to use Alpha Card Gateway API you need to have a Merchant account credentials such as `username` and `password`.\n\nIf your project will always use only one account for processing payments, then you can configure gem as follows:\n\n```ruby\nAlphaCard::Account.username = 'username'\nAlphaCard::Account.password = 'password'\n```\n\nIn Rails applications you can create an initializer:\n\n```ruby\n# config/initializers/alpha_card.rb\nif Rails.env.test? || Rails.env.ci?\n  AlphaCard::Account.use_demo_credentials!\nelse\n  AlphaCard::Account.username = 'username'\n  AlphaCard::Account.password = 'password'\nend\n```\n\nAnother 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):\n\n```ruby\nvoid = AlphaCard::Void.new(transaction_id: '312110')\nvoid.process(username: 'demo', password: 'demo')\n```\n\n## Alpha Card Objects \u0026 Transactions\n\nAlpha Card operates with next objects:\n\n*  [Order](#order)\n    - [Billing](#billing)\n    - [Shipping](#shipping)\n*  [Sale](#sale)/[Authorization](#authorization)/[Credit](#credit)/[Validate](#validate)\n*  [Refund](#refund)\n*  [Void](#void)\n*  [Capture](#capture)\n*  [Update](#update)\n\nLet us consider each of them.\n\n### Order\n\nOrder represents itself.\n\n_Optional attributes_:\n\n*  id : `String`\n*  description : `String`\n*  po_number : `String`\n*  tax : `String`\n*  ip_address : `String` (format: `xxx.xxx.xxx.xxx`)\n*  billing : `AlphaCard::Billing`\n*  shipping : `AlphaCard::Shipping`\n\n_Constructor_:\n\n```ruby\nAlphaCard::Order.new(property: value, ...)\n```\n\n### Billing\n\nSpecify Billing information for Order.\n\n_Optional attributes_:\n\n*  first_name : `String`\n*  last_name : `String`\n*  email : `String`\n*  fax : `String`\n*  phone : `String`\n*  company : `String`\n*  address_1 : `String`\n*  address_2 : `String`\n*  city : `String`\n*  state : `String` (format: `CC`)\n*  zip : `String`\n*  country : `String` (format: `CC`. Country codes are as shown in [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166))\n*  website : `String`\n\n_Constructor_:\n\n```ruby\nAlphaCard::Billing.new(property: value, ...)\n```\n\n### Shipping\n\nContains Shipping information for the Order.\n\n_Optional attributes_:\n\n*  first_name : `String`\n*  last_name : `String`\n*  company : `String`\n*  address_1 : `String`\n*  address_2 : `String`\n*  city : `String`\n*  state : `String` (format: `CC`)\n*  zip_code : `String`\n*  country : `String` (format: `CC`. Country codes are as shown in [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166))\n*  email : `String`\n\n_Constructor_:\n\n```ruby\nAlphaCard::Shipping.new(property: value, ...)\n```\n\n### Sale\n\nSale transaction is the main object of the Alpha Card Services. It is used to processed common payments for orders.\n\n_Required attributes_:\n\n*  card_expiration_date : `String` (format: `MMYY`)\n*  card_number : `String`\n*  amount : `String` (format: `x.xx`)\n\n_Optional attributes_:\n\n*  cvv : `String`\n*  payment : `String` (default: `'creditcard'`, values: `'creditcard'` or `'check'`)\n*  customer_receipt : `String` (values `'true'` or `'false'`)\n*  check_name : `String`\n*  check_aba : `String`\n*  check_account : `String`\n*  account_holder_type : `String` (values: `'business'` or `'personal'`)\n*  account_type : `String` (values: `'checking'` or `'savings'`)\n*  sec_code : `String` (values: `'PPD'`, `'WEB'`, `'TEL'`, or `'CCD'`)\n\n_Constructor_:\n\n```ruby\nAlphaCard::Sale.new(property: value, ...)\n```\n\nTo create the payment you must call *create(_alpha_card_order_)* method:\n\n```ruby\n# ...\nsale = AlphaCard::Sale.new(amount: 10)\nresponse = sale.process(order)\n\n# =\u003e #\u003cAlphaCard::Response:0x1a0fda ...\u003e\n```\n\n### Refund\n\nRepresents refund transaction.\n\n_Required attributes_:\n\n*  transaction_id : `String` or `Integer`\n\n_Optional attributes_:\n\n*  amount : `String` (format: `x.xx`)\n\n_Constructor_:\n\n```ruby\nAlphaCard::Refund.new(property: value, ...)\n```\n\nTo create the refund transaction you must call *create* or *process* method:\n\n```ruby\n# ...\nrefund = AlphaCard::Refund.new(transaction_id: '12312312', amount: 10)\nrefund.process\n```\n\n### Void\n\nRepresents void transaction.\n\n_Required attributes_:\n\n*  transaction_id : `String` or `Integer`\n\n_Constructor_:\n\n```ruby\nAlphaCard::Void.new(property: value, ...)\n```\n\nTo create the void transaction you must call *create* or *process* method:\n\n```ruby\n# ...\nvoid = AlphaCard::Void.new(transaction_id: '12312312')\nvoid.create\n```\n\n### Capture\n\nRepresents capture transaction.\n\n_Required attributes_:\n\n*  transaction_id : `String` or `Integer`\n*  amount : `String` (format: `xx.xx`)\n\n_Optional attributes_:\n\n*  tracking_number : `String`\n*  shipping_carrier : `String`\n*  order_id : `String`\n\n_Constructor_:\n\n```ruby\nAlphaCard::Capture.new(property: value, ...)\n```\n\nTo create the capture transaction you must call *create* or *process* method:\n\n```ruby\n# ...\ncapture = AlphaCard::Capture.new(transaction_id: '12312312', amount: '5.05')\ncapture.create\n```\n\n### Update\n\nRepresents update transaction.\n\n_Required attributes_:\n\n*  transaction_id : `String` or `Integer`\n\n_Optional attributes_:\n*  shipping: `String`\n*  shipping_postal: `String`\n*  ship_from_postal: `String`\n*  shipping_country: `String` \n*  shipping_carrier: `String` (values: `'ups'`, `'fedex'`, `'dhl'` or `'usps'`)\n*  shipping_date: `String` (format: `YYYYMMDD`)\n*  order_description: `String`\n*  order_date: `String`\n*  customer_receipt: `String` (values: `'true'` or `'false'`)\n*  po_number: `String`\n*  summary_commodity_code: `String`\n*  duty_amount: `String` (format: `x.xx`)\n*  discount_amount: `String` (format: `x.xx`)\n*  tax: `String` (format: `x.xx`)\n*  national_tax_amount: `String` (format: `x.xx`)\n*  alternate_tax_amount: `String` (format: `x.xx`)\n*  alternate_tax_id: `String`\n*  vat_tax_amount: `String`\n*  vat_tax_rate: `String`\n*  vat_invoice_reference_number: `String`\n*  customer_vat_registration: `String`\n*  merchant_vat_registration: `String`\n\n_Constructor_:\n\n```ruby\nAlphaCard::Update.new(property: value, ...)\n```\n\nTo create update transaction you must call *create* or *process* method:\n\n```ruby\n# ...\nupdate = AlphaCard::Update.new(tax: '10.02', shipping_carrier: 'ups', transaction_id: '66928')\nupdate.process\n```\n\n### Authorization\n\nHas the same attributes and methods as `Sale` transaction.\n\n### Credit\n\nHas the same attributes and methods as `Sale` transaction.\n\n### Validate\n\nHas the same attributes and methods as `Sale` transaction, except `amount` — there is no need in it.\n\n## Example of usage\n\nCreate AlphaCard sale (pay for the order):\n\n```ruby\nrequire 'alpha_card'\n\ndef create_payment\n  # Setup merchant account credentials\n  AlphaCard::Account.username = 'demo'\n  AlphaCard::Account.password = 'password'\n\n  billing = AlphaCard::Billing.new(email: 'test@example.com', phone: '+801311313111')\n  shipping = AlphaCard::Shipping.new(address_1: '33 N str', city: 'New York', state: 'NY', zip_code: '132')\n\n  order = AlphaCard::Order.new(id: 1, description: 'Test order', billing: billing, shipping: shipping)\n\n  # Format of the amount: \"XX.XX\"\n  sale = AlphaCard::Sale.new(card_expiration_date: '0117', card_number: '4111111111111111', amount: '1.50', cvv: '123')\n  response = sale.create(order)\n  #=\u003e #\u003cAlphaCard::Response:0x1a0fda ...\u003e\n\n  if response.success?\n    puts \"Order payed successfully: transaction ID = #{response.transaction_id}\"\n    true\n  else\n    puts \"Error message: #{e.response.message}\"\n    puts \"CVV response: #{e.response.cvv_response}\"\n    puts \"AVS response: #{e.response.avs_response}\"\n    false\n  end\n\n  rescue AlphaCard::APIConnectionError =\u003e e\n    puts \"Connection problems: #{e.message}\"\n    false\nend\n```\n\n`Billing` and `Shipping` is an _optional_ parameters and can be not specified.\n\n_Note_: take a look at the `amount` of the Order. It's format must be 'xx.xx'. All the information about variables formats \ncan be found on _Alpha Card Payment Gateway Integration Portal_ -\u003e _Direct Post API_ -\u003e _Documentation_ -\u003e _Transaction Variables_\n\nTo simulate request that returns an error do the next:\n\n*  to cause a declined message, pass an amount less than 1.00;\n*  to trigger a fatal error message, pass an invalid card number;\n*  to simulate an AVS match, pass 888 in the address1 field, 77777 for zip;\n*  to simulate a CVV match, pass 999 in the cvv field.\n\n## AlphaCard Response\n\n`AlphaCard::Response` contains all the necessary information about Alpha Card Gateway response. You can use the following API:\n\n*  `.text` — textual response of the Alpha Card Gateway;\n*  `.message` — response message be response code;\n*  `.transaction_id` — payment gateway transaction ID;\n*  `.order_id` — original order ID passed in the transaction request;\n*  `.code` — numeric mapping of processor responses;\n*  `.auth_code` — transaction authorization code;\n*  `.success?`, `.error?`, `.declined?` — state of the request;\n*  `.cvv_response` — CVV response message;\n*  `.avs_response` — AVS response message.\n\n## Testing\n\nIt 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:\n\n```ruby\nAlphaCard::Account.use_demo_credentials!\n```\n\nOr you can pass the next credentials with any request: `{ username: 'demo', password: 'password' }`\n\n## Contributing\n\nYou are very welcome to help improve alpha_card if you have suggestions for features that other people can use.\n\nTo contribute:\n\n1. Fork the project.\n2. Create your feature branch (`git checkout -b my-new-feature`).\n3. Implement your feature or bug fix.\n4. Add documentation for your feature or bug fix.\n5. Run \u003ctt\u003erake doc:yard\u003c/tt\u003e. If your changes are not 100% documented, go back to step 4.\n6. Add tests for your feature or bug fix.\n7. Run `rake` to make sure all tests pass.\n8. Commit your changes (`git commit -am 'Add new feature'`).\n9. Push to the branch (`git push origin my-new-feature`).\n10. Create new pull request.\n\nThanks.\n\n## License\n\nAlpha Card gem is released under the [MIT License](http://www.opensource.org/licenses/MIT).\n\nCopyright (c) 2014-2017 Nikita Bulai (bulajnikita@gmail.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbulaj%2Falpha_card","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnbulaj%2Falpha_card","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbulaj%2Falpha_card/lists"}